@drawmotive/textgraph 0.1.0-alpha.1

package/schemas/render.schema.json

@@ -0,0 +1,167 @@
+{
+  "type": "object",
+  "properties": {
+    "protocolVersion": {
+      "const": 1
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "severity": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "parse",
+              "semantic",
+              "layout",
+              "render",
+              "font"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "location": {
+            "type": "object",
+            "properties": {
+              "line": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "column": {
+                "type": "integer",
+                "minimum": 0
+              }
+            },
+            "required": [
+              "line",
+              "column"
+            ],
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "code",
+          "severity",
+          "stage",
+          "message"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "png": {
+      "type": "string",
+      "minLength": 4,
+      "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"
+    },
+    "width": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "height": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    }
+  },
+  "required": [
+    "protocolVersion",
+    "success",
+    "diagnostics"
+  ],
+  "additionalProperties": true,
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "success": {
+            "const": true
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "png",
+          "width",
+          "height"
+        ],
+        "properties": {
+          "diagnostics": {
+            "not": {
+              "contains": {
+                "type": "object",
+                "properties": {
+                  "severity": {
+                    "const": "error"
+                  }
+                }
+              }
+            },
+            "type": "array"
+          },
+          "png": {},
+          "width": {},
+          "height": {}
+        }
+      },
+      "else": {
+        "not": {
+          "anyOf": [
+            {
+              "required": [
+                "png"
+              ],
+              "properties": {
+                "png": {}
+              }
+            },
+            {
+              "required": [
+                "width"
+              ],
+              "properties": {
+                "width": {}
+              }
+            },
+            {
+              "required": [
+                "height"
+              ],
+              "properties": {
+                "height": {}
+              }
+            }
+          ]
+        },
+        "properties": {
+          "diagnostics": {
+            "contains": {
+              "type": "object",
+              "properties": {
+                "severity": {
+                  "const": "error"
+                }
+              }
+            },
+            "type": "array"
+          }
+        }
+      }
+    }
+  ]
+}

package/schemas/validation.schema.json

@@ -0,0 +1,70 @@
+{
+  "type": "object",
+  "properties": {
+    "protocolVersion": {
+      "const": 1
+    },
+    "valid": {
+      "type": "boolean"
+    },
+    "diagnostics": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "minLength": 1
+          },
+          "severity": {
+            "enum": [
+              "error",
+              "warning"
+            ]
+          },
+          "stage": {
+            "enum": [
+              "parse",
+              "semantic"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "location": {
+            "type": "object",
+            "properties": {
+              "line": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "column": {
+                "type": "integer",
+                "minimum": 0
+              }
+            },
+            "required": [
+              "line",
+              "column"
+            ],
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "code",
+          "severity",
+          "stage",
+          "message"
+        ],
+        "additionalProperties": true
+      }
+    }
+  },
+  "required": [
+    "protocolVersion",
+    "valid",
+    "diagnostics"
+  ],
+  "additionalProperties": true,
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

package/schemas/wasm-manifest.schema.json

@@ -0,0 +1,208 @@
+{
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "packageName": {
+      "const": "@drawmotive/textgraph"
+    },
+    "packageVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "abiVersion": {
+      "const": "1.0.0"
+    },
+    "protocolVersion": {
+      "const": 1
+    },
+    "targetFramework": {
+      "const": "net10.0"
+    },
+    "privateSource": {
+      "type": "object",
+      "properties": {
+        "commit": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{40}$"
+        },
+        "project": {
+          "const": "DrawMotive.TextGraph.Bridge"
+        }
+      },
+      "required": [
+        "commit",
+        "project"
+      ],
+      "additionalProperties": true
+    },
+    "entryAssembly": {
+      "type": "string"
+    },
+    "runtimeWasm": {
+      "type": "string"
+    },
+    "runtimeConfig": {
+      "type": "string"
+    },
+    "runtimeModule": {
+      "type": "string"
+    },
+    "bridge": {
+      "type": "object",
+      "properties": {
+        "assembly": {
+          "const": "DrawMotive.TextGraph.Bridge.dll"
+        },
+        "type": {
+          "const": "DrawMotive.TextGraph.Bridge.Program"
+        },
+        "info": {
+          "const": "GetRuntimeInfo"
+        },
+        "validate": {
+          "const": "Validate"
+        },
+        "execute": {
+          "const": "Execute"
+        }
+      },
+      "required": [
+        "assembly",
+        "type",
+        "info",
+        "validate"
+      ],
+      "additionalProperties": true
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true,
+      "contains": {
+        "const": "textgraph-validate-v1"
+      }
+    },
+    "assets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string",
+            "pattern": "^wasm/[A-Za-z0-9_-][A-Za-z0-9._-]*$"
+          },
+          "mediaType": {
+            "type": "string"
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "path",
+          "mediaType",
+          "bytes",
+          "sha256"
+        ],
+        "additionalProperties": true
+      }
+    },
+    "rendering": {
+      "type": "object",
+      "properties": {
+        "theme": {
+          "type": "string",
+          "pattern": "^wasm/[A-Za-z0-9_-][A-Za-z0-9._-]*[.]css$"
+        },
+        "fonts": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "family": {
+                "type": "string",
+                "minLength": 1
+              },
+              "asset": {
+                "type": "string",
+                "pattern": "^wasm/[A-Za-z0-9_-][A-Za-z0-9._-]*[.](ttf|otf)$"
+              }
+            },
+            "required": [
+              "family",
+              "asset"
+            ],
+            "additionalProperties": true
+          }
+        }
+      },
+      "required": [
+        "theme",
+        "fonts"
+      ],
+      "additionalProperties": true
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "packageName",
+    "packageVersion",
+    "abiVersion",
+    "protocolVersion",
+    "targetFramework",
+    "privateSource",
+    "entryAssembly",
+    "runtimeWasm",
+    "runtimeConfig",
+    "runtimeModule",
+    "bridge",
+    "capabilities",
+    "assets"
+  ],
+  "additionalProperties": true,
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "capabilities": {
+            "contains": {
+              "const": "textgraph-render-v1"
+            },
+            "type": "array"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "rendering"
+        ],
+        "properties": {
+          "bridge": {
+            "type": "object",
+            "properties": {
+              "execute": {
+                "const": "Execute"
+              }
+            },
+            "required": [
+              "execute"
+            ]
+          },
+          "rendering": {}
+        }
+      }
+    }
+  ]
+}

package/src/adapters.js

@@ -0,0 +1,27 @@
+import { DrawMotiveError } from './runtime/errors.js';
+
+const contracts = Object.freeze({ files: ['open', 'save'], network: ['fetch'] });
+
+/** Validates TextGraph host adapters and captures an immutable method snapshot. */
+export function validateTextGraphAdapters(adapters = {}) {
+  if (adapters === null || typeof adapters !== 'object') invalid('adapters');
+  const snapshot = {};
+  for (const [name, methods] of Object.entries(contracts)) {
+    const adapter = adapters[name];
+    if (adapter === undefined) continue;
+    if (adapter === null || typeof adapter !== 'object') invalid(name);
+    const captured = {};
+    for (const method of methods) {
+      if (typeof adapter[method] !== 'function') invalid(name, method);
+      captured[method] = adapter[method].bind(adapter);
+    }
+    snapshot[name] = Object.freeze(captured);
+  }
+  return Object.freeze(snapshot);
+}
+
+function invalid(adapter, method) {
+  throw new DrawMotiveError('INVALID_ADAPTER', `Adapter ${adapter}${method ? `.${method}` : ''} does not satisfy its contract`, {
+    details: { adapter, method: method ?? null },
+  });
+}

package/src/index.d.ts

@@ -0,0 +1,171 @@
+export interface TextGraphRuntimeManifest {
+  readonly packageName: '@drawmotive/textgraph';
+  readonly packageVersion: string;
+  readonly abiVersion: string;
+}
+
+export interface TextGraphAbiManifest extends TextGraphRuntimeManifest {
+  readonly schemaVersion: 1;
+  readonly protocolVersion: 1;
+  readonly targetFramework: 'net10.0';
+  readonly privateSource: { readonly commit: string; readonly project: string };
+  readonly entryAssembly: string;
+  readonly runtimeWasm: string;
+  readonly runtimeConfig: string;
+  readonly runtimeModule: string;
+  readonly bridge: { readonly assembly: string; readonly type: string; readonly info: string; readonly validate: string; readonly execute?: string };
+  readonly rendering?: {
+    readonly theme: string;
+    readonly fonts: readonly { readonly family: string; readonly asset: string }[];
+  };
+  readonly capabilities: readonly string[];
+  readonly assets: readonly Required<RuntimeAsset>[];
+}
+
+export interface RuntimeAsset {
+  readonly path: string;
+  readonly mediaType?: string;
+  readonly bytes?: number;
+  readonly sha256?: string;
+}
+
+export interface RuntimeAssetManifest {
+  readonly assets: readonly RuntimeAsset[];
+}
+
+export interface ResolvedRuntimeAsset {
+  readonly asset: RuntimeAsset;
+  readonly url: URL;
+}
+
+export interface LoadedRuntimeAsset extends Omit<RuntimeAsset, 'bytes'> {
+  readonly url: URL;
+  readonly bytes: Uint8Array;
+}
+
+export interface RuntimeAssetLoader {
+  readonly plan: readonly ResolvedRuntimeAsset[];
+  loadAssets(): Promise<ReadonlyMap<string, LoadedRuntimeAsset>>;
+}
+
+export interface TextGraphInstance {
+  readonly state: 'ready' | 'disposing' | 'disposed';
+  readonly info: TextGraphRuntimeInfo;
+  validate(source: string, options?: { signal?: AbortSignal }): Promise<TextGraphValidationResult>;
+  renderPng(source: string, options?: TextGraphRenderPngOptions<'bytes'>): Promise<TextGraphRenderPngResult<Uint8Array>>;
+  renderPng(source: string, options: TextGraphRenderPngOptions<'base64'> & { encoding: 'base64' }): Promise<TextGraphRenderPngResult<string>>;
+  renderPng(source: string, options: TextGraphRenderPngOptions): Promise<TextGraphRenderPngResult<Uint8Array | string>>;
+  readonly<T>(operation: () => T | Promise<T>): Promise<T>;
+  mutate<T>(operation: () => T | Promise<T>): Promise<T>;
+  dispose(): Promise<void>;
+}
+
+export interface TextGraphRuntime {
+  readonly abiVersion: string;
+  readonly capabilities?: readonly string[];
+  validate?(source: string): string | Promise<string>;
+  execute?(requestJson: string, context?: { signal?: AbortSignal }): string | Promise<string>;
+  dispose?(): void | Promise<void>;
+}
+
+export interface AdapterContext {
+  readonly signal?: AbortSignal;
+}
+
+export interface FileAdapter {
+  open(path: string, context: AdapterContext): Promise<Uint8Array>;
+  save(path: string, data: Uint8Array, context: AdapterContext): Promise<void>;
+}
+
+export interface NetworkAdapter {
+  fetch(input: RequestInfo | URL, init: RequestInit & AdapterContext): Promise<Response>;
+}
+
+export interface TextGraphAdapters {
+  readonly files?: FileAdapter;
+  readonly network?: NetworkAdapter;
+}
+
+export interface TextGraphInitializeOptions {
+  /** Development hook. Default platform loading requires no custom runtime. */
+  loadRuntime?(options: TextGraphInitializeOptions): Promise<TextGraphRuntime>;
+  signal?: AbortSignal;
+  adapters?: TextGraphAdapters;
+  resolveAsset?(asset: RuntimeAsset, defaultUrl: URL): string | URL;
+  fetch?: typeof globalThis.fetch;
+  /** Font data is copied during initialization and loaded only before the first render. */
+  languagePacks?: readonly TextGraphLanguagePack[];
+}
+
+export interface TextGraphFont {
+  readonly family: string;
+  /** Use a URL (including file: in Node) or bytes; bytes are copied during initialization. */
+  readonly source: URL | Uint8Array;
+}
+
+export interface TextGraphLanguagePack {
+  readonly fonts: readonly TextGraphFont[];
+  /** Ordered fallback families supplied by this initialization, after explicit diagram fonts. */
+  readonly fallbackFamilies?: readonly string[];
+}
+
+export type TextGraphPngEncoding = 'bytes' | 'base64';
+
+export interface TextGraphRenderPngOptions<Encoding extends TextGraphPngEncoding = TextGraphPngEncoding> {
+  /** Defaults to bytes. Base64 contains no data-URL prefix. */
+  encoding?: Encoding;
+  /** Positive render scale. Defaults to 2. */
+  scale?: number;
+  /** Non-negative padding in diagram units. Defaults to 10. */
+  padding?: number;
+  /** Positive integer upper bound on output width in pixels. */
+  maxWidth?: number;
+  /** Cancellation cannot preempt native work already running on this thread. */
+  signal?: AbortSignal;
+}
+
+export type TextGraphRenderPngResult<Png extends Uint8Array | string = Uint8Array | string> =
+  | { readonly success: true; readonly png: Png; readonly width: number; readonly height: number; readonly diagnostics: readonly TextGraphRenderDiagnostic[] }
+  | { readonly success: false; readonly diagnostics: readonly TextGraphRenderDiagnostic[] };
+
+export interface TextGraphRuntimeInfo extends TextGraphRuntimeManifest {
+  readonly protocolVersion: 1;
+  readonly capabilities: readonly string[];
+}
+
+export interface TextGraphDiagnostic {
+  readonly code: string;
+  readonly severity: 'error' | 'warning';
+  readonly stage: 'parse' | 'semantic';
+  readonly message: string;
+  /** Zero-based line and UTF-16 column; no fabricated end range. */
+  readonly location?: { readonly line: number; readonly column: number };
+}
+
+export interface TextGraphValidationResult {
+  readonly valid: boolean;
+  readonly diagnostics: readonly TextGraphDiagnostic[];
+}
+
+export interface TextGraphRenderDiagnostic extends Omit<TextGraphDiagnostic, 'stage'> {
+  readonly stage: 'parse' | 'semantic' | 'layout' | 'render' | 'font';
+}
+
+export declare const abiManifest: Readonly<TextGraphAbiManifest>;
+
+export declare class DrawMotiveError extends Error {
+  readonly code: string;
+  readonly details: Readonly<Record<string, unknown>>;
+}
+
+export declare function validateTextGraphAdapters(adapters?: TextGraphAdapters): Readonly<TextGraphAdapters>;
+
+export declare function resolveRuntimeAssets(options: {
+  manifest: RuntimeAssetManifest;
+  moduleUrl?: string | URL;
+  resolveAsset?(asset: RuntimeAsset, defaultUrl: URL): string | URL;
+}): readonly ResolvedRuntimeAsset[];
+
+export declare function initializeTextGraph(
+  options?: TextGraphInitializeOptions,
+): Promise<TextGraphInstance>;