@kubohiroya/turbowarp-structured-data 0.4.0

package/src/extension-manifest.ts

@@ -0,0 +1,176 @@
+import type {Plugin} from 'vite';
+
+export const EXTENSION_MANIFEST_FORMAT_VERSION = 3 as const;
+
+export interface ExtensionManifestArgument {
+  id: string;
+  type: string;
+  normalizesTo?: 'pathSegments';
+  staticLiteral?: boolean;
+  minimum?: number;
+  maximum?: number;
+}
+
+export interface ExtensionManifestBlock {
+  opcode: string;
+  blockType: string;
+  arguments: ExtensionManifestArgument[];
+  resultType: string;
+  effect: 'pure' | 'immutable' | 'state' | 'control';
+  immutable: boolean;
+  errors: string[];
+  server: {supported: boolean; irOperation: string};
+}
+
+export interface ExtensionManifest {
+  formatVersion: typeof EXTENSION_MANIFEST_FORMAT_VERSION;
+  id: string;
+  pathSegmentType: {
+    kind: 'discriminatedUnion';
+    variants: Array<{kind: 'key' | 'index'; valueType: 'string' | 'nonNegativeInteger'}>;
+  };
+  dataReferenceType: {
+    kind: 'named';
+    scope: 'target';
+    lifetime: 'untilProjectStop';
+    valueType: 'jsonValue';
+  };
+  blocks: ExtensionManifestBlock[];
+}
+
+export interface ExtensionManifestPluginOptions {
+  id: string;
+  definitions: unknown;
+  fileName?: string;
+}
+
+export function createExtensionManifest(id: string, definitions: unknown): ExtensionManifest {
+  if (!/^[a-z0-9]+$/.test(id)) {
+    throw new TypeError('Extension manifest ID must contain only lowercase letters and numbers.');
+  }
+  const source = requireRecord(definitions, 'Block definitions');
+  if (!Array.isArray(source.blocks)) {
+    throw new TypeError('Block definitions must contain a blocks array.');
+  }
+  const seenOpcodes = new Set<string>();
+  const blocks = source.blocks.map((block, index) => {
+    const normalized = normalizeBlock(block, index);
+    if (seenOpcodes.has(normalized.opcode)) {
+      throw new TypeError(`Duplicate block opcode: ${normalized.opcode}`);
+    }
+    seenOpcodes.add(normalized.opcode);
+    return normalized;
+  });
+  return {
+    formatVersion: EXTENSION_MANIFEST_FORMAT_VERSION,
+    id,
+    pathSegmentType: {
+      kind: 'discriminatedUnion',
+      variants: [
+        {kind: 'key', valueType: 'string'},
+        {kind: 'index', valueType: 'nonNegativeInteger'}
+      ]
+    },
+    dataReferenceType: {
+      kind: 'named',
+      scope: 'target',
+      lifetime: 'untilProjectStop',
+      valueType: 'jsonValue'
+    },
+    blocks: blocks.sort((left, right) => compareIds(left.opcode, right.opcode))
+  };
+}
+
+export function serializeExtensionManifest(id: string, definitions: unknown): string {
+  return `${JSON.stringify(createExtensionManifest(id, definitions), null, 2)}\n`;
+}
+
+export function extensionManifestPlugin(options: ExtensionManifestPluginOptions): Plugin {
+  return {
+    name: 'extension-api-manifest',
+    apply: 'build',
+    enforce: 'post',
+    generateBundle() {
+      this.emitFile({
+        type: 'asset',
+        fileName: options.fileName ?? 'extension-manifest.json',
+        source: serializeExtensionManifest(options.id, options.definitions)
+      });
+    }
+  };
+}
+
+function normalizeBlock(value: unknown, index: number): ExtensionManifestBlock {
+  const block = requireRecord(value, `Block at index ${index}`);
+  const opcode = requireNonEmptyString(block.opcode, `Block at index ${index} opcode`);
+  const argumentRecord = requireRecord(block.arguments ?? {}, `Block ${opcode} arguments`);
+  const argumentsList = Object.entries(argumentRecord).map(([id, value]) => {
+    const argument = requireRecord(value, `Block ${opcode} argument ${id}`);
+    const result: ExtensionManifestArgument = {
+      id: requireNonEmptyString(id, `Block ${opcode} argument ID`),
+      type: requireNonEmptyString(argument.type, `Block ${opcode} argument ${id} type`)
+    };
+    if (argument.normalizesTo !== undefined) {
+      if (argument.normalizesTo !== 'pathSegments') {
+        throw new TypeError(`Block ${opcode} argument ${id} has an unknown normalized type.`);
+      }
+      result.normalizesTo = argument.normalizesTo;
+    }
+    if (argument.staticLiteral !== undefined) result.staticLiteral = requireBoolean(argument.staticLiteral, `${opcode}.${id}.staticLiteral`);
+    if (argument.minimum !== undefined) result.minimum = requireNumber(argument.minimum, `${opcode}.${id}.minimum`);
+    if (argument.maximum !== undefined) result.maximum = requireNumber(argument.maximum, `${opcode}.${id}.maximum`);
+    return result;
+  });
+  const server = requireRecord(block.server, `Block ${opcode} server contract`);
+  const effect = block.effect;
+  if (
+    effect !== 'pure' &&
+    effect !== 'immutable' &&
+    effect !== 'state' &&
+    effect !== 'control'
+  ) {
+    throw new TypeError(`Block ${opcode} must define a supported effect.`);
+  }
+  if (!Array.isArray(block.errors) || !block.errors.every((code) => typeof code === 'string')) {
+    throw new TypeError(`Block ${opcode} errors must be an array of strings.`);
+  }
+  return {
+    opcode,
+    blockType: requireNonEmptyString(block.blockType, `Block ${opcode} blockType`),
+    arguments: argumentsList.sort((left, right) => compareIds(left.id, right.id)),
+    resultType: requireNonEmptyString(block.resultType, `Block ${opcode} resultType`),
+    effect,
+    immutable: requireBoolean(block.immutable, `Block ${opcode} immutable`),
+    errors: [...block.errors],
+    server: {
+      supported: requireBoolean(server.supported, `Block ${opcode} server.supported`),
+      irOperation: requireNonEmptyString(server.irOperation, `Block ${opcode} server.irOperation`)
+    }
+  };
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireNonEmptyString(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new TypeError(`${label} must be a non-empty string.`);
+  return value;
+}
+
+function requireBoolean(value: unknown, label: string): boolean {
+  if (typeof value !== 'boolean') throw new TypeError(`${label} must be a boolean.`);
+  return value;
+}
+
+function requireNumber(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) throw new TypeError(`${label} must be a finite number.`);
+  return value;
+}
+
+function compareIds(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/extension.ts

@@ -0,0 +1,361 @@
+import definitions from './block-definitions.json';
+import {
+  bindNamedDataRegistryLifecycle,
+  installNamedDataRegistry,
+  type NamedDataProviderRegistration,
+  type NamedDataRegistryService
+} from '@kubohiroya/turbowarp-named-data/composition';
+import {
+  extensionConfig,
+  isNamedDataRegistryMvpEnabled,
+  isStructuredDataMvpEnabled
+} from './config.js';
+import {
+  parseJsonDocument,
+  parseYamlDocument,
+  renderJsonDocument,
+  renderYamlDocument
+} from './codecs.js';
+import {
+  deleteAtPath,
+  getAtPath,
+  hasAtPath,
+  iterationEntries,
+  keysAtPath,
+  lengthAtPath,
+  parseJson as parseJsonValue,
+  parsePath,
+  setAtPath,
+  stringifyJson,
+  StructuredDataError,
+  type IterationEntry,
+  type JsonValue
+} from './core.js';
+import {
+  StructuredDataNamedDataProvider,
+  type StructuredDataBinding
+} from './structured-provider.js';
+
+type BlockTypeName = 'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'LOOP';
+type ArgumentTypeName = 'STRING' | 'NUMBER';
+
+interface DefinitionArgument {
+  type: ArgumentTypeName;
+  defaultValue: string | number;
+}
+
+interface BlockDefinition {
+  opcode: string;
+  blockType: BlockTypeName;
+  text: string;
+  description: string;
+  arguments: Record<string, DefinitionArgument>;
+}
+
+interface NamedPathArguments {
+  NAME: unknown;
+  PATH: unknown;
+}
+
+interface LoopState {
+  entries: IterationEntry[];
+  cursor: number;
+  active: boolean;
+}
+
+interface ActiveIteration extends IterationEntry {
+  index: number;
+}
+
+const LOOP_STATE = 'structuredDataLoopState';
+const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
+
+export class StructuredDataExtension implements TurboWarpExtension {
+  private readonly enabled: boolean;
+  private registries = new WeakMap<object, Map<string, StructuredDataBinding>>();
+  private iterationStacks = new WeakMap<object, ActiveIteration[]>();
+  private nextRevision = 1;
+  private readonly namedDataProvider?: StructuredDataNamedDataProvider;
+  private readonly namedDataRegistry?: NamedDataRegistryService;
+  private readonly namedDataRegistration?: NamedDataProviderRegistration;
+  private readonly unbindNamedDataRegistryLifecycle?: () => void;
+
+  public constructor(
+    enabled = isStructuredDataMvpEnabled(),
+    namedDataEnabled = isNamedDataRegistryMvpEnabled()
+  ) {
+    this.enabled = enabled;
+    if (namedDataEnabled) {
+      this.namedDataProvider = new StructuredDataNamedDataProvider({
+        get: (target, name) => this.registries.get(target)?.get(name)
+      });
+      const runtime = Scratch.vm?.runtime;
+      if (runtime) {
+        this.namedDataRegistry = installNamedDataRegistry(runtime);
+        this.namedDataRegistration = this.namedDataRegistry.registerProvider(
+          this.namedDataProvider,
+          {lifetime: 'persistent'}
+        );
+        this.unbindNamedDataRegistryLifecycle = bindNamedDataRegistryLifecycle(
+          runtime,
+          this.namedDataRegistry
+        );
+        runtime.on?.('RUNTIME_DISPOSED', () => {
+          void this.dispose();
+        });
+      }
+    }
+    Scratch.vm?.runtime?.on?.('PROJECT_STOP_ALL', () => this.clearRuntimeState());
+  }
+
+  public getNamedDataProvider(): StructuredDataNamedDataProvider | undefined {
+    return this.namedDataProvider;
+  }
+
+  public getNamedDataRegistry(): NamedDataRegistryService | undefined {
+    return this.namedDataRegistry;
+  }
+
+  public async dispose(): Promise<void> {
+    await this.namedDataRegistration?.unregister();
+    this.unbindNamedDataRegistryLifecycle?.();
+  }
+
+  public getInfo(): Record<string, unknown> {
+    return {
+      id: extensionConfig.id,
+      name: Scratch.translate(definitions.extensionName),
+      docsURI: extensionConfig.docsURI,
+      blockIconURI: extensionConfig.blockIconURI,
+      blocks: this.enabled ? blockDefinitions.map((block) => this.toScratchBlock(block)) : []
+    };
+  }
+
+  public parseJson(args: {TEXT: unknown; NAME: unknown}, util: ScratchBlockUtility): void {
+    this.store(
+      util.target,
+      args.NAME,
+      parseJsonDocument(Scratch.Cast.toString(args.TEXT)),
+      'json'
+    );
+  }
+
+  public parseYaml(args: {TEXT: unknown; NAME: unknown}, util: ScratchBlockUtility): void {
+    this.store(
+      util.target,
+      args.NAME,
+      parseYamlDocument(Scratch.Cast.toString(args.TEXT)),
+      'yaml'
+    );
+  }
+
+  public toJson(args: {NAME: unknown}, util: ScratchBlockUtility): string {
+    return renderJsonDocument(this.requireData(util.target, args.NAME));
+  }
+
+  public toYaml(args: {NAME: unknown}, util: ScratchBlockUtility): string {
+    return renderYamlDocument(this.requireData(util.target, args.NAME));
+  }
+
+  public hasStructuredData(args: {NAME: unknown}, util: ScratchBlockUtility): boolean {
+    return this.registryFor(util.target).has(this.name(args.NAME));
+  }
+
+  public deleteStructuredData(args: {NAME: unknown}, util: ScratchBlockUtility): void {
+    const registry = this.registryFor(util.target);
+    const name = this.name(args.NAME);
+    if (!registry.delete(name)) this.dataNotFound(name);
+  }
+
+  public getJsonAtPath(args: NamedPathArguments, util: ScratchBlockUtility): string {
+    return stringifyJson(
+      getAtPath(this.requireData(util.target, args.NAME), this.path(args.PATH))
+    );
+  }
+
+  public hasPath(args: NamedPathArguments, util: ScratchBlockUtility): boolean {
+    return hasAtPath(this.requireData(util.target, args.NAME), this.path(args.PATH));
+  }
+
+  public setJsonAtPath(
+    args: NamedPathArguments & {VALUE: unknown},
+    util: ScratchBlockUtility
+  ): void {
+    const name = this.name(args.NAME);
+    const updated = setAtPath(
+      this.requireDataByName(util.target, name),
+      this.path(args.PATH),
+      parseJsonValue(Scratch.Cast.toString(args.VALUE))
+    );
+    this.setBinding(util.target, name, updated);
+  }
+
+  public deleteAtPath(args: NamedPathArguments, util: ScratchBlockUtility): void {
+    const name = this.name(args.NAME);
+    const updated = deleteAtPath(
+      this.requireDataByName(util.target, name),
+      this.path(args.PATH)
+    );
+    this.setBinding(util.target, name, updated);
+  }
+
+  public keysAtPath(args: NamedPathArguments, util: ScratchBlockUtility): string {
+    return JSON.stringify(
+      keysAtPath(this.requireData(util.target, args.NAME), this.path(args.PATH))
+    );
+  }
+
+  public lengthAtPath(args: NamedPathArguments, util: ScratchBlockUtility): number {
+    return lengthAtPath(this.requireData(util.target, args.NAME), this.path(args.PATH));
+  }
+
+  public forEachAtPath(
+    args: NamedPathArguments & {MAX: unknown},
+    util: ScratchBlockUtility
+  ): void {
+    let state = util.stackFrame[LOOP_STATE] as LoopState | undefined;
+    const stack = this.stackFor(util.thread);
+
+    if (!state) {
+      state = {
+        entries: iterationEntries(
+          this.requireData(util.target, args.NAME),
+          this.path(args.PATH),
+          Scratch.Cast.toNumber(args.MAX)
+        ),
+        cursor: 0,
+        active: false
+      };
+      util.stackFrame[LOOP_STATE] = state;
+    } else if (state.active) {
+      if (stack.at(-1)?.index === state.cursor) stack.pop();
+      state.cursor += 1;
+      state.active = false;
+    }
+
+    const entry = state.entries[state.cursor];
+    if (!entry) {
+      delete util.stackFrame[LOOP_STATE];
+      if (stack.length === 0) this.iterationStacks.delete(util.thread);
+      return;
+    }
+
+    stack.push({...entry, index: state.cursor});
+    state.active = true;
+    util.startBranch(1, true);
+  }
+
+  public currentKey(_args: Record<string, never>, util: ScratchBlockUtility): string {
+    return this.currentIteration(util.thread).key;
+  }
+
+  public currentIndex(_args: Record<string, never>, util: ScratchBlockUtility): number {
+    return this.currentIteration(util.thread).index;
+  }
+
+  public currentValueJson(_args: Record<string, never>, util: ScratchBlockUtility): string {
+    return stringifyJson(this.currentIteration(util.thread).value);
+  }
+
+  private store(
+    target: object,
+    rawName: unknown,
+    value: JsonValue,
+    nativeRepresentation: 'json' | 'yaml'
+  ): void {
+    this.setBinding(target, this.name(rawName), value, nativeRepresentation);
+  }
+
+  private requireData(target: object, rawName: unknown): JsonValue {
+    return this.requireDataByName(target, this.name(rawName));
+  }
+
+  private requireDataByName(target: object, name: string): JsonValue {
+    const binding = this.registryFor(target).get(name);
+    if (binding === undefined) this.dataNotFound(name);
+    return binding.value;
+  }
+
+  private registryFor(target: object): Map<string, StructuredDataBinding> {
+    let registry = this.registries.get(target);
+    if (!registry) {
+      registry = new Map();
+      this.registries.set(target, registry);
+    }
+    return registry;
+  }
+
+  private setBinding(
+    target: object,
+    name: string,
+    value: JsonValue,
+    nativeRepresentation?: 'json' | 'yaml'
+  ): void {
+    const registry = this.registryFor(target);
+    const retainedRepresentation =
+      nativeRepresentation ?? registry.get(name)?.nativeRepresentation ?? 'json';
+    registry.set(name, {
+      value,
+      revision: this.nextRevision,
+      nativeRepresentation: retainedRepresentation
+    });
+    this.nextRevision += 1;
+  }
+
+  private name(value: unknown): string {
+    const name = Scratch.Cast.toString(value).trim();
+    if (name.length === 0) {
+      throw new StructuredDataError('INVALID_NAME', 'Structured data name cannot be empty.');
+    }
+    return name;
+  }
+
+  private dataNotFound(name: string): never {
+    throw new StructuredDataError('DATA_NOT_FOUND', `Structured data does not exist: ${name}`);
+  }
+
+  private currentIteration(thread: object): ActiveIteration {
+    const current = this.iterationStacks.get(thread)?.at(-1);
+    if (!current) {
+      throw new StructuredDataError(
+        'ITERATION_CONTEXT_REQUIRED',
+        'This reporter is only valid inside an active iteration.'
+      );
+    }
+    return current;
+  }
+
+  private stackFor(thread: object): ActiveIteration[] {
+    let stack = this.iterationStacks.get(thread);
+    if (!stack) {
+      stack = [];
+      this.iterationStacks.set(thread, stack);
+    }
+    return stack;
+  }
+
+  private path(value: unknown) {
+    return parsePath(Scratch.Cast.toString(value));
+  }
+
+  private clearRuntimeState(): void {
+    this.namedDataProvider?.clearSession();
+    this.registries = new WeakMap();
+    this.iterationStacks = new WeakMap();
+    this.nextRevision = 1;
+  }
+
+  private toScratchBlock(block: BlockDefinition): Record<string, unknown> {
+    return {
+      opcode: block.opcode,
+      blockType: Scratch.BlockType[block.blockType],
+      text: Scratch.translate(block.text),
+      arguments: Object.fromEntries(
+        Object.entries(block.arguments).map(([name, argument]) => [
+          name,
+          {type: Scratch.ArgumentType[argument.type], defaultValue: argument.defaultValue}
+        ])
+      )
+    };
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,38 @@
+interface TurboWarpExtension {
+  getInfo(): Record<string, unknown>;
+}
+
+interface ScratchTranslate {
+  (text: string): string;
+  (message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
+}
+
+interface ScratchBlockUtility {
+  thread: object;
+  target: object;
+  stackFrame: Record<string, unknown>;
+  startBranch(branchNumber: number, isLoop: boolean): void;
+}
+
+interface ScratchApi {
+  extensions: {
+    unsandboxed: boolean;
+    register(extension: TurboWarpExtension): void;
+  };
+  BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT' | 'LOOP', string>;
+  ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
+  Cast: {
+    toString(value: unknown): string;
+    toNumber(value: unknown): number;
+    toBoolean(value: unknown): boolean;
+  };
+  translate: ScratchTranslate;
+  vm?: {
+    runtime?: {
+      on(event: string, listener: () => void): void;
+      off?(event: string, listener: () => void): void;
+    };
+  };
+}
+
+declare const Scratch: ScratchApi;

package/src/index.ts

@@ -0,0 +1,8 @@
+import {extensionConfig} from './config.js';
+import {StructuredDataExtension} from './extension.js';
+
+if (extensionConfig.unsandboxed && !Scratch.extensions.unsandboxed) {
+  throw new Error(`${extensionConfig.name} must run unsandboxed.`);
+}
+
+Scratch.extensions.register(new StructuredDataExtension());