stack-chan

# Visual Programmingプロジェクト契約

## 対象

**Visual Programmingプロジェクト**は、Blocklyワークスペースと生成条件を保存する編集用成果物です。

編集用成果物と実行用のXSアーカイブは役割が異なります。

XSアーカイブは既存のMODとして実行し、Visual Programming専用ランタイムは導入しません。

## プロジェクト形式

プロジェクトファイルの拡張子は`.stackchan-blocks.json`です。

ルートオブジェクトは次のフィールドを持ちます。

- **format**：`tech.stackchan.visual-project`です。
- **version**：形式の互換性を示す整数です。
- **id**：プロジェクトと複製を区別する一意な識別子です。
- **name**：利用者が付けたプロジェクト名です。
- **target**：ビルド前診断に使う対象機種です。
- **workspace**：Blocklyの直列化結果です。
- **assets**：MODへ組み込むアセットです。
- **settings**：教育向け表示とアセット埋め込みの設定です。
- **createdAt**：作成日時です。
- **updatedAt**：最終更新日時です。

バージョン1はPR #538のBlocklyワークスペースのみの保存データを読み込めます。

読み込んだ旧形式は、保存時にバージョン1へ移行します。

ブラウザ内には更新日時順で最大8件のプロジェクトを保存します。

プロジェクト本体、履歴、復旧データは、最大サイズのプロジェクトでも自動保存できるようIndexedDBへ保存します。

PR #538以前のBlocklyワークスペースとバージョン1初期実装の`localStorage`データは、初回読込時にIndexedDBへ移行します。

現在の保存データや読み込んだファイルを解析できない場合、元の文字列とエラーを復旧用JSONへ退避します。

## MOD生成契約

エディタは`onContextCreated(robot)`を公開する`mod.js`とmanifestを生成します。

生成コードが使えるAPIは、通常のMODへ公開される`StackchanContext`の能力に限定します。

プロジェクトは利用する能力を列挙し、対象機種にない能力をビルド前にエラーとして報告します。

CoreS3とWebシミュレーターの現在の対象プロファイルは、XS 17.8.0を使用します。

ブラウザ用ビルドツールとWebシミュレーターはModdable SDK 8.3.1とEmscripten 5.0.1から生成し、生成スクリプトとCIの双方でこの版を固定します。

ブラウザ内ビルドは、生成したアーカイブのXS版が対象プロファイルと一致することを確認します。

## Webシミュレーターの起動と入力

Webシミュレーターは、保存したXSAをWASMメモリーへ配置してからファームウェアを起動します。

ファームウェアが`[main] app behaviors ready`を出力するまで、エディターへ起動成功を通知しません。

30秒以内にこの出力を受信できない場合は、起動準備のタイムアウトとしてエディターへ報告します。

エディターのA、B、Cボタンは、ブラウザー側の`Host.Button`へ押下状態を設定します。

WASM入力モジュールは押下状態を16ミリ秒間隔で読み取り、CoreS3と同じ1を押下、0を解放とする値をXS側の`Host.Button`へ渡します。

MODの入力ハンドラーは、ファームウェアとMODの準備が完了した後にボタンイベントを受け取ります。

## 安全性

エディタはブロックから生成したコードだけを標準のビルド対象にします。

任意のJavaScript入力欄は教育向けプロファイルに追加しません。

実機書き込みの前にはfactoryアプリの`esp_app_desc`を読み取り、ファームウェア版と対応XS版を確認します。

要求能力、対象チップ、実ファームウェア版、XS版、アーカイブサイズ、書き込み先パーティションのいずれかが不明または不一致なら、書き込みを開始しません。

WebSerial実機書き込みは、対象チップと対応ファームウェア版を定義したCoreS3プロファイルだけで有効にします。

Webシミュレーターと機種を限定しないプロファイルは、ビルドとシミュレーター実行には使用できますが、実機書き込みには使用できません。

条件ループは停止しない可能性があるため、ビルド前に警告し、実機より先にシミュレーターで実行します。

BlocklyとLucideの外部スクリプトは、バージョンとSubresource Integrityを固定します。

統合シミュレーターが読み込むThree.jsのES moduleは、import mapの`integrity`メタデータでバージョンとSHA-384を固定します。

実機書き込みに使うesptool-jsは、版とSHA-384を検証したbundleおよびライセンスをリポジトリ内へ同梱します。

## アセット

アセットのパスはプロジェクトルートからの相対パスです。

絶対パス、親ディレクトリ参照、バックスラッシュを含むパスは拒否します。

テキストはUTF-8、バイナリはBase64で保存します。

プロジェクトJSONは8 MiB、アセットは32個、1個あたり2 MiBを上限とします。

実行時ロードを必要としない小規模な教育用プロジェクトでは、アセットをMODへ埋め込みます。

プロジェクト設定の「アセットをMODへ埋め込む」を無効にすると、編集用プロジェクトにはアセットを残したまま、生成するXSAのresourcesから除外します。

共有アセットや差し替え頻度が高いアセットには、将来の標準アセットパッケージを使用します。

選定基準は次のとおりです。

| 条件                                                         | 方式             | 理由                                               |
| ------------------------------------------------------------ | ---------------- | -------------------------------------------------- |
| MODと同時に更新し、2 MiB以下で、単独利用する                 | ビルド時埋め込み | オフラインで再現でき、配布物を一つに保てる         |
| 複数MODで共有し、MODとは別の周期で差し替える                 | 実行時ロード     | 同一データの重複とMODの再ビルドを避けられる        |
| ネットワーク取得が必要、または2 MiBを超える                  | 実行時ロード     | プロジェクト形式とxsパーティションの肥大化を避ける |
| 初回起動に必須、または通信できない状態でも表示する必要がある | ビルド時埋め込み | 起動時の外部依存と取得失敗を避けられる             |

バージョン1のVisual Programmingエディタはビルド時埋め込みを実装します。

実行時ロードを選ぶアセットはプロジェクトへ埋め込まず、通常のMODからプラットフォームのアセットAPIを利用します。