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

必要な環境

• Node.js 22.12.0以上
• pnpm 11
• PDF生成に利用できるChromeまたはChromium
• Gitと、GitHub操作に利用するGitHub CLI

corepack enable
pnpm install

CIではlockfile以外の依存解決を許可しません。

pnpm install --frozen-lockfile

初回セットアップ後は、展開SB3ソースとテスト用SB3を確認します。

pnpm sb3:check
pnpm test

macOSでは通常のGoogle ChromeをPDF生成に自動利用します。別のブラウザを使う環境では、 VIVLIOSTYLE_CHROME_PATHへ実行ファイルの絶対パスを設定します。

導入

利用可能なバージョンを確認し、消費側で明示的に固定します。

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

生成したlockfileをcommitし、CIではpnpm install --frozen-lockfileを使います。

CLI

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

--outputは拡張子を含まないベース名です。次の3ファイルを同じtransactionとして 生成します。

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

完全な一覧はpnpm exec tmpose-kamishibai --helpで確認します。

JavaScript API

import {
  Sb3BuilderError,
  buildSb3Bundle,
  validateAssetManifest,
  validateBundle,
} from '@kubohiroya/tmpose-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);

baseSb3とsourceScriptにはファイルパスまたはfile: URLを指定できます。 assetManifestにはファイルパス、file: URL、または検証対象のJavaScriptオブジェクトを 指定できます。相対file:を含むオブジェクトではmanifestBaseDirectoryも指定します。

ネットワーク・ファイル取得はallowedFileRoots、allowHttp、requestTimeoutMs、 maxAssetBytes、maxRedirectsで制限できます。playerの組み込み台本上限は maxEmbeddedScriptBytesで変更できます。

buildSb3BundleはmanifestとoutputPathsを返します。入力・アセット・出力の問題は Sb3BuilderErrorとして処理段階とアセット情報を保持します。

アセットマニフェスト

入力manifestはformatVersion: 1と1件以上のassetsを持ちます。

{
  "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
      }
    }
  ]
}

DSL名、同一target内のSB3名、既存SB3のアセット名は重複できません。licenseには素材の ライセンスまたは利用条件の識別情報と参照先を記録します。

安全性と再現性

• file:は既定でmanifestのディレクトリ以下だけを許可し、..やsymlinkによる脱出を拒否する
• HTTPSを既定とし、平文HTTPは明示的に許可した場合だけ取得する
• Content-Type、実サイズ、ロック済みサイズ、SHA-256、timeout、redirectを検証する
• ZIP entry順、timestamp、圧縮設定、JSON表現を固定する
• SB3、変換済み台本、出力manifestの対応を確定前に再検証する
• 3成果物を一時領域で生成し、すべて成功した場合だけ置換する
• 失敗時は既存成果物を保持または復元する

同じ入力、固定依存、設定から生成したSB3、台本、manifestはbit-for-bitで一致しなければ なりません。

変更対象ごとのテスト

標準チェック

pnpm lint
pnpm format
pnpm typecheck
pnpm test
pnpm run build

GitHub ActionsはcleanなLinux環境でpnpm install --frozen-lockfile、pnpm test、 pnpm buildを実行します。ローカルで成功しても、未追跡ファイルや既存生成物へ依存して いないことをCIで確認します。

pnpm run buildは少なくとも次を生成・検証します。

• dist/downloads/kamishibai.sb3
• 一般文書ごとのWeb Publication、HTML/PDF、Vivliostyle CLIがh2・h3までから生成する目次
• 参加者向け・スタッフ向け体験会資料
• 公開サイトのリンク、画像、目次、PDF bookmark、favicon

SB3またはruntimeを変更した場合は、生成SB3をTurboWarpで開いて次を手動確認します。

• 読込エラーがない
• green flagでtitleとmenuが表示される
• 外部台本と組み込み台本の対象フローが開始できる
• pause、Space、Right、Downの進行が意図どおり動く
• Downでシーンを飛ばしてもBGMが継続し、残りのtransitionが最終状態になる
• Loading、画像、音声、テキストが正しく表示・再生される

内部構造を変更したPRでは、app/project.source.jsonと内部仕様書のtarget、変数、message、 hat、custom block一覧を同時に更新します。

GitHub Pages

pnpm run deploy

predeployがフルbuildを行い、成功したdist/だけをgh-pagesへ公開します。公開後は top page、文書一覧、各カードのHTML／Vivliostyle Viewer／PDF、SB3 downloadを実際の URLから確認します。

問題がある場合は、直前の検証済みcommitをcheckoutしたcleanな環境から再度build・ deployします。生成済みdist/だけを手作業で修正しません。

npmパッケージ

公開済みversionは変更・再利用できません。releaseごとに新しいversionとGit tagを使います。

1. package.json、lockfile、src/builder/constants.js、READMEの導入例を同じversionへ更新する。
2. cleanなcommitで標準チェック、フルbuild、公開内容のdry-runを実行する。

pnpm release:check

3. tarballのファイル一覧、license、size、CLI/APIを確認する。
4. Git worktreeではなく通常のclean cloneから公開する。
5. WebAuthnなどの認証を完了してpublic packageとして公開する。

npm publish --access public

6. registry反映後にmetadataを確認する。

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

7. 一時ディレクトリへ公開版を導入し、CLIの--versionと @kubohiroya/tmpose-kamishibai/builderのimportを確認する。
8. 公開に使った確定commitへannotated tagを作り、GitHub Releaseを作成する。

公開後に問題が見つかった場合は対象versionをnpm deprecateし、修正版を新しいpatch versionとして公開します。公開済みtarballやtagを差し替えません。

sb3-toolchain

sb3-toolchainは、SB3をGit差分可能な 展開ソースとして管理し、検証して決定的に再構築するためのCLI／JavaScript APIです。 このリポジトリでは固定依存として利用し、app/のimport、検証、build、埋め込み 機能拡張の同期とID移行を担います。

• SB3ソース管理ワークフロー
• SB3展開ソース形式 v1
• 埋め込み拡張IDの移行

Viteプラグイン

• vite-plugin-turbowarp-extension: TypeScriptプロジェクトを単一ファイルのTurboWarp機能拡張としてbuildするViteプラグイン

TurboWarp 機能拡張開発用テンプレート

• turbowarp-extension-template: Viteを使ったTurboWarp機能拡張の開発、テスト、build、リリース用テンプレート

TurboWarp 機能拡張

• turbowarp-tmpose: Teachable Machine Poseモデルを利用したカメラ姿勢認識
• turbowarp-text-lines: テキストの行数取得、行単位の読み出し・分割
• turbowarp-asset-manager: IndexedDBとSB3内の画像・音声を扱うアセット管理
• turbowarp-async-input: キーボード、ポインター、姿勢入力を対象ごとに扱う非同期入力
• turbowarp-runtime-expression: runtime変数を使う条件式の安全な評価とbroadcast監視

その他のライブラリ

• rubygana: 日本語テキストの読み仮名を生成するNode.jsライブラリ