@kubohiroya/turbowarp-structured-data 0.4.0

package/src/structured-provider.ts

@@ -0,0 +1,188 @@
+import {renderJsonDocument, renderYamlDocument} from './codecs.js';
+import type {JsonValue} from './core.js';
+import {
+  NamedDataError,
+  type NamedDataBody,
+  type NamedDataMetadata,
+  type NamedDataProvider,
+  type NamedDataReference,
+  type NamedDataRepresentation,
+  type NamedDataResolveContext
+} from '@kubohiroya/turbowarp-named-data/composition';
+
+export const STRUCTURED_DATA_NAMESPACE = 'structured';
+export const STRUCTURED_BODY_MAX_BYTES = 256 * 1024;
+
+export interface StructuredDataBinding {
+  value: JsonValue;
+  revision: number;
+  nativeRepresentation: 'json' | 'yaml';
+}
+
+export interface StructuredDataBindingStore {
+  get(target: object, name: string): StructuredDataBinding | undefined;
+}
+
+export class StructuredDataNamedDataProvider implements NamedDataProvider {
+  public readonly namespace = STRUCTURED_DATA_NAMESPACE;
+  public readonly kind = 'structured' as const;
+  private readonly openBodies = new Set<symbol>();
+  private released = false;
+
+  public constructor(
+    private readonly store: StructuredDataBindingStore,
+    private readonly maxBodyBytes = STRUCTURED_BODY_MAX_BYTES
+  ) {}
+
+  public canResolve(
+    reference: NamedDataReference,
+    representation: NamedDataRepresentation
+  ): boolean {
+    return (
+      reference.namespace === this.namespace &&
+      reference.kind === this.kind &&
+      reference.scope === 'target' &&
+      (representation === 'json' || representation === 'yaml')
+    );
+  }
+
+  public stat(
+    reference: NamedDataReference,
+    representation: NamedDataRepresentation,
+    context: NamedDataResolveContext
+  ): NamedDataMetadata {
+    const resolved = this.resolve(reference, representation, context);
+    return this.metadata(
+      reference,
+      resolved.nativeRepresentation,
+      representation,
+      resolved.bytes.byteLength,
+      resolved.revision
+    );
+  }
+
+  public openBody(
+    reference: NamedDataReference,
+    representation: NamedDataRepresentation,
+    context: NamedDataResolveContext
+  ): NamedDataBody {
+    const resolved = this.resolve(reference, representation, context);
+    const handle = Symbol('structured-body');
+    this.openBodies.add(handle);
+    let released = false;
+    return {
+      ...this.metadata(
+        reference,
+        resolved.nativeRepresentation,
+        representation,
+        resolved.bytes.byteLength,
+        resolved.revision
+      ),
+      body: resolved.bytes,
+      release: () => {
+        if (released) return;
+        released = true;
+        this.openBodies.delete(handle);
+      }
+    };
+  }
+
+  public release(): void {
+    this.released = true;
+    this.openBodies.clear();
+  }
+
+  public clearSession(): void {
+    this.openBodies.clear();
+  }
+
+  private resolve(
+    reference: NamedDataReference,
+    representation: NamedDataRepresentation,
+    context: NamedDataResolveContext
+  ): {bytes: Uint8Array; revision: number; nativeRepresentation: 'json' | 'yaml'} {
+    if (this.released) {
+      throw new NamedDataError('NAMED_DATA_PROVIDER_RELEASED', 'The structured provider was released.');
+    }
+    this.validateReference(reference, context);
+    this.throwIfAborted(context.signal);
+    const binding = this.store.get(context.target as object, reference.name);
+    if (!binding) {
+      throw new NamedDataError(
+        'NAMED_DATA_NOT_FOUND',
+        `Structured data does not exist: ${reference.name}`
+      );
+    }
+    const text = this.render(binding.value, representation);
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.byteLength > this.maxBodyBytes) {
+      throw new NamedDataError(
+        'NAMED_DATA_BODY_TOO_LARGE',
+        `Encoded body is ${bytes.byteLength} bytes; maximum is ${this.maxBodyBytes}.`
+      );
+    }
+    this.throwIfAborted(context.signal);
+    return {
+      bytes,
+      revision: binding.revision,
+      nativeRepresentation: binding.nativeRepresentation
+    };
+  }
+
+  private validateReference(
+    reference: NamedDataReference,
+    context: NamedDataResolveContext
+  ): void {
+    if (reference.namespace !== this.namespace || reference.name.trim().length === 0) {
+      throw new NamedDataError('NAMED_DATA_INVALID_REF', 'Invalid structured data reference.');
+    }
+    if (reference.kind !== this.kind) {
+      throw new NamedDataError(
+        'NAMED_DATA_KIND_MISMATCH',
+        `Expected ${this.kind}, received ${reference.kind}.`
+      );
+    }
+    if (reference.scope !== 'target' || !context.target) {
+      throw new NamedDataError(
+        'NAMED_DATA_SCOPE_MISMATCH',
+        'Structured data currently requires a target scope and target context.'
+      );
+    }
+  }
+
+  private render(value: JsonValue, representation: NamedDataRepresentation): string {
+    if (representation === 'json') return renderJsonDocument(value);
+    if (representation === 'yaml') return renderYamlDocument(value);
+    throw new NamedDataError(
+      'NAMED_DATA_REPRESENTATION_UNSUPPORTED',
+      `Structured data cannot be rendered as ${representation}.`
+    );
+  }
+
+  private metadata(
+    reference: NamedDataReference,
+    nativeRepresentation: 'json' | 'yaml',
+    representation: NamedDataRepresentation,
+    byteLength: number,
+    revision: number
+  ): NamedDataMetadata {
+    return {
+      reference: {...reference},
+      nativeRepresentation,
+      representation,
+      mediaType:
+        representation === 'json'
+          ? 'application/json; charset=utf-8'
+          : 'application/yaml; charset=utf-8',
+      byteLength,
+      revision: String(revision),
+      replayable: true
+    };
+  }
+
+  private throwIfAborted(signal: AbortSignal | undefined): void {
+    if (signal?.aborted) {
+      throw new NamedDataError('NAMED_DATA_ABORTED', 'Body resolution was aborted.');
+    }
+  }
+}

package/templates/README.ja.md

@@ -0,0 +1,183 @@
+# TurboWarp-<Extension-Name>
+
+[English](README.md) | [日本語](README.ja.md)
+
+<何をするかを一文で説明>ためのTurboWarp機能拡張です。
+
+**利用ガイド:** [English](<PAGES_URL>/)
+
+## できること
+
+- <利用者ができること1>
+- <利用者ができること2>
+- <利用者ができること3>
+
+実装ファイルの説明ではなく、利用者から見た結果を書きます。
+
+## ドキュメントとブロックアイコン
+
+この機能拡張は、英語版の利用者向けドキュメントをGitHub Pagesで公開します。
+
+- `docsURI` はGitHub Pages上の英語版ドキュメント `<PAGES_URL>/` を指します。
+- `blockIconURI` は `data:image/svg+xml;base64,...` 形式の自己完結したSVGとします。
+- ブロックアイコンは機能拡張の内容を直感的に表す、単純で識別しやすい図柄にします。公開版では汎用の仮アイコンをそのまま使用しません。
+
+## 動作条件と安全上の注意
+
+- <TurboWarp Desktop／Web／Packagerの対応>
+- <Browser APIまたはcompanion extension>
+- <sandbox条件>
+
+> [!IMPORTANT]
+> この機能拡張は<理由>のため、サンドボックスなしで実行する必要があります。
+> 信頼できる配布元の機能拡張だけを読み込んでください。
+
+sandbox互換の場合は上の注意書きを削除します。
+
+## インストール
+
+### 完成済みJavaScript
+
+1. [`dist/<file>.js`](dist/<file>.js?raw=1)をダウンロードします。
+2. TurboWarpで**機能拡張**を開きます。
+3. **カスタム機能拡張**からfileを読み込みます。
+4. 必要な場合は**サンドボックスなしで実行する**を許可します。
+
+完成済みの検証対象JavaScriptをrepositoryへcommitしているため、利用者が
+Node.jsやbuild環境を用意する必要はありません。
+
+### npm package
+
+検証済みのversionをexact pinします。
+
+```bash
+pnpm add --save-exact @kubohiroya/<package>@<version>
+```
+
+standalone bundle:
+
+```text
+node_modules/@kubohiroya/<package>/dist/<file>.js
+```
+
+version固定CDN URL:
+
+```text
+https://cdn.jsdelivr.net/npm/@kubohiroya/<package>@<version>/dist/<file>.js
+```
+
+`<version>`を手作業で保守する場合は、`package.json`との一致をCIで検査します。
+
+## クイックスタート
+
+1. <手順1>
+2. <手順2>
+3. <手順3>
+
+```text
+<最小のTurboWarp block flow>
+```
+
+## ブロックリファレンス
+
+block referenceは
+[`src/block-definitions.json`](src/block-definitions.json)から生成します。
+生成範囲を直接編集しないでください。
+
+<!-- BEGIN GENERATED BLOCKS -->
+
+<自動生成block文書>
+
+<!-- END GENERATED BLOCKS -->
+
+## 重要な動作
+
+| 状況 | 動作 |
+|---|---|
+| <case> | <正確な動作> |
+| project停止 | <cleanup> |
+| project再読込 | <cleanupまたは復元> |
+| 無効な入力 | <errorまたはfallback> |
+
+## Composition API
+
+Composition APIがないpackageでは、このsectionを削除します。
+
+Composition APIをimportしても、standalone TurboWarp機能拡張は自動登録されません。
+
+```ts
+import {create<Feature>Composition} from '@kubohiroya/<package>/composition';
+
+const feature = create<Feature>Composition({
+  // 明示的な依存
+});
+
+// capabilityを利用する。
+
+feature.releaseAll();
+```
+
+所有、取消し、`AbortSignal`、project lifecycle、副作用、browser／network／storage／
+renderer境界、`release()`／`releaseAll()`を説明します。
+
+完全なmethod referenceは
+[`docs/composition-api.md`](docs/composition-api.md)へ分けます。
+
+## 連携
+
+| 利用側 | 関係 |
+|---|---|
+| `<consumer package>` | <required／optional／capability injection> |
+
+依存方向はconsumerからproviderとし、private fieldを公開連携方法として書きません。
+
+## 互換性
+
+| 識別子 | 値 | 安定性 |
+|---|---|---|
+| 製品名 | `TurboWarp-<Extension-Name>` | 利用者向け表示 |
+| repository | `kubohiroya/<repository>` | current source |
+| npm package | `@kubohiroya/<package>` | public package contract |
+| extension ID | `<extensionid>` | SB3に保存。変更にはmigrationが必要 |
+
+複数語からなるTurboWarp機能拡張の正式表示名では、すべての構成語をハイフンで連結します。例: `TurboWarp-Asset-Manager`、`TurboWarp-Runtime-Expression`、`TurboWarp-Diagnostic-Overlay`。
+
+extension IDまたはopcode変更時はschema-aware migrationを説明し、保存済み識別子が変わった場合にJavaScriptだけの差替えを案内しません。
+
+## 開発
+
+`engines`のNode.jsと、`packageManager`に宣言したpnpmを使用します。
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+| command | 用途 |
+|---|---|
+| `pnpm dev` | source変更中の継続build |
+| `pnpm test` | test |
+| `pnpm docs` | block文書生成 |
+| `pnpm check:dist` | commit済みbuild artifactの検証 |
+| `pnpm pack:check` | npm package内容の確認 |
+| `pnpm release:check` | release dry run |
+
+## リリース
+
+1. `CHANGELOG.md`がある場合は更新する。
+2. `package.json`のversionを更新する。
+3. `pnpm check`とrepository固有のrelease checkを実行する。
+4. release PRをmergeする。
+5. 検証済みcommitへ`v<version>`tagを付ける。
+6. 必要に応じて同じversionをnpmへpublishする。
+7. GitHub Release、npm tarball、GitHub Pages、`docsURI`、block icon、CDNを確認する。
+
+release consistency checkでは、exact-version README／CDN例に加え、`docsURI`が英語版Pagesを指すこと、`blockIconURI`が`data:image/svg+xml;base64,...`形式であることを検証します。
+
+## ライセンス
+
+[Mozilla Public License 2.0](LICENSE)（SPDX: `MPL-2.0`）で提供します。
+
+third-party componentを含む場合は
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)に記載します。

package/templates/README.md

@@ -0,0 +1,198 @@
+# TurboWarp-<Extension-Name>
+
+[English](README.md) | [日本語](README.ja.md)
+
+A TurboWarp extension that <one-sentence purpose>.
+
+**User guide:** [English](<PAGES_URL>/)
+
+## What it does
+
+- <User-visible capability 1>
+- <User-visible capability 2>
+- <User-visible capability 3>
+
+Keep this section about outcomes, not implementation files.
+
+## Documentation and block icon
+
+This extension publishes its English user documentation with GitHub Pages.
+
+- `docsURI` points to the English GitHub Pages documentation: `<PAGES_URL>/`.
+- `blockIconURI` is a self-contained SVG encoded as `data:image/svg+xml;base64,...`.
+- The block icon should be a simple, recognizable symbol that represents this extension and improves block readability. Do not use a generic placeholder icon in a released extension.
+
+## Requirements and safety
+
+- <TurboWarp Desktop / Web / Packager support>
+- <Browser API or companion extension requirements>
+- <Sandbox requirement>
+
+> [!IMPORTANT]
+> This extension must run without the sandbox because <reason>. Load unsandboxed
+> extension code only from a source you trust.
+
+Delete the notice above when the extension is sandbox-compatible.
+
+## Installation
+
+### Ready-to-use JavaScript
+
+1. Download [`dist/<file>.js`](dist/<file>.js?raw=1).
+2. Open **Extensions** in TurboWarp.
+3. Choose **Custom Extension** and load the file.
+4. Enable **Run extension without sandbox** when required.
+
+The reviewed JavaScript build is committed to this repository, so users do not
+need Node.js to install the extension.
+
+### npm package
+
+Install an exact version that you have reviewed:
+
+```bash
+pnpm add --save-exact @kubohiroya/<package>@<version>
+```
+
+Load the standalone bundle from:
+
+```text
+node_modules/@kubohiroya/<package>/dist/<file>.js
+```
+
+A version-pinned CDN URL is:
+
+```text
+https://cdn.jsdelivr.net/npm/@kubohiroya/<package>@<version>/dist/<file>.js
+```
+
+Do not maintain `<version>` manually unless CI checks it against `package.json`.
+
+## Quick start
+
+1. <Step 1>
+2. <Step 2>
+3. <Step 3>
+
+```text
+<Minimal TurboWarp block flow>
+```
+
+## Block reference
+
+The block reference is generated from
+[`src/block-definitions.json`](src/block-definitions.json). Do not edit the
+generated section manually.
+
+<!-- BEGIN GENERATED BLOCKS -->
+
+<Generated block documentation>
+
+<!-- END GENERATED BLOCKS -->
+
+## Important behavior
+
+| Situation | Behavior |
+|---|---|
+| <Case> | <Exact behavior> |
+| Project stop | <Cleanup behavior> |
+| Project reload | <Cleanup or restoration behavior> |
+| Invalid input | <Error or fallback behavior> |
+
+## Composition API
+
+Delete this section when the package has no Composition API.
+
+Importing the Composition API does not register the standalone TurboWarp
+extension.
+
+```ts
+import {create<Feature>Composition} from '@kubohiroya/<package>/composition';
+
+const feature = create<Feature>Composition({
+  // Explicit dependencies
+});
+
+// Use the capability.
+
+feature.releaseAll();
+```
+
+Explain:
+
+- ownership;
+- cancellation and `AbortSignal`;
+- target/project lifecycle;
+- side effects;
+- browser, network, storage, and renderer boundaries;
+- `release()` / `releaseAll()` behavior.
+
+Move the complete method reference to [`docs/composition-api.md`](docs/composition-api.md).
+
+## Integration
+
+| Consumer | Relationship |
+|---|---|
+| `<consumer package>` | <required / optional / capability injection> |
+
+Dependencies must point from the consumer to the provider. Do not document
+private-field access as an integration API.
+
+## Compatibility
+
+| Identifier | Value | Stability |
+|---|---|---|
+| Product name | `TurboWarp-<Extension-Name>` | Human-facing |
+| Repository | `kubohiroya/<repository>` | Current source location |
+| npm package | `@kubohiroya/<package>` | Public package contract |
+| Extension ID | `<extensionid>` | Stored in SB3; migration required to change |
+
+Use hyphens between every component of a multi-word TurboWarp extension name,
+for example `TurboWarp-Asset-Manager`, `TurboWarp-Runtime-Expression`, and
+`TurboWarp-Diagnostic-Overlay`.
+
+Document schema-aware migrations when an extension ID or opcode changes. Never
+instruct users to replace JavaScript alone when stored identifiers have changed.
+
+## Development
+
+Use Node.js `<minimum version>` and the pnpm version declared by
+`packageManager`.
+
+```bash
+corepack enable
+pnpm install --frozen-lockfile
+pnpm check
+```
+
+Useful commands:
+
+| Command | Purpose |
+|---|---|
+| `pnpm dev` | Rebuild while source files change |
+| `pnpm test` | Run tests |
+| `pnpm docs` | Regenerate block documentation |
+| `pnpm check:dist` | Verify committed build artifacts |
+| `pnpm pack:check` | Inspect the npm package |
+| `pnpm release:check` | Dry-run the release |
+
+## Release
+
+1. Update `CHANGELOG.md` when present.
+2. Update the version in `package.json`.
+3. Run `pnpm check` and the repository release checks.
+4. Merge the release PR.
+5. Create tag `v<version>` on the verified commit.
+6. Publish the same version to npm when applicable.
+7. Verify GitHub Release, npm tarball, GitHub Pages, `docsURI`, block icon, and CDN artifacts.
+
+The release consistency check should verify every exact-version README and CDN
+example, and should ensure that `docsURI` still resolves to the English Pages
+site and `blockIconURI` remains a `data:image/svg+xml;base64,...` URI.
+
+## License
+
+[Mozilla Public License 2.0](LICENSE) (SPDX: `MPL-2.0`).
+
+Third-party components, when present, are listed in
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).