@kubohiroya/turbowarp-document-data 0.0.0-stage → 0.2.0

package/src/document.ts

@@ -0,0 +1,254 @@
+import {fromMarkdown} from 'mdast-util-from-markdown';
+import {toMarkdown} from 'mdast-util-to-markdown';
+import {parseFragment} from 'parse5';
+import type {Root as MarkdownRoot, RootContent as MarkdownNode} from 'mdast';
+
+export const DOCUMENT_MAX_SOURCE_BYTES = 256 * 1024;
+export const DOCUMENT_MAX_OUTPUT_BYTES = 256 * 1024;
+export const DOCUMENT_MAX_NODES = 50_000;
+export const DOCUMENT_MAX_DEPTH = 64;
+
+export type DocumentKind = 'html' | 'markdown';
+export type HtmlNode =
+  | {type: 'element'; tagName: string; attributes: Record<string, string>; children: HtmlNode[]}
+  | {type: 'text'; value: string}
+  | {type: 'comment'; value: string};
+export interface HtmlRoot {type: 'root'; children: HtmlNode[]}
+export type DocumentTree =
+  | {kind: 'html'; root: HtmlRoot}
+  | {kind: 'markdown'; root: MarkdownRoot};
+
+export type DocumentErrorCode =
+  | 'INVALID_DOCUMENT'
+  | 'INVALID_NAME'
+  | 'DOCUMENT_NOT_FOUND'
+  | 'DOCUMENT_LIMIT_EXCEEDED'
+  | 'INVALID_LOCATION'
+  | 'LOCATION_NOT_FOUND'
+  | 'LOSSY_CONVERSION';
+
+export class DocumentDataError extends Error {
+  public constructor(public readonly code: DocumentErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'DocumentDataError';
+  }
+}
+
+interface Parse5Node {
+  nodeName: string;
+  tagName?: string;
+  value?: string;
+  data?: string;
+  attrs?: Array<{name: string; value: string}>;
+  childNodes?: Parse5Node[];
+}
+
+export function parseHtmlDocument(source: string): DocumentTree {
+  checkSource(source);
+  let parsed: Parse5Node;
+  try {
+    parsed = parseFragment(source) as unknown as Parse5Node;
+  } catch (error) {
+    throw new DocumentDataError('INVALID_DOCUMENT', errorMessage(error, 'Invalid HTML.'));
+  }
+  const root: HtmlRoot = {
+    type: 'root',
+    children: (parsed.childNodes ?? []).map(convertHtmlNode).filter((node): node is HtmlNode => !!node)
+  };
+  checkTree(root);
+  return {kind: 'html', root};
+}
+
+export function parseMarkdownDocument(source: string): DocumentTree {
+  checkSource(source);
+  let root: MarkdownRoot;
+  try {
+    root = stripPositions(fromMarkdown(source));
+  } catch (error) {
+    throw new DocumentDataError('INVALID_DOCUMENT', errorMessage(error, 'Invalid Markdown.'));
+  }
+  checkTree(root);
+  return {kind: 'markdown', root};
+}
+
+export function serializeDocument(tree: DocumentTree, format: DocumentKind = tree.kind): string {
+  if (format !== tree.kind) {
+    throw new DocumentDataError(
+      'LOSSY_CONVERSION',
+      `Converting ${tree.kind} to ${format} is not supported because it may be lossy.`
+    );
+  }
+  const output =
+    tree.kind === 'html'
+      ? tree.root.children.map((node) => serializeHtmlNode(node)).join('')
+      : toMarkdown(tree.root, {bullet: '-', emphasis: '*', strong: '*', fences: true});
+  if (new TextEncoder().encode(output).byteLength > DOCUMENT_MAX_OUTPUT_BYTES) {
+    throw new DocumentDataError('DOCUMENT_LIMIT_EXCEEDED', 'Serialized document is too large.');
+  }
+  return output.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+}
+
+export function getDocumentText(tree: DocumentTree, location: string): string {
+  const node = resolveLocation(tree, location);
+  return collectText(node);
+}
+
+export function replaceDocumentText(
+  tree: DocumentTree,
+  location: string,
+  text: string
+): DocumentTree {
+  const copy = structuredClone(tree);
+  const node = resolveLocation(copy, location);
+  if (copy.kind === 'html') replaceHtmlNodeText(node as HtmlRoot | HtmlNode, text);
+  else replaceMarkdownNodeText(node as MarkdownRoot | MarkdownNode, text);
+  checkTree(copy.root);
+  return copy;
+}
+
+function convertHtmlNode(node: Parse5Node): HtmlNode | undefined {
+  if (node.nodeName === '#text') return {type: 'text', value: node.value ?? ''};
+  if (node.nodeName === '#comment') return {type: 'comment', value: node.data ?? ''};
+  if (!node.tagName) return undefined;
+  return {
+    type: 'element',
+    tagName: node.tagName,
+    attributes: Object.fromEntries(
+      (node.attrs ?? [])
+        .map((attribute): [string, string] => [attribute.name, attribute.value])
+        .sort(([a], [b]) => a.localeCompare(b))
+    ),
+    children: (node.childNodes ?? []).map(convertHtmlNode).filter((child): child is HtmlNode => !!child)
+  };
+}
+
+function resolveLocation(tree: DocumentTree, rawLocation: string): unknown {
+  const location = rawLocation.trim();
+  if (location === '$') return tree.root;
+  if (tree.kind === 'html' && /^[#.a-zA-Z][\w-]*$/.test(location)) {
+    const found = findHtml(tree.root.children, location);
+    if (!found) throw new DocumentDataError('LOCATION_NOT_FOUND', `No HTML node matches ${location}.`);
+    return found;
+  }
+  const indexes = parsePath(location);
+  let current: unknown = tree.root;
+  for (const index of indexes) {
+    const children = childrenOf(current);
+    current = children[index];
+    if (current === undefined) {
+      throw new DocumentDataError('LOCATION_NOT_FOUND', `Document location does not exist: ${location}`);
+    }
+  }
+  return current;
+}
+
+function parsePath(location: string): number[] {
+  if (!/^\$(?:\[\d+\])+$/.test(location)) {
+    throw new DocumentDataError('INVALID_LOCATION', `Expected $, $[0][1], or a simple HTML selector: ${location}`);
+  }
+  return [...location.matchAll(/\[(\d+)\]/g)].map((match) => Number(match[1]));
+}
+
+function childrenOf(value: unknown): unknown[] {
+  if (typeof value !== 'object' || value === null || !('children' in value)) return [];
+  const children = (value as {children?: unknown}).children;
+  return Array.isArray(children) ? children : [];
+}
+
+function findHtml(nodes: HtmlNode[], selector: string): HtmlNode | undefined {
+  for (const node of nodes) {
+    if (node.type === 'element') {
+      const matches = selector.startsWith('#')
+        ? node.attributes.id === selector.slice(1)
+        : selector.startsWith('.')
+          ? (node.attributes.class ?? '').split(/\s+/).includes(selector.slice(1))
+          : node.tagName === selector.toLowerCase();
+      if (matches) return node;
+      const nested = findHtml(node.children, selector);
+      if (nested) return nested;
+    }
+  }
+  return undefined;
+}
+
+function collectText(value: unknown): string {
+  if (typeof value !== 'object' || value === null) return '';
+  if ('type' in value && (value as {type: string}).type === 'comment') return '';
+  if ('value' in value && typeof (value as {value?: unknown}).value === 'string') {
+    return (value as {value: string}).value;
+  }
+  return childrenOf(value).map(collectText).join('');
+}
+
+function replaceHtmlNodeText(node: HtmlRoot | HtmlNode, text: string): void {
+  if (node.type === 'text' || node.type === 'comment') {
+    node.value = text;
+    return;
+  }
+  node.children = [{type: 'text', value: text}];
+}
+
+function replaceMarkdownNodeText(node: MarkdownRoot | MarkdownNode, text: string): void {
+  if ('value' in node && typeof node.value === 'string') {
+    node.value = text;
+    return;
+  }
+  if ('children' in node && Array.isArray(node.children)) {
+    if (node.type === 'root') {
+      node.children = [{type: 'paragraph', children: [{type: 'text', value: text}]}];
+    } else {
+      node.children = [{type: 'text', value: text}];
+    }
+    return;
+  }
+  throw new DocumentDataError('INVALID_LOCATION', 'The selected Markdown node has no text content.');
+}
+
+function serializeHtmlNode(node: HtmlNode, parentTag?: string): string {
+  if (node.type === 'text') return parentTag && RAW_TEXT_ELEMENTS.has(parentTag) ? node.value : escapeHtmlText(node.value);
+  if (node.type === 'comment') return `<!--${node.value.replaceAll('--', '- -')}-->`;
+  const attributes = Object.entries(node.attributes)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => ` ${name}="${escapeHtmlAttribute(value)}"`)
+    .join('');
+  const start = `<${node.tagName}${attributes}>`;
+  if (VOID_ELEMENTS.has(node.tagName)) return start;
+  return `${start}${node.children.map((child) => serializeHtmlNode(child, node.tagName)).join('')}</${node.tagName}>`;
+}
+
+const VOID_ELEMENTS = new Set(['area','base','br','col','embed','hr','img','input','link','meta','source','track','wbr']);
+const RAW_TEXT_ELEMENTS = new Set(['script', 'style', 'xmp', 'iframe', 'noembed', 'noframes', 'plaintext']);
+const escapeHtmlText = (value: string) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;');
+const escapeHtmlAttribute = (value: string) => escapeHtmlText(value).replaceAll('"', '&quot;');
+
+function checkSource(source: string): void {
+  if (new TextEncoder().encode(source).byteLength > DOCUMENT_MAX_SOURCE_BYTES) {
+    throw new DocumentDataError('DOCUMENT_LIMIT_EXCEEDED', 'Document source is too large.');
+  }
+}
+
+function checkTree(root: unknown): void {
+  let count = 0;
+  const visit = (node: unknown, depth: number): void => {
+    count += 1;
+    if (count > DOCUMENT_MAX_NODES || depth > DOCUMENT_MAX_DEPTH) {
+      throw new DocumentDataError('DOCUMENT_LIMIT_EXCEEDED', 'Document tree exceeds its node or depth limit.');
+    }
+    for (const child of childrenOf(node)) visit(child, depth + 1);
+  };
+  visit(root, 0);
+}
+
+function stripPositions<T>(value: T): T {
+  if (Array.isArray(value)) return value.map(stripPositions) as T;
+  if (typeof value !== 'object' || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => key !== 'position')
+      .map(([key, child]) => [key, stripPositions(child)])
+  ) as T;
+}
+
+function errorMessage(error: unknown, fallback: string): string {
+  return error instanceof Error ? error.message : fallback;
+}

package/src/extension.ts

@@ -0,0 +1,136 @@
+import {fixedInputRegistration} from './fixed-input-editors.js';
+import definitions from './block-definitions.json';
+import {extensionConfig, isDocumentDataMvpEnabled} from './config.js';
+import {
+  DocumentDataError, getDocumentText, parseHtmlDocument, parseMarkdownDocument,
+  replaceDocumentText, serializeDocument, type DocumentKind, type DocumentTree
+} from './document.js';
+import {DocumentNamedDataProvider, type DocumentBinding} from './document-provider.js';
+import {
+  bindNamedDataRegistryLifecycle,
+  installNamedDataRegistry,
+  type NamedDataProviderRegistration,
+  type NamedDataRegistryService
+} from '@kubohiroya/turbowarp-named-data/composition';
+
+type BlockTypeName = 'COMMAND' | 'REPORTER' | 'BOOLEAN';
+type ArgumentTypeName = 'STRING';
+interface DefinitionArgument {type: ArgumentTypeName; defaultValue: string; menu?: string}
+interface BlockDefinition {opcode: string; blockType: BlockTypeName; text: string; description: string; arguments: Record<string, DefinitionArgument>}
+interface MenuDefinition {acceptReporters: boolean; items: string[]}
+const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
+
+export class DocumentDataExtension implements TurboWarpExtension {
+  private readonly fixedInputs = fixedInputRegistration(typeof Scratch === 'undefined' ? undefined : Scratch);
+
+  private registries = new WeakMap<object, Map<string, DocumentBinding>>();
+  private nextRevision = 1;
+  private readonly provider?: DocumentNamedDataProvider;
+  private readonly namedDataRegistry?: NamedDataRegistryService;
+  private readonly namedDataRegistration?: NamedDataProviderRegistration;
+  private readonly unbindNamedDataRegistryLifecycle?: () => void;
+
+  public constructor(private readonly enabled = isDocumentDataMvpEnabled()) {
+    const runtime = Scratch.vm?.runtime;
+    if (enabled) {
+      this.provider = new DocumentNamedDataProvider({
+        get: (target, name) => this.registries.get(target)?.get(name)
+      });
+      if (runtime) {
+        this.namedDataRegistry = installNamedDataRegistry(runtime);
+        this.namedDataRegistration = this.namedDataRegistry.registerProvider(
+          this.provider,
+          {lifetime: 'persistent'}
+        );
+        if (runtime.on) {
+          this.unbindNamedDataRegistryLifecycle = bindNamedDataRegistryLifecycle(
+            runtime as {on(event: string, listener: () => void): void},
+            this.namedDataRegistry
+          );
+          runtime.on('RUNTIME_DISPOSED', () => {
+            void this.dispose();
+          });
+        }
+      }
+    }
+    runtime?.on?.('PROJECT_STOP_ALL', () => this.clearRuntimeState());
+  }
+
+  public getNamedDataProvider(): DocumentNamedDataProvider | undefined {return this.provider;}
+  public getNamedDataRegistry(): NamedDataRegistryService | undefined {
+    return this.namedDataRegistry;
+  }
+  public async dispose(): Promise<void> {
+    this.fixedInputs.dispose();
+    await this.namedDataRegistration?.unregister();
+    this.unbindNamedDataRegistryLifecycle?.();
+  }
+
+  public getInfo(): Record<string, unknown> {
+    this.fixedInputs.ensure(this.enabled ? blockDefinitions.map(block => `${extensionConfig.id}_${block.opcode}`) : []);
+    return {
+      id: extensionConfig.id,
+      name: Scratch.translate(definitions.extensionName),
+      docsURI: extensionConfig.docsURI,
+      blockIconURI: extensionConfig.blockIconURI,
+      blocks: this.enabled ? blockDefinitions.map((block) => this.toScratchBlock(block)) : [],
+      menus: Object.fromEntries(Object.entries(definitions.menus).map(([id, menu]) => [id, this.toScratchMenu(menu)]))
+    };
+  }
+
+  public parseHtml(args: {TEXT: unknown; NAME: unknown}, util: ScratchBlockUtility): void {
+    this.setBinding(util.target, this.name(args.NAME), parseHtmlDocument(Scratch.Cast.toString(args.TEXT)));
+  }
+  public parseMarkdown(args: {TEXT: unknown; NAME: unknown}, util: ScratchBlockUtility): void {
+    this.setBinding(util.target, this.name(args.NAME), parseMarkdownDocument(Scratch.Cast.toString(args.TEXT)));
+  }
+  public hasDocument(args: {NAME: unknown}, util: ScratchBlockUtility): boolean {
+    return this.registryFor(util.target).has(this.name(args.NAME));
+  }
+  public deleteDocument(args: {NAME: unknown}, util: ScratchBlockUtility): void {
+    const name = this.name(args.NAME);
+    if (!this.registryFor(util.target).delete(name)) this.notFound(name);
+  }
+  public documentKind(args: {NAME: unknown}, util: ScratchBlockUtility): DocumentKind {
+    return this.requireBinding(util.target, args.NAME).tree.kind;
+  }
+  public getDocumentText(args: {NAME: unknown; LOCATION: unknown}, util: ScratchBlockUtility): string {
+    return getDocumentText(this.requireBinding(util.target, args.NAME).tree, Scratch.Cast.toString(args.LOCATION));
+  }
+  public replaceDocumentText(args: {NAME: unknown; LOCATION: unknown; TEXT: unknown}, util: ScratchBlockUtility): void {
+    const name = this.name(args.NAME);
+    const updated = replaceDocumentText(this.requireBindingByName(util.target, name).tree, Scratch.Cast.toString(args.LOCATION), Scratch.Cast.toString(args.TEXT));
+    this.setBinding(util.target, name, updated);
+  }
+  public serializeDocument(args: {NAME: unknown; FORMAT: unknown}, util: ScratchBlockUtility): string {
+    const format = Scratch.Cast.toString(args.FORMAT);
+    if (format !== 'html' && format !== 'markdown') throw new DocumentDataError('INVALID_DOCUMENT', `Unknown document format: ${format}`);
+    return serializeDocument(this.requireBinding(util.target, args.NAME).tree, format);
+  }
+
+  private name(value: unknown): string {
+    const name = Scratch.Cast.toString(value).trim();
+    if (!name) throw new DocumentDataError('INVALID_NAME', 'Document name cannot be empty.');
+    return name;
+  }
+  private registryFor(target: object): Map<string, DocumentBinding> {
+    let registry = this.registries.get(target);
+    if (!registry) {registry = new Map(); this.registries.set(target, registry);}
+    return registry;
+  }
+  private setBinding(target: object, name: string, tree: DocumentTree): void {
+    this.registryFor(target).set(name, {tree, revision: this.nextRevision++});
+  }
+  private requireBinding(target: object, rawName: unknown): DocumentBinding {return this.requireBindingByName(target, this.name(rawName));}
+  private requireBindingByName(target: object, name: string): DocumentBinding {
+    const binding = this.registries.get(target)?.get(name);
+    if (!binding) this.notFound(name);
+    return binding;
+  }
+  private notFound(name: string): never {throw new DocumentDataError('DOCUMENT_NOT_FOUND', `Document does not exist: ${name}`);}
+  private clearRuntimeState(): void {this.registries = new WeakMap(); this.provider?.clearSession();}
+  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, ...(argument.menu ? {menu: argument.menu} : {})}]))};
+  }
+  private toScratchMenu(menu: MenuDefinition): Record<string, unknown> {return {acceptReporters: menu.acceptReporters, items: menu.items};}
+}

package/src/fixed-input-editors.ts

@@ -0,0 +1,116 @@
+import {parseFixedNumberInput} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import type {FixedInputBinding, FixedInputEditorOptions, JsonValue, LiteralValue} from '@kubohiroya/turbowarp-extension-data-editor';
+import {fixedInputBundle} from './fixed-input-schema.js';
+const extensionId = "kubohiroyadocumentdata";
+const repository = "turbowarp-document-data";
+interface Field {opcode: string; argument: string; control: 'number' | 'enum'; choices: readonly string[];
+  normalization: string; shape: string; maxBytes: boolean}
+const fields: readonly Field[] = [
+  {
+    "opcode": "serializeDocument",
+    "argument": "FORMAT",
+    "control": "enum",
+    "choices": [
+      "html",
+      "markdown"
+    ],
+    "normalization": "identity",
+    "shape": "menu-shadow",
+    "maxBytes": false
+  }
+];
+function literalString(value: JsonValue | LiteralValue): string {
+  if (typeof value !== 'string') throw new TypeError('Expected a string literal.');
+  return value;
+}
+/** Legacy nonempty finite aliases are projections; opening never creates a write. */
+export function existingFixedNumber(value: JsonValue | LiteralValue): number {
+  if ((typeof value !== 'string' && typeof value !== 'number') ||
+      (typeof value === 'string' && value.trim() === '')) throw new TypeError('Unavailable numeric projection.');
+  const number = Number(value);
+  if (!Number.isFinite(number)) throw new TypeError('Unavailable numeric projection.');
+  return number;
+}
+function normalizeChoice(field: Field, raw: string): string {
+  if (field.normalization === 'lowercase') return raw.toLowerCase();
+  if (field.normalization === 'method') return raw.trim().toUpperCase();
+  if (field.normalization === 'trim') return raw.trim();
+  if (field.normalization === 'parse-format') {
+    const lower = raw.trim().toLowerCase();
+    return lower === 'json' ? 'JSON' : lower === 'yaml' ? 'YAML' : lower === 'auto' ? 'auto' : raw;
+  }
+  return raw;
+}
+function binding(field: Field): FixedInputBinding {
+  return {argument: field.argument, schemaBundle: fixedInputBundle(field.opcode, field.argument),
+    control: {kind: field.control, ...(field.control === 'enum' ? {choices: field.choices.map(value => ({value}))} : {})},
+    read(value) {return field.control === 'number' ? existingFixedNumber(value) : normalizeChoice(field, literalString(value));},
+    encode(value) {
+      if (field.control === 'number') {
+        const parsed = parseFixedNumberInput(value);
+        if (parsed.kind !== 'valid') throw new TypeError('Invalid new numeric input.');
+        return parsed.token;
+      }
+      const raw = literalString(value), normalized = normalizeChoice(field, raw);
+      if (!field.choices.includes(normalized)) throw new TypeError('Unsupported fixed choice.');
+      return field.shape === 'menu-shadow' || field.shape === 'direct-field-dropdown' ? normalized : raw;
+    },
+    validateCandidate(value) {
+      try {
+        if (field.control === 'number') {
+          const number = existingFixedNumber(value);
+          if (field.maxBytes && (!Number.isSafeInteger(Math.trunc(number)) || Math.trunc(number) < 1)) return [{message: 'Invalid named body size.'}];
+          return [];
+        }
+        return field.choices.includes(normalizeChoice(field, literalString(value))) ? [] : [{message: 'Unsupported fixed choice.'}];
+      } catch {return [{message: 'Invalid fixed input.'}];}
+    }
+  };
+}
+export const fixedInputEditors: readonly FixedInputEditorOptions[] = [...new Set(fields.map(f => f.opcode))].map(opcode => ({
+  apiVersion: 1, extensionId, editorId: `${opcode}-fixed-inputs`, opcodes: [`${extensionId}_${opcode}`],
+  contractId: `${repository}/${opcode}`, contractRevision: 'fixed-inputs-v1',
+  bindings: fields.filter(field => field.opcode === opcode).map(binding),
+  validationContext: () => ({consumerId: repository, nowMs: 0, settings: null})
+}));
+
+interface OptionalFixedHost {
+  gui?: {blockEditors?: {apiVersion?: number; registerFixedInputEditor?: (definition: FixedInputEditorOptions) => () => void}};
+  vm?: {runtime?: {on?: (event: string, listener: () => void) => void; off?: (event: string, listener: () => void) => void}};
+}
+/** Registration follows the advertised opcode membership and the optional host capability. */
+export function fixedInputRegistration(scratch: unknown) {
+  const host = (scratch ?? {}) as OptionalFixedHost;
+  let active: unknown;
+  let membership = '';
+  const removers: (() => void)[] = [];
+  let stopped = false;
+  const clear = () => {
+    host.vm?.runtime?.off?.('RUNTIME_DISPOSED', shutdown);
+    for (const remove of removers.splice(0).reverse()) remove();
+    active = undefined;
+    membership = '';
+  };
+  const shutdown = () => {stopped = true; clear();};
+  return {
+    ensure(visibleOpcodes: readonly string[]) {
+      const api = host.gui?.blockEditors;
+      const definitions = fixedInputEditors.filter(definition => definition.opcodes.every(opcode => visibleOpcodes.includes(opcode)));
+      const key = definitions.map(definition => definition.editorId).join(',');
+      if (stopped || (api === active && membership === key)) return;
+      clear();
+      if (api?.apiVersion !== 1 || typeof api.registerFixedInputEditor !== 'function' || !definitions.length) return;
+      try {
+        for (const definition of definitions) {
+          const remove = api.registerFixedInputEditor.call(api, definition);
+          if (typeof remove !== 'function') throw new TypeError('Invalid fixed input cleanup.');
+          removers.push(remove);
+        }
+        active = api;
+        membership = key;
+        host.vm?.runtime?.on?.('RUNTIME_DISPOSED', shutdown);
+      } catch (error) {clear(); throw error;}
+    },
+    dispose: shutdown
+  };
+}

package/src/fixed-input-schema.ts

@@ -0,0 +1,15 @@
+import type {SchemaBundle, SchemaDocument} from '@kubohiroya/turbowarp-extension-data-editor/schema';
+import document from '../schemas/block-editor-fixed-inputs.schema.json' with {type: 'json'};
+const repository = "turbowarp-document-data";
+/** The owner JSON document is canonical; this selects a primitive field fragment. */
+export function fixedInputBundle(opcode: string, argument: string): SchemaBundle {
+  const pointer = `#/$defs/${opcode}/properties/${argument}`;
+  const source = {repository, path: 'schemas/block-editor-fixed-inputs.schema.json', symbol: pointer};
+  const blocks = document.$defs as Record<string, {properties: Record<string, SchemaDocument>}>;
+  return {identity: {ownerId: repository, contractId: opcode, revision: 'fixed-inputs-v1', variantId: argument},
+    dialect: '2020-12', root: {retrievalUri: document.$id, document: blocks[opcode]!.properties[argument]!,
+      artifact: {role: 'canonical-schema', source}},
+    resources: [],
+    provenance: {canonicalSources: [source, {repository, path: 'src/extension.ts', symbol: opcode}],
+      generatedFiles: [], referenceSchemas: [], generationSources: []}};
+}

package/src/globals.d.ts

@@ -0,0 +1,28 @@
+interface TurboWarpExtension {
+  getInfo(): Record<string, unknown>;
+}
+
+interface ScratchTranslate {
+  (text: string): string;
+  (message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
+}
+
+interface ScratchApi {
+  extensions: {
+    unsandboxed: boolean;
+    register(extension: TurboWarpExtension): void;
+  };
+  BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT', 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}};
+}
+
+interface ScratchBlockUtility {target: object}
+
+declare const Scratch: ScratchApi;

package/src/index.ts

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