@kubohiroya/turbowarp-asset-cache 0.3.0 → 0.3.2

package/README.ja.md

@@ -0,0 +1,152 @@
+# TurboWarp-Asset-Cache
+
+[English](README.md)
+
+TurboWarpのプロジェクト向けに、画像・音声・実行時テキストをブラウザ内へ保持するasset cacheです。
+composition hostには、OPFSを明示的に選べるhybridなbinary backingを提供します。外部ファイル、
+プロジェクト内のコスチューム／背景／音、Temporary Variablesのテキスト参照を登録し、TurboWarpのblockや
+composition hostから利用できるようにします。
+
+Asset Cacheは従来の`isLoaded`とcacheのlifecycle semanticsを意図的に維持しています。汎用のサーバー
+object storeではなく、format 2 manifestではすべてのblockを`server.supported: false`としています。
+移植可能なnamespace/keyの永続化とサーバー側への移送には
+[`@kubohiroya/turbowarp-kvs`](https://github.com/kubohiroya/turbowarp-kvs)を使ってください。
+
+`@kubohiroya/turbowarp-asset-manager`は非推奨です。composition利用側は、asset登録・描画・再生・
+DOM image resource・検証済みremote cache APIについて、importパスを
+`@kubohiroya/turbowarp-asset-cache/composition`へ置き換えられます。binary object、bundle、
+session backingのAPIは`@kubohiroya/turbowarp-kvs`から直接importしてください。standaloneの
+プロジェクトでは、拡張機能IDも`kubohiroyaassetmanager`から`kubohiroyaassetcache`へ置き換える必要が
+あります。公開済みのSB3成果物は、元の拡張機能に固定したままにしてください。
+
+## ユーザーガイド
+
+導入手順、安全上の注意、レシピ、図入りのblock解説は
+[English user guide](https://kubohiroya.github.io/turbowarp-asset-cache/)または
+[日本語ユーザーガイド](https://kubohiroya.github.io/turbowarp-asset-cache/ja/)を参照してください。
+
+## できること
+
+- 画像、音声、プロジェクトasset、実行時テキストを論理的なasset名で登録します。
+- 登録済みの画像やテキストを、スプライト、クローン、ステージへ適用します。
+- 登録済みの音声を再生し、actorのアニメーション列にも対応します。
+- host拡張機能向けに、blockを使わないComposition APIを提供します。
+- SVGとremote binaryの入力を、利用前およびcacheへの書き込み前に検証します。
+- アプリケーションshell向けに、story単位のIndexedDB cache制御を利用できる状態に保ちます。
+- 既定はIndexedDBのまま、composition hostが検証済みbinary objectのbyte列にOPFSを選べるようにします。
+
+## 統合方法を選ぶ
+
+TurboWarpのプロジェクトが`dist/asset-cache.js`を直接読み込み、パレットにAsset Cacheのblockを並べる場合は
+Standalone拡張機能を使います。
+
+別のunsandboxed拡張機能やアプリケーションshellが`@kubohiroya/turbowarp-asset-cache/composition`を
+importし、registryを内部に閉じたまま、パレットへAsset Cacheのblockを追加したくない場合はComposition APIを
+使います。
+
+## 動作条件と安全性
+
+standaloneでの利用には、TurboWarp Desktop、またはunsandboxedなカスタム拡張機能を読み込める他の
+TurboWarp環境が必要です。実行時テキストの描画には、さらにTemporary Variables（`lmsTempVars2`）と
+Animated Text（`text`）が必要です。
+
+SVG入力は既定で拒否します。remote binaryのcache entryは、保存前にサイズ・content-type・SHA-256を
+検証します。IndexedDBは機密の境界ではなく補助的なcacheとして扱います。
+
+メンテナはNode.js 22以降と、Corepack経由のpnpmを使います。インストール例とCDN URLのsource of truthは
+`package.json`のversionです。
+
+## セキュリティダイアログの説明言語
+
+この版のビルドでは、既定の英語説明に加えて`Description[ja]`コメントへ日本語の説明を出力します。このメタデータに対応した共通セキュリティダイアログは、Editorが日本語なら日本語の説明を表示し、対応する翻訳がなければ元の説明を表示します。
+
+説明の翻訳は必要な実行モードを変えません。この拡張は引き続き`Unsandboxed: required`です。
+
+## インストール
+
+[`dist/asset-cache.js`](dist/asset-cache.js)をダウンロードし、TurboWarp Desktopでローカルの
+カスタム拡張機能として読み込みます。確認されたら**サンドボックス化せずに実行**を有効にします。
+
+ビルド済みのJavaScriptファイルをこのリポジトリにcommitしてあるため、Node.jsのインストールやビルドの実行は
+必要ありません。
+
+versionを付けたnpm packageにも、同じレビュー済みビルドが入っています。
+
+```bash
+pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.3.2
+```
+
+`node_modules/@kubohiroya/turbowarp-asset-cache/dist/asset-cache.js`を読み込むか、version固定の
+CDN URLを使います。
+
+```text
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.3.2/dist/asset-cache.js
+```
+
+## クイックスタート
+
+1. `dist/asset-cache.js`をunsandboxedなTurboWarp拡張機能として読み込みます。
+2. `register resource [RESOURCE_ID] as asset [NAME]`でリソースを登録します。
+3. `show asset [NAME] on this sprite`、`set stage backdrop to asset [NAME]`、または音声blockでassetを使います。
+4. プロジェクトのlifecycleや保存方針として明示的な後片付けが必要な場合は、cacheと削除のblockを使います。
+
+## Compositionの例
+
+```js
+import {createAssetManagerComposition} from '@kubohiroya/turbowarp-asset-cache/composition';
+
+const assets = createAssetManagerComposition();
+await assets.registerEmbeddedAsset({
+  name: 'Opening',
+  sourceName: 'opening.svg',
+  mimeType: 'image/svg+xml',
+  bytes: new TextEncoder().encode('<svg xmlns="http://www.w3.org/2000/svg"/>')
+});
+await assets.applyToStage('Opening');
+assets.releaseAll();
+```
+
+## 統合の全体像
+
+- standaloneのプロジェクトは、リソース識別子、実行時テキスト、診断、actorアニメーション、読み込み互換性、
+  拡張機能IDの移行について[Runtime and Standalone Contracts](docs/runtime-contracts.md)を参照してください。
+- composition hostは、埋め込みasset、構造化locator、音声voice、DOM image resource、SVG検証、
+  story単位のcache、検証済みremote binary、binary bundle、session限定のbinary backingについて
+  [Composition API](docs/composition-api.md)を参照してください。
+- blockの利用者とドキュメントのメンテナは、生成されたblock表について
+  [Block Reference](docs/block-reference.md)を参照してください。
+
+## 開発
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm run check
+```
+
+block APIの正式なsourceは`src/block-definitions.json`です。変更したらblockのドキュメントを再生成します。
+
+```bash
+pnpm run docs
+```
+
+ビルドは`dist/asset-cache.js`、`dist/extension-manifest.json`、`dist/composition.js`、
+`dist/types/composition.d.ts`を生成します。決定的なformat 2 manifestはすべてのblock signatureを記録し、
+Asset Cacheのパレット全体をブラウザ専用として明示します。拡張機能、block metadata、Compositionのsourceを
+変更したら、再ビルドした成果物をcommitしてください。
+
+## リリース
+
+公開前にローカルでリリース検査を実行します。
+
+```bash
+pnpm run pack:check
+pnpm run release:check
+```
+
+npm packageのアーカイブには、README、LICENSE、Standalone bundle、拡張機能API manifest、
+Composition bundle、Compositionの型宣言を含める必要があります。
+
+## ライセンス
+
+SPDX-License-Identifier: MPL-2.0

package/README.md

@@ -1,5 +1,7 @@
 # TurboWarp-Asset-Cache
 
+[日本語](README.ja.md)
+
 A browser-local image, audio, and runtime-text asset cache for TurboWarp projects, with an explicit OPFS hybrid binary backing for composition hosts. It registers external files, project-local costumes/backdrops/sounds, and Temporary Variables text references for use from TurboWarp blocks or composition hosts.
 
 Asset Cache intentionally keeps the legacy `isLoaded` and cache lifecycle semantics. It is not a general server object store: every block is marked `server.supported: false` in the format 2 manifest. Use [`@kubohiroya/turbowarp-kvs`](https://github.com/kubohiroya/turbowarp-kvs) for portable namespace/key persistence and server lowering.
@@ -39,6 +41,12 @@ SVG input is reject-by-default, remote binary cache entries are size/content-typ
 
 Maintainers use Node.js 22 or later with pnpm through Corepack. The package version in `package.json` is the source of truth for install examples and CDN URLs.
 
+## Security dialog description language
+
+Builds include a Japanese `Description[ja]` header alongside the default English
+description. A supporting shared security dialog follows the Editor locale and falls back to
+the original description when no translation is available. Translation does not change the `Unsandboxed: required` requirement.
+
 ## Installation
 
 Download [`dist/asset-cache.js`](dist/asset-cache.js), then open TurboWarp Desktop and load it as a local custom extension. Enable **Run extension without sandbox** when prompted.
@@ -48,13 +56,13 @@ The built JavaScript file is committed to this repository so users do not need t
 The versioned npm package contains the same reviewed build:
 
 ```bash
-pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.3.0
+pnpm add --save-exact @kubohiroya/turbowarp-asset-cache@0.3.2
 ```
 
 Load `node_modules/@kubohiroya/turbowarp-asset-cache/dist/asset-cache.js`, or use the version-pinned CDN URL:
 
 ```text
-https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.3.0/dist/asset-cache.js
+https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-cache@0.3.2/dist/asset-cache.js
 ```
 
 ## Quick Start

package/dist/asset-cache.js

@@ -3,6 +3,8 @@
 // Description: Register, cache, display, and play image, audio, and runtime text assets in TurboWarp.
 // By: Hiroya Kubo
 // License: MPL-2.0
+// Unsandboxed: required
+// Description[ja]: TurboWarpで画像・音声・実行時テキストの素材を登録・保持し、表示・再生します。
 
 (function (Scratch) {
   'use strict';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-asset-cache",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A browser-local image, audio, and runtime-text asset cache for TurboWarp projects.",
   "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
   "type": "module",
@@ -25,6 +25,7 @@
     "schemas/",
     "docs/fixed-input-editors.ja.md",
     "README.md",
+    "README.ja.md",
     "LICENSE",
     "docs/audio-playback.md"
   ],
@@ -66,7 +67,7 @@
     "@kubohiroya/turbowarp-extension-data-editor": "0.2.1",
     "@kubohiroya/turbowarp-extension-manifest": "0.3.2",
     "@kubohiroya/turbowarp-named-data": "0.3.1",
-    "@kubohiroya/vite-plugin-turbowarp-extension": "0.6.1",
+    "@kubohiroya/vite-plugin-turbowarp-extension": "0.7.0",
     "@types/node": "^22.20.1",
     "@xmldom/xmldom": "0.9.11",
     "eslint": "^9.39.5",