@drawmotive/textgraph 0.1.0-alpha.1

package/src/index.js

@@ -0,0 +1,78 @@
+import { validateTextGraphAdapters } from './adapters.js';
+import { createManagedInstance, throwIfAborted, validateAbi, waitForInitialResource } from './runtime/lifecycle.js';
+import { decodeValidation, validateSignal } from './runtime/validation.js';
+import { DrawMotiveError } from './runtime/errors.js';
+import { normalizeLanguagePacks } from './runtime/language-packs.js';
+import { decodeRender, normalizeRenderOptions } from './runtime/rendering.js';
+import manifest from '../generated/wasm-manifest.js';
+
+export { validateTextGraphAdapters } from './adapters.js';
+export { DrawMotiveError } from './runtime/errors.js';
+export { resolveRuntimeAssets } from './runtime/assets.js';
+
+const freeze = value => {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freeze); Object.freeze(value); }
+  return value;
+};
+export const abiManifest = freeze(structuredClone(manifest));
+
+/** Initializes one headless TextGraph instance through the selected platform loader. */
+export async function initializeTextGraph(options = {}) {
+  if (!options || typeof options !== 'object') throw new DrawMotiveError('INVALID_ARGUMENT', 'Initialization options must be an object');
+  for (const key of ['resolveAsset', 'fetch', 'loadRuntime']) {
+    if (options[key] !== undefined && typeof options[key] !== 'function') throw new DrawMotiveError('INVALID_ARGUMENT', `${key} must be a function`);
+  }
+  validateSignal(options.signal);
+  if (typeof options.loadRuntime !== 'function') {
+    throw new TypeError('initializeTextGraph requires a loadRuntime function');
+  }
+  const normalized = Object.freeze({ ...options, adapters: validateTextGraphAdapters(options.adapters), languagePacks: normalizeLanguagePacks(options.languagePacks) });
+  const runtime = await waitForInitialResource(() => options.loadRuntime(normalized), options.signal);
+  await validateAbi(runtime, abiManifest.abiVersion);
+  const instance = createManagedInstance([runtime]);
+  const capabilities = runtime.capabilities ?? [
+    ...(typeof runtime.validate === 'function' ? ['textgraph-validate-v1'] : []),
+    ...(typeof runtime.execute === 'function' ? ['textgraph-render-v1'] : []),
+  ];
+  const info = Object.freeze({ packageName: abiManifest.packageName, packageVersion: abiManifest.packageVersion, abiVersion: runtime.abiVersion, protocolVersion: 1, capabilities: Object.freeze([...capabilities]) });
+  return Object.assign(instance, {
+    info,
+    async renderPng(source, callOptions = {}) {
+      if (instance.state !== 'ready') throw new DrawMotiveError('INSTANCE_DISPOSED', 'The runtime instance is disposing or disposed');
+      const { request, encoding, signal } = normalizeRenderOptions(source, callOptions);
+      throwIfAborted(signal);
+      if (typeof runtime.execute !== 'function' || !capabilities.includes('textgraph-render-v1')) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Runtime does not support PNG rendering');
+      return instance.mutate(async () => {
+        throwIfAborted(signal);
+        let response;
+        try { response = await runtime.execute(JSON.stringify(request), { signal }); }
+        catch (cause) {
+          throwIfAborted(signal);
+          if (cause instanceof DrawMotiveError || cause?.name === 'AbortError') throw cause;
+          throw new DrawMotiveError('RUNTIME_FAILED', 'PNG rendering could not execute', { cause });
+        }
+        throwIfAborted(signal);
+        return decodeRender(response, encoding);
+      });
+    },
+    async validate(source, callOptions = {}) {
+      if (instance.state !== 'ready') throw new DrawMotiveError('INSTANCE_DISPOSED', 'The runtime instance is disposing or disposed');
+      if (typeof source !== 'string' || !callOptions || typeof callOptions !== 'object') throw new DrawMotiveError('INVALID_ARGUMENT', 'Validation requires a source string and options object');
+      validateSignal(callOptions.signal);
+      throwIfAborted(callOptions.signal);
+      if (typeof runtime.validate !== 'function') throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Runtime does not support validation');
+      return instance.mutate(async () => {
+        throwIfAborted(callOptions.signal);
+        let response;
+        try { response = await runtime.validate(source); }
+        catch (cause) {
+          throwIfAborted(callOptions.signal);
+          if (cause?.name === 'AbortError') throw cause;
+          throw new DrawMotiveError('RUNTIME_FAILED', 'Validation could not execute', { cause });
+        }
+        throwIfAborted(callOptions.signal);
+        return decodeValidation(response);
+      });
+    },
+  });
+}

package/src/platform/browser.d.ts

@@ -0,0 +1,13 @@
+export * from '../index.js';
+
+import type { RuntimeAsset, RuntimeAssetLoader, RuntimeAssetManifest } from '../index.js';
+
+export declare const platform: 'browser';
+
+export declare function createTextGraphRuntimeLoader(options: {
+  manifest: RuntimeAssetManifest;
+  moduleUrl?: string | URL;
+  baseUrl?: string | URL;
+  resolveAsset?(asset: RuntimeAsset, defaultUrl: URL): string | URL;
+  fetch?: typeof fetch;
+}): RuntimeAssetLoader;

package/src/platform/browser.js

@@ -0,0 +1,13 @@
+export * from '../index.js';
+import { initializeTextGraph as initialize } from '../index.js';
+import { loadBrowserRuntime } from '../runtime/browser.js';
+import manifest from '../../generated/wasm-manifest.js';
+import { DrawMotiveError } from '../runtime/errors.js';
+
+export async function initializeTextGraph(options = {}) {
+  if (!options || typeof options !== 'object') throw new DrawMotiveError('INVALID_ARGUMENT', 'Initialization options must be an object');
+  return initialize({ ...options, loadRuntime: options.loadRuntime ?? (context => loadBrowserRuntime(context, manifest)) });
+}
+export { createTextGraphRuntimeLoader } from '../runtime/browser.js';
+
+export const platform = 'browser';

package/src/platform/node.d.ts

@@ -0,0 +1,3 @@
+export * from '../index.js';
+
+export declare const platform: 'node';

package/src/platform/node.js

@@ -0,0 +1,12 @@
+export * from '../index.js';
+import { initializeTextGraph as initialize } from '../index.js';
+import { loadNodeRuntime } from '../runtime/node.js';
+import manifest from '../../generated/wasm-manifest.js';
+import { DrawMotiveError } from '../runtime/errors.js';
+
+export async function initializeTextGraph(options = {}) {
+  if (!options || typeof options !== 'object') throw new DrawMotiveError('INVALID_ARGUMENT', 'Initialization options must be an object');
+  return initialize({ ...options, loadRuntime: options.loadRuntime ?? (context => loadNodeRuntime(context, manifest)) });
+}
+
+export const platform = 'node';

package/src/platform/worker.d.ts

@@ -0,0 +1,3 @@
+export * from './browser.js';
+
+export declare const platform: 'worker';

package/src/platform/worker.js

@@ -0,0 +1,4 @@
+export * from './browser.js';
+export { createTextGraphRuntimeLoader } from '../runtime/browser.js';
+
+export const platform = 'worker';

package/src/runtime/assets.js

@@ -0,0 +1,27 @@
+import { DrawMotiveError } from './errors.js';
+
+/** Resolves manifest assets relative to this package without ambient base URLs. */
+export function resolveRuntimeAssets({ manifest, moduleUrl = import.meta.url, resolveAsset }) {
+  if (!Array.isArray(manifest?.assets)) {
+    throw new DrawMotiveError('INVALID_MANIFEST', 'The runtime manifest must contain an assets array');
+  }
+  const generatedBase = new URL('../../generated/', new URL(moduleUrl));
+  return manifest.assets.map((asset) => {
+    const defaultUrl = new URL(asset.path, generatedBase);
+    const override = resolveAsset ? resolveAsset(asset, defaultUrl) : defaultUrl;
+    return Object.freeze({ asset, url: absoluteUrl(override, asset.path) });
+  });
+}
+
+function absoluteUrl(value, assetPath) {
+  try {
+    const url = value instanceof URL ? new URL(value.href) : new URL(value);
+    if (!url.protocol) throw new TypeError('Missing protocol');
+    return url;
+  } catch (cause) {
+    throw new DrawMotiveError('INVALID_ASSET_URL', `Asset ${assetPath} must resolve to an absolute URL`, {
+      cause,
+      details: { asset: assetPath, value: String(value) },
+    });
+  }
+}

package/src/runtime/browser.js

@@ -0,0 +1,41 @@
+import { createRuntimeAssetPlan } from './shared.js';
+import { DrawMotiveError } from './errors.js';
+import { startTextGraphRuntime } from './dotnet.js';
+
+/** Browser and module Workers share URL-based startup without DOM dependencies. */
+export function loadBrowserRuntime(options, manifest) {
+  const fetchResource = options.fetch ?? options.adapters?.network?.fetch ?? globalThis.fetch;
+  return startTextGraphRuntime(options, manifest, async (item, context) => {
+    try {
+      const response = await fetchResource(item.url, { signal: context.signal });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return response;
+    } catch (cause) {
+      if (cause?.name === 'AbortError') throw cause;
+      throw new DrawMotiveError('RESOURCE_NOT_FOUND', `Could not load ${item.asset.path}`, { cause, details: { asset: item.asset.path } });
+    }
+  });
+}
+
+/** Creates the browser-compatible loader for TextGraph's package-owned runtime assets. */
+export function createTextGraphRuntimeLoader(options) {
+  const fetchResource = options.fetch ?? globalThis.fetch;
+  if (typeof fetchResource !== 'function') throw new TypeError('A fetch implementation is required');
+  const plan = createRuntimeAssetPlan(options);
+  return {
+    plan,
+    async loadAssets() {
+      const loaded = new Map();
+      for (const item of plan) {
+        const response = await fetchResource(item.url);
+        if (!response.ok) {
+          throw new DrawMotiveError('RESOURCE_NOT_FOUND', `Failed to load ${item.asset.path}: HTTP ${response.status}`, {
+            details: { asset: item.asset.path, status: response.status, url: item.url.href },
+          });
+        }
+        loaded.set(item.asset.path, { ...item.asset, url: item.url, bytes: new Uint8Array(await response.arrayBuffer()) });
+      }
+      return loaded;
+    },
+  };
+}

package/src/runtime/dotnet.js

@@ -0,0 +1,100 @@
+import { createRuntimeAssetPlan } from './shared.js';
+import { DrawMotiveError } from './errors.js';
+import { validateManifest, validateBootConfig, validationCapability, renderingCapability, isRuntimeAsset } from './manifest.js';
+import { throwIfAborted } from './lifecycle.js';
+import { readVerifiedAsset } from './integrity.js';
+import { createRenderingExecutor } from './render-resources.js';
+import { decodeConfiguration } from './rendering.js';
+
+/** Starts one isolated .NET module graph; platform loaders own all data I/O. */
+export async function startTextGraphRuntime(options, manifest, readAsset) {
+  validateManifest(manifest);
+  throwIfAborted(options.signal);
+  if (!globalThis.crypto?.subtle || typeof globalThis.crypto.randomUUID !== 'function') {
+    throw new DrawMotiveError('UNSUPPORTED_ENVIRONMENT', 'TextGraph requires Web Crypto in HTTPS or localhost');
+  }
+  const plan = createRuntimeAssetPlan({ manifest: { assets: manifest.assets.filter(isRuntimeAsset) }, moduleUrl: import.meta.url, resolveAsset: options.resolveAsset });
+  const byName = new Map(plan.map(item => [item.asset.path.slice(5), item]));
+  const instanceKey = crypto.randomUUID();
+  const moduleUrl = item => {
+    const url = new URL(item.url);
+    // .NET ESM modules retain mutable initialization state, so each instance needs its own graph.
+    url.searchParams.set('textgraph-instance', instanceKey);
+    return url.href;
+  };
+  let bridge;
+  try {
+    // .NET treats download failures as fatal and may terminate a Node host. Own
+    // loading/cancellation here, before entering its non-cancellable startup.
+    const data = new Map();
+    for (const item of plan) {
+      throwIfAborted(options.signal);
+      if (/[.](mjs|js)$/.test(item.asset.path)) continue;
+      data.set(item.asset.path, await readVerifiedAsset(item, options, readAsset));
+    }
+    throwIfAborted(options.signal);
+    // Detect unsupported WASM features before the runtime takes ownership of failure handling.
+    await WebAssembly.compile(data.get(manifest.runtimeWasm));
+    // Import dependency modules before create(): its asynchronous imports otherwise
+    // turn missing modules into fatal unhandled runtime startup failures.
+    for (const item of plan) {
+      if (!/[.]js$/.test(item.asset.path) || item.asset.path === manifest.runtimeModule) continue;
+      let imported;
+      try { imported = await import(/* webpackIgnore: true */ /* @vite-ignore */ moduleUrl(item)); }
+      catch (cause) { throw new DrawMotiveError('RESOURCE_NOT_FOUND', `Could not import ${item.asset.path}`, { cause, details: { asset: item.asset.path } }); }
+      if (item.asset.path === 'wasm/dotnet.boot.js') validateBootConfig(imported.config, manifest);
+    }
+    throwIfAborted(options.signal);
+    const runtimeEntry = byName.get(manifest.runtimeModule.slice(5));
+    let dotnet;
+    try { ({ dotnet } = await import(/* webpackIgnore: true */ /* @vite-ignore */ moduleUrl(runtimeEntry))); }
+    catch (cause) { throw new DrawMotiveError('RESOURCE_NOT_FOUND', 'Could not import the runtime module', { cause, details: { asset: runtimeEntry.asset.path } }); }
+    const runtime = await dotnet.withResourceLoader((type, name) => {
+      const item = byName.get(name);
+      if (!item) throw new DrawMotiveError('RESOURCE_NOT_FOUND', 'Runtime requested an unlisted asset', { details: { asset: name } });
+      if (/[.](mjs|js)$/.test(name)) return moduleUrl(item);
+      return Promise.resolve(new Response(data.get(item.asset.path), { headers: { 'Content-Type': item.asset.mediaType } }));
+    }).create();
+    throwIfAborted(options.signal);
+    const exports = await runtime.getAssemblyExports(manifest.bridge.assembly);
+    bridge = manifest.bridge.type.split('.').reduce((value, key) => value?.[key], exports);
+    if (typeof bridge?.[manifest.bridge.info] !== 'function' || typeof bridge?.[manifest.bridge.validate] !== 'function') {
+      throw new DrawMotiveError('ABI_MISMATCH', 'Required bridge exports are missing');
+    }
+    let info;
+    try { info = JSON.parse(bridge[manifest.bridge.info]()); }
+    catch (cause) { throw new DrawMotiveError('ABI_MISMATCH', 'Invalid bridge handshake', { cause }); }
+    if (!info || info.abiVersion !== manifest.abiVersion || info.packageKind !== 'textgraph' || info.protocolVersion !== manifest.protocolVersion) {
+      throw new DrawMotiveError('ABI_MISMATCH', 'Bridge and manifest disagree');
+    }
+    if (!Array.isArray(info.capabilities) || !info.capabilities.includes(validationCapability)) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Bridge does not implement validation');
+    const renders = manifest.capabilities.includes(renderingCapability);
+    if (renders && !info.capabilities.includes(renderingCapability)) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Bridge does not implement rendering');
+    if (renders && typeof bridge[manifest.bridge.execute] !== 'function') throw new DrawMotiveError('ABI_MISMATCH', 'Rendering bridge export is missing');
+    return createBridgeRuntime({ manifest, options, readAsset, bridge, info });
+  } catch (cause) {
+    bridge = undefined;
+    if (cause instanceof DrawMotiveError || cause?.name === 'AbortError') throw cause;
+    throw new DrawMotiveError('INITIALIZATION_FAILED', 'Could not initialize TextGraph WASM', { cause });
+  }
+}
+
+/** Owns managed bridge resources; the instance queue drains calls before invoking disposal. */
+export function createBridgeRuntime({ manifest, options, readAsset, bridge, info }) {
+  const renders = manifest.capabilities.includes(renderingCapability);
+  return {
+    abiVersion: info.abiVersion, capabilities: info.capabilities,
+    validate: source => bridge[manifest.bridge.validate](source),
+    ...(renders ? { execute: createRenderingExecutor({ manifest, options, readAsset, execute: request => bridge[manifest.bridge.execute](request) }) } : {}),
+    async dispose() {
+      if (!bridge) return;
+      try {
+        // Release native font caches and their timers without .NET exit(), which terminates Node.
+        if (renders) decodeConfiguration(await bridge[manifest.bridge.execute](JSON.stringify({ protocolVersion: 1, operation: 'dispose' })), 'disposal');
+      } catch (cause) {
+        if (cause instanceof DrawMotiveError) throw cause;
+        throw new DrawMotiveError('RUNTIME_FAILED', 'Native resource disposal failed', { cause });
+      } finally { bridge = undefined; }
+    },
+  };
+}

package/src/runtime/errors.js

@@ -0,0 +1,14 @@
+/** Represents a stable public DrawMotive runtime failure. */
+export class DrawMotiveError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = 'DrawMotiveError';
+    this.code = code;
+    this.details = Object.freeze({ ...(options.details ?? {}) });
+  }
+}
+
+/** Creates the standard cancellation error used by all package entrypoints. */
+export function createAbortError() {
+  return new DOMException('The operation was aborted', 'AbortError');
+}

package/src/runtime/integrity.js

@@ -0,0 +1,12 @@
+import { DrawMotiveError } from './errors.js';
+
+/** Check package-owned data before passing it to native code, including lazy render resources. */
+export async function readVerifiedAsset(item, options, readAsset) {
+  const response = await readAsset(item, options);
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  const hash = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)), byte => byte.toString(16).padStart(2, '0')).join('');
+  if (bytes.byteLength !== item.asset.bytes || hash !== item.asset.sha256) {
+    throw new DrawMotiveError('ASSET_INTEGRITY_MISMATCH', `Asset integrity failed: ${item.asset.path}`, { details: { asset: item.asset.path } });
+  }
+  return bytes;
+}

package/src/runtime/language-packs.js

@@ -0,0 +1,32 @@
+import { DrawMotiveError } from './errors.js';
+
+const defaultFamilies = ['NotoSans-Regular', 'FuzzyBubbles-Regular'];
+
+/** Copy caller-owned font descriptors before asynchronous startup without performing font I/O. */
+export function normalizeLanguagePacks(packs = []) {
+  const invalid = message => { throw new DrawMotiveError('INVALID_ARGUMENT', message); };
+  if (!Array.isArray(packs)) invalid('languagePacks must be an array');
+  const families = new Set(defaultFamilies);
+  const normalized = packs.map(pack => {
+    if (!pack || !Array.isArray(pack.fonts) || pack.fonts.length === 0) invalid('Each language pack must contain a non-empty fonts array');
+    const fonts = pack.fonts.map(font => {
+      if (!font || typeof font.family !== 'string' || !font.family.trim() || font.family !== font.family.trim()) invalid('Font family must be a non-empty trimmed string');
+      if (families.has(font.family)) invalid(`Duplicate font family: ${font.family}`);
+      families.add(font.family);
+      let source;
+      if (font.source instanceof URL) {
+        if (!['https:', 'http:', 'file:', 'data:', 'blob:'].includes(font.source.protocol)) invalid(`Unsupported font URL protocol: ${font.source.protocol}`);
+        source = new URL(font.source.href);
+      } else if (font.source instanceof Uint8Array && font.source.byteLength > 0) source = new Uint8Array(font.source);
+      else invalid(`Font ${font.family} source must be a URL or non-empty Uint8Array`);
+      return Object.freeze({ family: font.family, source });
+    });
+    const fallbackFamilies = pack.fallbackFamilies ?? [];
+    if (!Array.isArray(fallbackFamilies) || !fallbackFamilies.every(family => typeof family === 'string' && family.trim() && family === family.trim())) invalid('fallbackFamilies must be an array of font family names');
+    return Object.freeze({ fonts: Object.freeze(fonts), fallbackFamilies: Object.freeze([...fallbackFamilies]) });
+  });
+  for (const pack of normalized) for (const family of pack.fallbackFamilies) {
+    if (!families.has(family)) invalid(`Fallback font family is not configured: ${family}`);
+  }
+  return Object.freeze(normalized);
+}

package/src/runtime/lifecycle.js

@@ -0,0 +1,84 @@
+import { createAbortError, DrawMotiveError } from './errors.js';
+
+/** Throws before host work begins when initialization was already cancelled. */
+export function throwIfAborted(signal) {
+  if (signal?.aborted) throw createAbortError();
+}
+
+/** Waits for an initialization resource while guaranteeing cleanup after cancellation. */
+export async function waitForInitialResource(factory, signal) {
+  throwIfAborted(signal);
+  const resourcePromise = Promise.resolve().then(factory);
+  if (!signal) return resourcePromise;
+
+  let rejectAbort;
+  const abortPromise = new Promise((_, reject) => { rejectAbort = reject; });
+  const abort = () => rejectAbort(createAbortError());
+  signal.addEventListener('abort', abort, { once: true });
+  try {
+    return await Promise.race([resourcePromise, abortPromise]);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      void resourcePromise.then((resource) => resource?.dispose?.()).catch(() => undefined);
+    }
+    throw error;
+  } finally {
+    signal.removeEventListener('abort', abort);
+  }
+}
+
+/** Verifies the runtime boundary before exposing an instance to the host. */
+export async function validateAbi(resource, expectedAbi) {
+  if (resource?.abiVersion === expectedAbi) return resource;
+  await resource?.dispose?.();
+  throw new DrawMotiveError('ABI_MISMATCH', `Expected ABI ${expectedAbi} but received ${resource?.abiVersion ?? 'none'}`, {
+    details: { expected: expectedAbi, actual: resource?.abiVersion ?? null },
+  });
+}
+
+/** Wraps a runtime in an isolated read/write scheduler with deterministic disposal. */
+export function createManagedInstance(resources) {
+  let state = 'ready';
+  let mutationTail = Promise.resolve();
+  let disposePromise;
+  const active = new Set();
+
+  const ensureReady = () => {
+    if (state !== 'ready') {
+      throw new DrawMotiveError('INSTANCE_DISPOSED', 'The runtime instance is disposing or disposed', { details: { state } });
+    }
+  };
+  const track = (promise) => {
+    const tracked = Promise.resolve(promise);
+    active.add(tracked);
+    void tracked.finally(() => active.delete(tracked)).catch(() => undefined);
+    return tracked;
+  };
+
+  return {
+    get state() { return state; },
+    async readonly(operation) {
+      ensureReady();
+      return track(Promise.resolve().then(operation));
+    },
+    async mutate(operation) {
+      ensureReady();
+      const result = mutationTail.then(operation);
+      mutationTail = result.catch(() => undefined);
+      return track(result);
+    },
+    dispose() {
+      if (disposePromise) return disposePromise;
+      state = 'disposing';
+      disposePromise = (async () => {
+        await Promise.allSettled([...active]);
+        try {
+          const results = await Promise.allSettled(resources.map(resource => Promise.resolve().then(() => resource?.dispose?.())));
+          const failure = results.find(result => result.status === 'rejected');
+          if (failure) throw failure.reason;
+        } finally { state = 'disposed'; }
+      })();
+      return disposePromise;
+    },
+  };
+}

package/src/runtime/manifest.js

@@ -0,0 +1,60 @@
+import { DrawMotiveError } from './errors.js';
+
+export const validationCapability = 'textgraph-validate-v1';
+export const renderingCapability = 'textgraph-render-v1';
+
+/** Only native runtime formats belong to startup; fonts, themes and licenses are separate assets. */
+export function isRuntimeAsset(asset) {
+  return /[.](wasm|js|mjs|json|dat)$/.test(asset.path);
+}
+
+/** Boot metadata cannot expand the preflighted asset authority after native startup begins. */
+export function validateBootConfig(config, manifest) {
+  if (config?.mainAssemblyName !== manifest.bridge.assembly) throw new DrawMotiveError('ABI_MISMATCH', 'Unexpected boot entry assembly');
+  const paths = new Set(manifest.assets.filter(isRuntimeAsset).map(asset => asset.path.slice(5)));
+  if (!config.resources || typeof config.resources !== 'object') throw new DrawMotiveError('INVALID_MANIFEST', 'Missing boot resources');
+  const visit = value => {
+    if (!value || typeof value !== 'object') return;
+    if (Object.hasOwn(value, 'name') && !paths.has(value.name)) throw new DrawMotiveError('INVALID_MANIFEST', 'Boot resource is absent from the asset manifest', { details: { asset: value.name } });
+    Object.values(value).forEach(visit);
+  };
+  visit(config.resources);
+}
+
+/** Reject incompatible bundles and ambiguous paths before any executable asset is imported. */
+export function validateManifest(manifest) {
+  const invalid = () => { throw new DrawMotiveError('INVALID_MANIFEST', 'Invalid TextGraph runtime manifest'); };
+  if (!manifest || manifest.schemaVersion !== 1 || manifest.packageName !== '@drawmotive/textgraph'
+      || typeof manifest.packageVersion !== 'string' || !manifest.packageVersion || manifest.protocolVersion !== 1
+      || manifest.targetFramework !== 'net10.0' || !/^[a-f0-9]{40}$/.test(manifest.privateSource?.commit ?? '')
+      || manifest.privateSource?.project !== 'DrawMotive.TextGraph.Bridge' || !Array.isArray(manifest.assets)) invalid();
+  if (manifest.abiVersion !== '1.0.0') throw new DrawMotiveError('ABI_MISMATCH', 'Unsupported TextGraph ABI');
+  if (!Array.isArray(manifest.capabilities) || !manifest.capabilities.every(item => typeof item === 'string')) invalid();
+  if (!manifest.capabilities.includes(validationCapability)) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Validation capability is missing');
+  const paths = new Set();
+  for (const asset of manifest.assets) {
+    if (!asset || !/^wasm[/][A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(asset.path) || paths.has(asset.path)
+        || /[.](pdb|map|br|gz|cs)$/.test(asset.path) || !/^[a-f0-9]{64}$/.test(asset.sha256)
+        || !Number.isSafeInteger(asset.bytes) || asset.bytes < 0 || typeof asset.mediaType !== 'string') invalid();
+    paths.add(asset.path);
+  }
+  for (const key of ['runtimeModule', 'entryAssembly', 'runtimeWasm', 'runtimeConfig']) if (!paths.has(manifest[key])) invalid();
+  if (!paths.has('wasm/dotnet.boot.js') || manifest.bridge?.assembly !== 'DrawMotive.TextGraph.Bridge.dll'
+      || manifest.bridge?.type !== 'DrawMotive.TextGraph.Bridge.Program' || manifest.bridge?.info !== 'GetRuntimeInfo'
+      || manifest.bridge?.validate !== 'Validate') invalid();
+  if (manifest.bridge.execute !== undefined && manifest.bridge.execute !== 'Execute') invalid();
+  if (manifest.capabilities.includes(renderingCapability) && (!manifest.rendering || manifest.bridge.execute !== 'Execute')) invalid();
+  if (manifest.rendering !== undefined) {
+    const rendering = manifest.rendering;
+    if (!rendering || !paths.has(rendering.theme) || !rendering.theme.endsWith('.css')
+        || !Array.isArray(rendering.fonts) || rendering.fonts.length === 0) invalid();
+    const families = new Set();
+    const fontPaths = new Set();
+    for (const font of rendering.fonts) {
+      if (!font || typeof font.family !== 'string' || !font.family.trim() || font.family !== font.family.trim()
+          || families.has(font.family) || fontPaths.has(font.asset) || !paths.has(font.asset) || !/[.](ttf|otf)$/.test(font.asset)) invalid();
+      families.add(font.family); fontPaths.add(font.asset);
+    }
+  }
+  return manifest;
+}

package/src/runtime/node.js

@@ -0,0 +1,21 @@
+import { readFile } from 'node:fs/promises';
+import { startTextGraphRuntime } from './dotnet.js';
+import { DrawMotiveError } from './errors.js';
+
+/** Node file loading is isolated from the browser module graph. */
+export function loadNodeRuntime(options, manifest) {
+  return startTextGraphRuntime(options, manifest, async (item, context) => {
+    try {
+      if (item.url.protocol === 'file:') {
+        return new Response(await readFile(item.url, { signal: context.signal }), { headers: { 'Content-Type': item.asset.mediaType } });
+      }
+      const fetchResource = context.fetch ?? context.adapters?.network?.fetch ?? globalThis.fetch;
+      const response = await fetchResource(item.url, { signal: context.signal });
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      return response;
+    } catch (cause) {
+      if (cause?.name === 'AbortError') throw cause;
+      throw new DrawMotiveError('RESOURCE_NOT_FOUND', `Could not load ${item.asset.path}`, { cause, details: { asset: item.asset.path } });
+    }
+  });
+}

package/src/runtime/render-resources.js

@@ -0,0 +1,51 @@
+import { createRuntimeAssetPlan } from './shared.js';
+import { readVerifiedAsset } from './integrity.js';
+import { decodeConfiguration } from './rendering.js';
+import { throwIfAborted } from './lifecycle.js';
+
+function base64(bytes) {
+  const chunks = [];
+  for (let offset = 0; offset < bytes.length; offset += 32768) chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 32768)));
+  return btoa(chunks.join(''));
+}
+
+/** Preparation lives inside the instance operation queue; validation never triggers font I/O. */
+export function createRenderingExecutor({ manifest, options, readAsset, execute }) {
+  let configured = false;
+  return async (request, context = {}) => {
+    const loadingOptions = { ...options, signal: context.signal };
+    throwIfAborted(context.signal);
+    if (!configured) {
+      const selected = new Set([manifest.rendering.theme, ...manifest.rendering.fonts.map(font => font.asset)]);
+      const plan = createRuntimeAssetPlan({ manifest: { assets: manifest.assets.filter(asset => selected.has(asset.path)) }, moduleUrl: import.meta.url, resolveAsset: options.resolveAsset });
+      const byPath = new Map(plan.map(item => [item.asset.path, item]));
+      const load = async path => {
+        throwIfAborted(context.signal);
+        const bytes = await readVerifiedAsset(byPath.get(path), loadingOptions, readAsset);
+        throwIfAborted(context.signal);
+        return bytes;
+      };
+      const theme = new TextDecoder('utf-8', { fatal: true }).decode(await load(manifest.rendering.theme));
+      const fonts = [];
+      for (const font of manifest.rendering.fonts) fonts.push({ family: font.family, data: base64(await load(font.asset)) });
+      const fallbackFamilies = [];
+      for (const pack of options.languagePacks ?? []) {
+        for (const font of pack.fonts) {
+          throwIfAborted(context.signal);
+          const bytes = font.source instanceof Uint8Array ? font.source : new Uint8Array(await (await readAsset({
+            asset: { path: `font:${font.family}`, mediaType: 'font/ttf' }, url: font.source,
+          }, loadingOptions)).arrayBuffer());
+          throwIfAborted(context.signal);
+          fonts.push({ family: font.family, data: base64(bytes) });
+        }
+        for (const family of pack.fallbackFamilies) if (!fallbackFamilies.includes(family)) fallbackFamilies.push(family);
+      }
+      throwIfAborted(context.signal);
+      decodeConfiguration(await execute(JSON.stringify({ protocolVersion: 1, operation: 'configure', theme, fonts, fallbackFamilies })));
+      // Native configuration is committed even when the caller cancels during that synchronous operation.
+      configured = true;
+      throwIfAborted(context.signal);
+    }
+    return execute(request);
+  };
+}