Loading files
3bc1fc157This file is pinned to the selected release. Download the original to open it in your design tool.
# 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 9.0.0と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`を読み取り、Moddable SDK版、`+stackchan.N`で示すhost API世代、対応XS版を確認します。
要求能力、host API世代、対象チップ、実ファームウェア版、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を利用します。