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

このガイドの読み進め方

4.0の実装全体を初めて調べる場合は、先に アプリ・教材・ツールチェインガイドでprojectからruntimeまでの流れを 確認してください。本書はその全体像を、実際の変更・検証・リリース作業へ対応させる入口です。

本書を一度通読した後は、次の「最初に保守境界を判断する」を索引として使います。内部の型と状態遷移は 内部仕様書、外部パッケージとの接続は 機能拡張・プラットフォーム統合ガイド、失敗時の副作用禁止と停止順序は 台本診断・安全停止 設計レビューで深掘りします。

最初に保守境界を判断する

変更対象ごとの正本と、最初に確認する場所は次のとおりです。

Schema、source frontend、StoryDocument、runtimeを同時に変更する必要がある場合も、互換性の判断を一つの 大きな差分へ隠しません。Schemaとfixture、frontend、semantic validator、runtime、adapterの順に小さく分け、 各PRに受け入れ基準とrollbackを記録します。

規範Schemaとsource lockを守る

DSL 4.0の構造仕様は、本体リポジトリのschema/dsl-4.schema.jsonが規範です。runtime codeからSchemaを 生成しません。表層仕様、Schema、適合実装、testは同じ上流revisionで扱い、文書だけを別のrevisionへ 先行させません。

文書リポジトリは上流revisionを次の二つで固定します。

• sources/dsl4/source-lock.json: repository、コミット、Schema path、SHA-256、参照URL
• sources/dsl4/dsl-4.schema.json: 固定コミットから取得した規範Schemaのスナップショット

公開用docs/dsl-author-guides/dsl-4.0-schema-reference.mdは、このスナップショットと sources/dsl4/annotations.ja.jsonから決定的に生成します。生成Markdownやスナップショットを直接書き換えて 上流との差を隠してはいけません。

上流を更新するときだけ、文書リポジトリで次を実行します。

pnpm docs:dsl4:sync -- \
  --repository ../tm-kamishibai \
  --commit 29c0deadcb98badf94a0244c479ca896dc71f842
pnpm docs:dsl4:check
git diff -- \
  sources/dsl4/source-lock.json \
  sources/dsl4/dsl-4.schema.json \
  docs/dsl-author-guides/dsl-4.0-schema-reference.md

新しいコミットへ進める場合は--commitをその完成revisionへ置き換えます。同期後はSchema差分だけでなく、 表層仕様、fixture、frontend、runtime、release artifactが同じrevisionに含まれることを確認します。

開発環境を準備する

固定コミットの本体リポジトリはNode.js 22.12.0以上とpnpm 11、文書リポジトリはNode.js 24.0.0以上と pnpm 11を要求します。それぞれのrepository rootでロックファイルを使用して依存を復元します。

corepack enable
pnpm install --frozen-lockfile

本体リポジトリでは、最初に固定release sourceとquick suiteが正常であることを確認します。

pnpm sb3:dsl4-release:check
pnpm verify:quick

文書リポジトリでは、Schemaスナップショットと生成referenceの同期を確認します。

pnpm docs:dsl4:check
pnpm test

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

本体リポジトリのDSL 4.0保守領域は次のとおりです。

文書リポジトリでは、次の境界を保ちます。

dist/は両repositoryとも生成物です。変更の正本にせず、ビルド後の検査対象として扱います。

feature flagを起動時スナップショットとして扱う

DSL 4.0のflagはsrc/dsl4/feature-flags.jsで列挙し、dsl4DefaultFeatureFlagsではすべてfalseです。 resolveDsl4FeatureFlags()は起動時に未知keyと依存関係を検査し、deep freezeしたスナップショットを返します。 実行中にflag objectを変更して一部だけを切り替えません。

主な依存関係は次のとおりです。

• dsl4AppShellはdsl4Runtimeを必要とする
• dsl4SourceIncludesはdsl4Runtimeを必要とする
• dsl4WebPreviewAdapterはdsl4Runtimeとdsl4AppShellを必要とする
• dsl4WebPreviewAssetLiveReloadはruntime、app shell、Web Preview adapterを必要とする
• dsl4PreviewReloadOverlayはruntimeとapp shellを必要とする
• dsl4SpeechAdvanceTypewriterはruntimeを必要とする

build-dsl4とpreview-dsl4のSource Graph経路は--enable-source-includesを指定したときだけ有効になり、 source件数、graph合計byte数、include depthの有限上限も必須になります。問題を切り分ける場合はflagを既定OFFへ 戻し、単一sourceでruntime、adapter、artifactの基線を確認します。flagの既定値自体を文書変更と一緒に変えません。

projectとsource manifestを準備する

CLI previewとビルドは、project rootとroot直下のproject.source.jsonを明示的に受け取ります。新しいprojectは entry sourceをpathへ記録します。

{
  "formatVersion": 1,
  "mode": "external",
  "sourceId": "main",
  "path": "story.k4.yml"
}

pathを省略した場合だけstory.kamishibai.yamlを使用します。entryはroot直下のbasenameに限り、ディレクトリ、 絶対path、URI、..を受理しません。初回の正常なbuild-dsl4は、verified remote asset cacheを作品単位で 分離するcacheIdとcacheDatabaseNameをマニフェストへatomicに追記します。既存identityは台本名を変更しても 再生成しません。

validateを実行する

validate-dsl4はproductionと同じcanonicalizer、Schema、semantic validator、diagnostic modelで一つのYAMLを 検証します。--max-source-bytesを省略できません。pretty形式は人が読み、JSON形式はCIやeditorが処理します。

pnpm exec tm-kamishibai validate-dsl4 \
  --input project/story.k4.yml \
  --max-source-bytes 65536 \
  --format pretty

終了statusは、成功が0、source診断が1、optionや内部契約の問題が2です。JSON envelopeはsource text、AST、 端末の絶対pathを出力しません。

includeはJSON Schemaのfieldではなく、Schema検証前のSource Graph directiveです。そのため複数source全体は、 validate-dsl4へinclude付きentryを直接渡すのではなく、次節のpreview-dsl4またはbuild-dsl4で --enable-source-includesとgraph上限を指定して検証します。

CLI Previewを実行する

preview-dsl4 --watchはNode側でprojectを監視し、development-only browser runtimeをmemory内に構築します。 固定コミットの公開CLIでは、base SB3、project root、source manifest、control profile、channel、sourceとassetの 有限上限がすべて必須です。

pnpm exec tm-kamishibai preview-dsl4 \
  --watch \
  --base base.sb3 \
  --project-root project \
  --source-manifest project/project.source.json \
  --control-profile production \
  --channel bundled \
  --max-source-bytes 65536 \
  --max-asset-file-bytes 16777216 \
  --max-asset-files 64 \
  --max-total-asset-bytes 67108864 \
  --enable-source-includes \
  --max-source-files 32 \
  --max-total-source-bytes 262144 \
  --max-include-depth 8 \
  --port 0

includeを使わないprojectでは、--enable-source-includesと三つのgraph上限をまとめて外します。--port 0は OSに空いているloopback portを選択させます。hostは127.0.0.1または::1にだけbindし、許可originと one-use session tokenを検査します。CLIはbrowser runtime-ready acknowledgmentを受け取るまでreadyを表示しません。 SIGINT／SIGTERM、ブラウザー切断、full rebuild要求ではwatcher、transport、runtimeを有限時間で終了します。

YAMLだけの変更はcandidate generationとしてlive reloadします。base SB3、asset bundle、app shell、runtime、 ビルダー設定、source path／ID、control profileを含むartifact fingerprintが変わった場合は、部分reloadを続けず full rebuildとしてcommandを再起動します。

自己完結SB3をビルドする

配布candidateはbuild-dsl4で一つの.sb3へ出力します。次の例はSource Graphを有効にする場合の完全なCLI契約です。

pnpm exec tm-kamishibai build-dsl4 \
  --base base.sb3 \
  --project-root project \
  --source-manifest project/project.source.json \
  --output dist/story.sb3 \
  --control-profile production \
  --channel bundled \
  --max-source-bytes 65536 \
  --max-asset-file-bytes 16777216 \
  --max-asset-files 64 \
  --max-total-asset-bytes 67108864 \
  --enable-source-includes \
  --max-source-files 32 \
  --max-total-source-bytes 262144 \
  --max-include-depth 8

--channel bundledはproduction player／Packager、--channel unbundledはTurboWarp editorで使用する保存面です。 両channelは同じsource descriptorとintegrityを検証します。同じchannelのcomponentがbase SB3にある場合は既定で 拒否し、意図的に置き換えるときだけ--replace-existingを指定します。

ビルドは次の順序を一つのcandidateに対して行います。

1. project rootとsource manifestを検証し、entry sourceを二回安定取得する
2. Source Graphを使う場合は全nodeを有限上限内で読み、cycleと重複を診断してcomposeする
3. production frontendでcanonical sourceとdeep-frozen StoryDocumentを生成する
4. 宣言元sourceを基準にlocal assetを安定取得し、一つのasset snapshotを作る
5. source descriptor、runtime artifact、asset bundleをbase SB3へ格納する
6. memory内の生成projectをloaderで再検証する
7. disk candidateを再読込し、byte一致とruntime componentを再検証する
8. 成功した.sb3だけを出力先へatomicに設置する

失敗時は以前の出力を維持し、途中candidateを残しません。project.source.jsonへ初回cache identityを追記する場合も temporary fileからrenameします。

Source Graph transactionとimmutable snapshotを保つ

includeはentryから到達するsourceだけをdiscovery orderで読みます。source数、1 sourceのbyte数、graph合計byte数、 include depth、compose後byte数に独立した有限上限を適用します。絶対path、root外へのescape、シンボリックリンクによるescape、cycle、 同じnamespaceの同じID、kamishibai等の単一設定の重複はcandidateを実行する前に失敗します。

compose後はincludeを取り除いたcanonical sourceをfrontendへ渡し、StoryDocumentに各StoryPathのsourceIdと source rangeを保持します。local assetの相対pathはentryではなく宣言元sourceを基準に解決します。これにより、 included fileへ宣言を移動した場合も診断とasset参照を元のsourceへ戻せます。

Previewでは、entry pathとdiscovery order内の全canonical sourceからgeneration identityを作ります。一つでも 読込中に変化した場合、古いgenerationと新しいgenerationを混ぜません。frontend結果とStoryDocumentはdeep freezeし、 runtimeやadapterが正規化済みtreeを直接書き換えないようにします。

live reloadは次の境界で行います。

1. 新しいsource resultをstageし、無効なら現在のruntimeを維持して診断だけを更新する
2. 有効なcandidateでは現在actionをquiesceし、再開可能なscene／actionと変数スナップショットを得る
3. reload planと作者の再開選択を確定する
4. 新sessionを開始してcandidateをcommitする
5. コミット成功後にだけ旧sessionをdisposeする
6. quiesce、start、コミットが失敗した場合はcandidateを破棄し、可能なら旧sessionをresumeする

asset reloadもprepare、activate、acknowledge、旧generationのreleaseの順でtransactionを行います。ただし、source保存と 複数asset保存を一つのfilesystem transactionに束ねるatomicityは保証しません。各スナップショットが安定するまで待ち、source generationとasset generationを混同しないことが重要です。

browser adapterとCLI adapterの責務を分ける

Browser PreviewとCLI Previewはproduction source frontend、generation protocol、runtime componentを共有しますが、 I/Oの所有者は分けます。

platform coreはfilesystem、DOM、カメラ、TurboWarp VMへ直接依存しません。src/dsl4/platform/のportへactor、media、 SVG Text、pose、asset lifecycleを注入し、browser-turbowarp-platform.jsでブラウザー実装をcomposeします。platform APIを 変更した場合はcore unit testだけでなく、browser fixtureとadapter contractを実行します。

変更対象別の検証matrix

変更したpathに対応する行をすべて実行し、最後に標準checkへ合流します。

本体リポジトリの最終回帰は次です。

pnpm verify:full

固定コミットでは、このcommandがsb3:check、lint、format、typecheck、full test、E2E、siteビルド、 pack:checkを順に実行します。失敗した工程をIssueの運用ログへblocked:として記録し、合格するまでリリースへ 進みません。

リリースを作成する

公開前のcandidate固定、Browser／CLI Preview、production SB3／Web版、実カメラ・実ポーズ、release-stop、 証跡の保存はDSL 4.0 release smokeを正本とします。本節はrelease sourceを作る順序、 同書は作成したcandidateを公開してよいか判定する手順を担当します。

DSL 4.0 Standard Runtimeは、source-composedされたkubohiroyakamishibairuntime4と、完全固定したcapability パッケージから作ります。rc.8ではタグ、release-metadata/4.0.0-rc.8.json、GitHub Releaseの kamishibai-4.0.0-rc.8.sb3を不変の公開記録として管理します。現行branchへ展開済みrelease sourceを重複保持しません。 composite IDはkubohiroyakamishibai4で、23個のcore actionは 可視blockとして、4個の内部制御blockは非表示で登録されます。

リリースは次の順で行います。

1. capabilityパッケージを各repositoryで検証してリリースする
2. 本体のpackage.jsonとpnpm-lock.yamlをexactなバージョンとintegrityへ更新する
3. LICENSES.mdのattributionとパッケージのprovenanceを同期する
4. Standard Runtime ID、23個の可視core action、4個の非表示制御、remote code禁止をcontract testで確認する
5. pnpm verify:fullを完走する
6. release-metadata/<version>.jsonをcandidateとして作り、source identityと成果物を生成する
7. source identityと成果物が正本と一致することをpnpm release:dsl4:checkで確認する
8. scripts/download-catalog.mjsのバージョン、sourceCommit、buildDate、SHA-256を更新する
9. pnpm release:dsl4:freezeでタグ対象のコミットとartifactを固定する
10. pnpm release:checkでnpm 公開内容をdry runする
11. GitHub Actions、download、パッケージ、Pagesの公開結果を確認してからIssueを完了する

rc.8のrelease metadataと成果物を検査するcommandは次です。公開済みartifactを再生成して差し替えません。

pnpm release:dsl4:check
pnpm verify:full
pnpm release:check
git diff --exit-code -- release-metadata/4.0.0-rc.8.json

安定版へ進める場合は、generator内のリリース ディレクトリ、パッケージ バージョン、download catalogを同じバージョンへ更新して から実行します。既存バージョンのrelease sourceやcatalog checksumを、異なるbyte列のまま再利用しません。

PRには少なくとも次を記録します。

• 上流コミットと変更したSchema／source／adapter path
• 実行したtargeted testとpnpm verify:fullの結果
• kamishibai-4.0.0-rc.8.sb3のSHA-256とsource identity
• Browser／CLI Preview、カメラ、pose、offline smokeの対象
• feature flagの既定値とrollback方法
• パッケージ、artifact、Pagesの公開順

rollbackする

公開前に検証が失敗した場合は、新しいartifactを公開しません。package／lock pin、release source、download catalogを 直前のコミットへ戻し、feature flagを既定OFFにした状態でpnpm verify:fullを再実行します。

公開後に問題が見つかった場合は、次の順で影響を止めます。

1. 問題のあるsurfaceのflagを起動時スナップショットでOFFにする
2. npmのnextを直前版へ戻し、PagesとGitHub prereleaseへ注意事項を追加する
3. パッケージとロックファイルを直前のexact pinへ戻す
4. 公開済みrc.8は上書きせず、修正版を新しいバージョンとしてビルドする
5. pnpm verify:fullと代表smokeを再実行する
6. Pagesを再公開し、Issueとrelease noteへ影響範囲を記録する

npmへ公開済みのversionは上書きせず、必要に応じてdeprecateと修正版バージョンを使用します。Source Graphだけを止める 場合はdsl4SourceIncludesをOFFにし、--enable-source-includesを外した単一source経路へ戻します。Browser Previewの 問題ではpreview adapterをOFFにしても、検証済み自己完結SB3のproduction runtimeを同時に変更しません。

文書だけをrollbackする場合は、本書のMarkdown、docs/config.mjsの4.0 publication、site/4.0/index.htmlのカード、 対応する回帰testだけをrevertします。他の4.0文書と固定Schemaスナップショットは残します。

完了条件

DSL 4.0の保守変更は、次をすべて満たしたときに完了です。

• 規範Schema、source lock、実装コミットの関係が説明できる
• 変更したpathから必要なunit、contract、ブラウザー、artifact testを特定して実行した
• Source Graphの有限上限、source origin、transaction、immutable generationを壊していない
• Browser Preview、CLI Preview、production runtimeの所有境界を混ぜていない
• local embedded assetを含む自己完結SB3を再読込して検証した
• remote assetを使う場合はoffline境界とintegrity検証を明記した
• feature flagは既定OFFで、起動時スナップショットとrollbackを確認した
• pnpm verify:full、release candidateのchecksum、代表smokeをIssueへ記録した
• publication、通常HTML、Vivliostyle Viewerの4.0専用URLを確認した