紙芝居アプリ 3.2 ソフトウェアメンテナンスガイド

管理範囲と責務を理解する

本体リポジトリが管理するものは次のとおりです。

• 物語固有の台本やアセットを含まない、汎用の紙芝居アプリ
• アプリSB3の展開ソースと、配布用SB3を生成する設定
• 台本と画像・音声をSB3へ組み込むnpmパッケージ
• アプリ・文書・サンプルへの公開入口と配布用SB3
• 上記を検証する自動テスト

文書リポジトリは、一般向け、DSL作成者向け、開発者向け、体験会向けの文書ソース、 共有画像、Vivliostyleビルド、PDF、文書Pagesを管理します。

関連プロジェクトとの境界は次のとおりです。

公開サンプル の固有ファイルを本体へコピーしません。本体の汎用性と、サンプルの独立した更新・配布を 維持します。

依存バージョン、スクリプト、公開対象の正本はpackage.jsonとpnpm-lock.yamlです。 文書には特定コミットを転記せず、必要なときに確認します。

pnpm why @kubohiroya/sb3-toolchain
git diff -- package.json pnpm-lock.yaml

開発環境を準備する

corepack enable
pnpm install

pnpm install --frozen-lockfile

pnpm sb3:check
pnpm test

リポジトリ構成を把握する

文書リポジトリでは、読者別のdocs/user-guides/、docs/dsl-author-guides/、 docs/developer-guides/、開催日別のdocs/workshops/をソースとし、scripts/で 全文書のHTMLと、docs/workshops/配下の体験会資料だけのPDFを生成します。

次の場所は生成物であり、Git管理上の正本ではありません。

文書リポジトリのdist/は文書Pages、output/pdf/は印刷用PDFのローカル確認先です。

共通の開発フローに従う

すべての変更はGitHub Issueへ受け入れ基準とロールバック手順を記録し、小さなブランチと PRへ分けます。

1. 最新のmainから作業ブランチを作る。
2. pnpm install --frozen-lockfileで依存を復元する。
3. 変更対象に近いテストを先に実行する。
4. 生成物ではなく正本を変更する。
5. 差分と生成結果を確認する。
6. 標準チェックと必要な手動確認を行う。
7. Issueの運用ログとDoDを更新してPRを作成する。

無関係な変更や未追跡ファイルをまとめてコミットしません。SB3の取り込みや成果物の 置換を行う前には、必ずgit statusと対象パスの差分を確認します。変更対象ごとの テストと公開前チェックは「変更を検証する」を 参照してください。

成果物プロファイルを理解する

紙芝居の成果物は、台本と物語固有アセットをどこに保持するかで分けます。

genericはapp/から生成し、特定の物語を含めません。ビルダーAPIとCLIが受け付ける profileはeditorまたはplayerです。

editorとplayerは同じベースSB3、台本、アセットロックから生成します。両者の 変換済み台本とアセット参照を分岐させません。playerは組み込み台本を予約変数へ保存し、 タイトル操作後にファイル選択なしで開始します。

playerへ台本とアセットを組み込んでも、TurboWarp TMモデル、カメラ、外部サービスまで 自動的にオフライン化されるわけではありません。残るオンライン依存は成果物マニフェストと 公開ページへ明記します。

SB3・台本変換ビルダーを利用する

この章はビルダー利用者に対する外部契約を示します。ビルダーの実装を変更する手順は 「ビルダーの実装を変更する」を 参照してください。汎用アプリSB3の内部構造は本章の対象外です。

npm view @kubohiroya/tm-kamishibai version
pnpm add --save-exact @kubohiroya/tm-kamishibai@<VERSION>

pnpm exec tm-kamishibai build-sb3 \
  --base kamishibai.sb3 \
  --script source.txt \
  --assets assets.lock.json \
  --output dist/sample \
  --profile editor

dist/sample.sb3
dist/sample.txt
dist/sample.manifest.json

import {
  Sb3BuilderError,
  buildSb3Bundle,
  validateAssetManifest,
  validateBundle,
} from '@kubohiroya/tm-kamishibai/builder';

const result = await buildSb3Bundle({
  baseSb3: 'kamishibai.sb3',
  sourceScript: 'source.txt',
  assetManifest: 'assets.lock.json',
  outputDirectory: 'dist',
  outputName: 'sample',
  profile: 'editor',
});

console.log(result.outputPaths);

{
  "formatVersion": 1,
  "assets": [
    {
      "name": "forest",
      "uri": "file:assets/forest.svg",
      "kind": "backdrop",
      "target": "@stage",
      "sb3Name": "森",
      "contentType": "image/svg+xml",
      "dataFormat": "svg",
      "size": 1234,
      "sha256": "<64文字の16進数>",
      "license": "CC-BY-4.0: https://creativecommons.org/licenses/by/4.0/",
      "metadata": {
        "bitmapResolution": 1,
        "rotationCenterX": 240,
        "rotationCenterY": 180
      }
    }
  ]
}

アプリSB3を変更する

このリポジトリではapp/をアプリSB3の正本とし、固定したsb3-toolchainを pnpm sb3:*スクリプトから利用します。展開ソース形式、取り込みとビルドの上書き保護、 決定的出力の共通仕様は sb3-toolchainのSB3ソース管理ワークフロー を参照してください。 CIも依存関係の導入直後にpnpm sb3:checkを実行するため、ローカル開発、テスト、 配布ビルドで同じコミット固定のツールチェインを利用します。

app/から編集用SB3を生成します。

pnpm sb3:build

生成時に、Title背景のVersion <version> (YYYY/MM/DD)へpackage.jsonの バージョンとAsia/Tokyoのビルド日を自動で埋め込みます。同時に、公式Webサイトボタンへ Webサイトのブランド画像の正本であるsite/favicon.pngを埋め込みます。app/には プレースホルダーを保持し、一時ソースで2つのSVGの内容、MD5、assetId、md5ext、 書庫のエントリーを同時に更新するため、ビルドで正本は変更されません。

過去のリリースを同じ日付で再現するときは、日付をYYYY-MM-DDで明示します。不正な 日付はエラーにし、暗黙に補正しません。

KAMISHIBAI_BUILD_DATE=2026-07-31 pnpm sb3:build

tmp/kamishibai.sb3をTurboWarpで編集し、別の明示的なパスへ保存してから取り込みます。

pnpm sb3:import -- /path/to/edited-kamishibai.sb3
git diff -- app
pnpm sb3:check
pnpm test
pnpm run build

app/project.source.jsonは次の不変条件を維持します。

• 浦島太郎などの公開サンプル固有ターゲット、画像、音声を含めない
• 台本解析・実行用リストを空の初期状態で保持する
• 組み込み台本用の予約変数を一意に保持する

展開形式とアセット・拡張の整合性はpnpm sb3:checkで検証します。ツールチェインの共通 検証項目を本ガイドへ重複して列挙しません。

DSL、Loading表示、入力、分岐、テキスト、画面遷移などの振る舞いを変更するときは、 同じPRでDSL資料、コマンド資料、 内部仕様書、VMまたはブロック構造のテストを更新します。

埋め込み機能拡張を更新する

app/extensions/のJavaScriptは同期済み成果物です。バグ修正や機能追加は、 app/embedded-extensions.jsonに記録された上流リポジトリまたはnpmパッケージで行い、レビュー済みの 成果物だけを本リポジトリへ取り込みます。source.providerがnpmの場合はパッケージ名、完全固定バージョン、 artifact path、integrityを記録し、パッケージマネージャーが導入した内容から同期します。アプリ側に パッケージ固有のコピーscriptを追加しません。この取得・検証・同期はsb3-toolchainの責務です。

status、sync、updateの意味、由来情報の形式、一括の更新、ID移行の 対象schemaは、sb3-toolchainのSB3ソース管理ワークフローと 埋め込み拡張IDの移行 を正本とします。ここでは紙芝居アプリへ反映する手順だけを示します。

pnpm sb3:extensions:status
pnpm sb3:extensions:sync
pnpm sb3:extensions:update -- EXTENSION_ID

上流で拡張IDが変更された場合は、ツールチェインのID移行を伴う更新を使います。

pnpm sb3:extensions:update -- OLD_ID --migrate-id NEW_ID

GitHub提供元で上流の成果物パスも変わった場合だけ--artifact PATHを追加します。npm提供元では、 先にパッケージマネージャーで依存バージョンを更新してからstatusまたはupdateを実行します。更新後は必ず git diff -- app、pnpm sb3:check、pnpm test、pnpm run buildを確認し、 生成したSB3をTurboWarpで開いて対象拡張の主要機能を確認します。

ビルダーの実装を変更する

公開APIはsrc/builder/index.js、CLIはsrc/builder/cli.jsとbin/、仕様テストは test/builder.test.mjsにあります。公開API、CLI、アセットマニフェスト、決定的生成、 一括更新の現行仕様は 「SB3・台本変換ビルダーを利用する」を 参照してください。この章では仕様そのものを繰り返さず、実装変更時の確認事項だけを 扱います。

APIまたはCLIを変更するときは次を同じ変更に含めます。

• API入力、返り値、エラーの後方互換性の判断
• CLIの--helpと引数検証
• アセットマニフェストと出力マニフェストの形式
• 決定的生成と一括更新のテスト
• 内部仕様書のAPI／CLI例
• 破壊的変更の場合は新しいメジャーバージョン

node --test test/builder.test.mjs
node bin/tm-kamishibai.mjs --help
pnpm typecheck
pnpm pack:check

ドキュメントとサイトを変更する

一般文書と体験会資料は文書リポジトリ、アプリの公開入口は本体リポジトリのsite/を 正本とします。文書リポジトリでは次を利用します。

DOCUMENT_SOURCE=user-guide.md pnpm run preview:document
pnpm run preview:workshop
pnpm run preview:staff

子供向け概要書と参加者向け体験会資料だけにrubyganaを適用します。確認する学年を 変更する場合は1から6を指定します。

RUBYGANA_GRADE=4 pnpm run build

文書リポジトリのpnpm run buildは一般文書ごとにWeb Publicationを構築し、 Vivliostyle CLIのtoc設定で h2・h3までを含む目次を生成します。生成後処理で通常HTMLのindex.htmlへ本文と目次を 統合し、目次を固定・展開可能な階層ツリーにします。Vivliostyle Viewerのreading orderには document.htmlだけを残すため、同じ本文を二重に表示しません。目次をMarkdownへ重複して 記述しません。

参加者向け体験会資料では、Viewer／PDF用のcover.html、toc.html、本文HTMLを保ったまま、 3つのbodyを画面用index.htmlへ統合します。スタッフ向け体験会資料では、本文HTMLの見出しから 画面用の階層目次を作り、本文と同じindex.htmlへ統合します。スタッフ向けViewerとPDFは document.htmlだけを使用するため、画面用目次によってPDFのページ構成は変わりません。 一般文書と両体験会資料はdocument-toc.cssとdocument-toc.jsを共有します。

HTML、Vivliostyle Viewer、体験会資料のPDF、文書横断目次、画像参照、しおり、 ライセンスをまとめて検証します。Markdownだけを確認して完了にせず、生成されたHTMLと、 docs/workshops/を変更した場合のPDFも確認します。

2回目以降のpnpm run buildは、出版物の種別に依存しない共通の増分ビルド処理で、 出版物ごとにMarkdown、参照画像、共通テーマ、フォント、Vivliostyle設定、ビルドスクリプトの 更新時刻を調べます。必要なHTML、体験会資料のPDF、build-info.jsonがすべて存在し、 生成物の最も古い更新時刻が入力の最も新しい更新時刻以後なら、その出版物のVivliostyle処理と 目次統合を省略します。同じ内容のアセットや後処理済みHTMLも再書き込みしません。生成だけを 実行する場合はpnpm run build:publications、全出版物を無条件に作り直す場合は pnpm run build:publications:full、検証まで含めて強制再生成する場合はpnpm run build:fullを 使用します。クリーンなチェックアウトで生成物が存在しないCIでは、通常のpnpm run buildでも 全出版物を生成します。

文書の変更が本体の実装変更を伴う場合は、2つのIssueとPRに依存関係を記録します。 文書ビルドが本体をチェックアウトしたり、本体ビルドが文書を生成したりする循環依存は作りません。

Markdownの見出しには章・節番号を書きません。h1は番号なしの文書名、h2とh3は 本文と目次で自動採番します。用語集などの前付けを採番しない場合は、見出しへ {.unnumbered}を付けます。本文から見出しを参照するときは、番号ではなく意味の変わらない IDを付けてリンクし、組版結果にも現在の章・節番号を表示する場合は、リンクへ {data-ref="chapter"}または{data-ref="section"}を付けます。

変更を検証する

pnpm lint
pnpm format
pnpm typecheck
pnpm test
pnpm run build

公開する

pnpm run deploy

pnpm release:check

npm publish --access public

npm view @kubohiroya/tm-kamishibai@<VERSION> \
  version license dist-tags.latest dist.integrity --json

開発上の問題を解決する

復旧でGit履歴を破壊しません。公開済み変更はgit revertまたは新しい修正PRで戻し、タグを 移動しません。

ライセンスと秘密情報を扱う

詳細はLICENSES.md、docs/LICENSE.md、 docs/workshops/LICENSE.mdを参照してください。

第三者の画像、音声、フォント、モデル、機能拡張には個別のライセンスまたは利用条件が適用されます。 ビルダーで組み込む素材はアセットマニフェストのlicenseへ由来を記録します。許諾が確認できない 素材を本体またはsampleへ追加しません。

token、npm認証情報、秘密鍵、個人情報をrepository、SB3、台本、マニフェスト、生成HTMLへ 記録しません。認証情報は環境変数、OSのkeychain、GitHub Secretsなど、公開物へ含まれない 仕組みで渡します。

関連プロジェクトを確認する

TM紙芝居の開発から分離し、他のTurboWarp作品や開発環境でも利用できるものを 各リポジトリで公開しています。各プロジェクトの仕様、開発手順、リリースはリンク先を 正本とします。

関連ドキュメントを確認する

• user-guide.md: アプリの利用方法と成果物の使い分け
• dsl-manual.md: 台本の構造と書き方
• command-reference.md: コマンドとアクションの仕様
• internal-specification.md: 汎用アプリSB3の内部構造、呼出し関係、状態遷移
• extension-guide.md: 依存機能拡張16個の一覧、図解、役割、利用箇所
• application-materials-guide.md: アプリ、浦島太郎、体験会教材、DSL 3.2、sb3-toolchainの8ページ概要
• history.md: DSLとアプリの変更履歴
• アプリrepository README: プロジェクト全体の入口と主要コマンド