@drawmotive/textgraph 0.2.0 → 0.2.2-alpha.1

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@drawmotive/textgraph",
-  "version": "0.2.0",
-  "description": "TextGraph DSL and headless DrawMotive file toolkit",
+  "version": "0.2.2-alpha.1",
+  "description": "Render TextGraph flowcharts and directed graphs as PNG images in Node.js, browsers, React, and Web Workers.",
+  "keywords": [
+    "textgraph",
+    "diagram",
+    "flowchart",
+    "directed-graph",
+    "text-to-diagram",
+    "automatic-layout",
+    "png",
+    "react",
+    "webassembly",
+    "wasm"
+  ],
   "type": "module",
   "types": "./src/index.d.ts",
   "exports": {
@@ -82,7 +94,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "latest"
+    "tag": "alpha"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0"

package/schemas/render.schema.json

@@ -76,6 +76,14 @@
       "type": "integer",
       "minimum": 1,
       "maximum": 2147483647
+    },
+    "displayWidth": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "displayHeight": {
+      "type": "number",
+      "exclusiveMinimum": 0
     }
   },
   "required": [
@@ -145,6 +153,22 @@
               "properties": {
                 "height": {}
               }
+            },
+            {
+              "required": [
+                "displayWidth"
+              ],
+              "properties": {
+                "displayWidth": {}
+              }
+            },
+            {
+              "required": [
+                "displayHeight"
+              ],
+              "properties": {
+                "displayHeight": {}
+              }
             }
           ]
         },
@@ -163,5 +187,13 @@
         }
       }
     }
-  ]
+  ],
+  "dependentRequired": {
+    "displayWidth": [
+      "displayHeight"
+    ],
+    "displayHeight": [
+      "displayWidth"
+    ]
+  }
 }

package/src/index.d.ts

@@ -93,14 +93,28 @@ export interface TextGraphInitializeOptions {
   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. */
+  /** Legacy descriptors load on first render; descriptors with coverage load on demand. */
   languagePacks?: readonly TextGraphLanguagePack[];
+  /** Optional deployed catalog; without a package, online rendering uses the staging catalog. */
+  fontAssets?: TextGraphFontAssets;
+}
+
+export interface TextGraphFontAssets {
+  /** Catalog URL; files resolve relative to this URL. A configured catalog is authoritative. */
+  readonly catalog?: URL;
+  /** Disable external fallback for offline hosts, or select another remote catalog. */
+  readonly fallback?: false | URL;
 }
 
 export interface TextGraphFont {
   readonly family: string;
   /** Use a URL (including file: in Node) or bytes; bytes are copied during initialization. */
   readonly source: URL | Uint8Array;
+  /** Sorted, disjoint inclusive Unicode ranges. Supply all metadata fields together for lazy loading. */
+  readonly coverage?: readonly (readonly [number, number])[];
+  readonly languages?: readonly string[];
+  readonly bytes?: number;
+  readonly sha256?: string;
 }
 
 export interface TextGraphLanguagePack {
@@ -112,9 +126,11 @@ export interface TextGraphLanguagePack {
 export type TextGraphPngEncoding = 'bytes' | 'base64';
 
 export interface TextGraphRenderPngOptions<Encoding extends TextGraphPngEncoding = TextGraphPngEncoding> {
+  /** Optional language hint for ambiguous Han text, e.g. ja or zh-CN. */
+  language?: string;
   /** Defaults to bytes. Base64 contains no data-URL prefix. */
   encoding?: Encoding;
-  /** Positive render scale. Defaults to 2. */
+  /** Positive raster density relative to logical diagram size. Defaults to 1. */
   scale?: number;
   /** Non-negative padding in diagram units. Defaults to 10. */
   padding?: number;
@@ -125,7 +141,9 @@ export interface TextGraphRenderPngOptions<Encoding extends TextGraphPngEncoding
 }
 
 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: true; readonly png: Png; readonly width: number; readonly height: number;
+      /** Logical display dimensions before density scaling; omitted by older runtimes. */
+      readonly displayWidth?: number; readonly displayHeight?: number; readonly diagnostics: readonly TextGraphRenderDiagnostic[] }
   | { readonly success: false; readonly diagnostics: readonly TextGraphRenderDiagnostic[] };
 
 export interface TextGraphRuntimeInfo extends TextGraphRuntimeManifest {

package/src/index.js

@@ -2,7 +2,7 @@ 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 { normalizeFontAssets, normalizeLanguagePacks } from './runtime/language-packs.js';
 import { decodeRender, normalizeRenderOptions } from './runtime/rendering.js';
 import manifest from '../generated/wasm-manifest.js';
 
@@ -26,7 +26,7 @@ export async function initializeTextGraph(options = {}) {
   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 normalized = Object.freeze({ ...options, adapters: validateTextGraphAdapters(options.adapters), languagePacks: normalizeLanguagePacks(options.languagePacks), fontAssets: normalizeFontAssets(options.fontAssets) });
   const runtime = await waitForInitialResource(() => options.loadRuntime(normalized), options.signal);
   await validateAbi(runtime, abiManifest.abiVersion);
   const instance = createManagedInstance([runtime]);

package/src/platform/node.d.ts

@@ -1,3 +1,5 @@
 export * from '../index.js';
 
+/** The workspace development command may select local native assets through
+ * DRAWMOTIVE_TEXTGRAPH_RUNTIME; ordinary Node loading uses packaged assets. */
 export declare const platform: 'node';

package/src/platform/node.js

@@ -3,10 +3,29 @@ 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';
+import { normalizeFontAssets, normalizeLanguagePacks } from '../runtime/language-packs.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)) });
+  options = { ...options };
+  // The workspace development command opts in explicitly; imports and browser
+  // loaders never consult a local build directory or replace packaged assets.
+  const directory = process.env.DRAWMOTIVE_TEXTGRAPH_RUNTIME;
+  const languagePacks = normalizeLanguagePacks(options.languagePacks);
+  let fontAssets = normalizeFontAssets(options.fontAssets);
+  if (!options.loadRuntime && fontAssets?.catalog === undefined && options.languagePacks === undefined) {
+    let entry;
+    try { entry = import.meta.resolve('@drawmotive/textgraph-fonts'); }
+    catch (error) { if (error.code !== 'ERR_MODULE_NOT_FOUND') throw error; }
+    // Resolve the optional package from the installed SDK tree. A broken installed
+    // package must surface its error; only absence enables the remote source.
+    if (entry) {
+      const pack = await import(entry);
+      if (!(pack.fontCatalogUrl instanceof URL)) throw new DrawMotiveError('INVALID_MANIFEST', 'Installed font package has no catalog URL');
+      fontAssets = { ...fontAssets, catalog: pack.fontCatalogUrl };
+    }
+  }
+  return initialize({ ...options, languagePacks, fontAssets, loadRuntime: options.loadRuntime ?? (context => loadNodeRuntime(context, manifest, directory)) });
 }
 
 export const platform = 'node';

package/src/react/index.d.ts

@@ -11,6 +11,7 @@ export interface TextGraphProviderProps {
 export interface TextGraphProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'src' | 'srcSet' | 'children' | 'loading'> {
   source: string;
   alt?: string;
+  /** Defaults to scale 1; the image displays at logical size. */
   renderOptions?: Omit<TextGraphRenderPngOptions, 'encoding' | 'signal'>;
   loading?: ReactNode;
 }

package/src/react/index.js

@@ -15,10 +15,10 @@ export function TextGraphProvider({ options = defaultOptions, children }) {
 
 /** Renders DSL as an image; only the latest committed input may publish a result. */
 export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = defaultOptions,
-  loading = 'Rendering diagram…', ...imageProps }) {
+  loading = 'Rendering diagram…', style, ...imageProps }) {
   const shared = useContext(RuntimeContext);
   const resource = useMemo(() => shared ?? createRuntimeResource(defaultOptions), [shared]);
-  const { scale, padding, maxWidth } = renderOptions;
+  const { scale = 1, padding, maxWidth } = renderOptions;
   const request = useMemo(() => ({ source, scale, padding, maxWidth, resource }),
     [source, scale, padding, maxWidth, resource]);
   const [state, setState] = useState(null);
@@ -51,6 +51,9 @@ export function TextGraph({ source, alt = 'TextGraph diagram', renderOptions = d
     return createElement('span', { role: 'alert' }, message || 'Could not render diagram');
   }
   const result = state.result;
-  return createElement('img', { width: result.width, height: result.height, ...imageProps,
+  // Density improves sharpness without enlarging the diagram. Native dimensions
+  // also preserve logical size when maxWidth lowers the actual render density.
+  return createElement('img', { width: result.displayWidth ?? result.width / scale, height: result.displayHeight ?? result.height / scale, ...imageProps,
+    style: { maxWidth: '100%', ...(imageProps.height == null ? { height: 'auto' } : {}), ...style },
     src: `data:image/png;base64,${result.png}`, alt });
 }

package/src/runtime/browser.js

@@ -25,17 +25,16 @@ export function createTextGraphRuntimeLoader(options) {
   return {
     plan,
     async loadAssets() {
-      const loaded = new Map();
-      for (const item of plan) {
+      // Fetch independent assets together; retain manifest order in the result.
+      return new Map(await Promise.all(plan.map(async item => {
         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;
+        return [item.asset.path, { ...item.asset, url: item.url, bytes: new Uint8Array(await response.arrayBuffer()) }];
+      })));
     },
   };
 }

package/src/runtime/dotnet.js

@@ -5,6 +5,7 @@ import { throwIfAborted } from './lifecycle.js';
 import { readVerifiedAsset } from './integrity.js';
 import { createRenderingExecutor } from './render-resources.js';
 import { decodeConfiguration } from './rendering.js';
+import { fontCapability } from './font-resources.js';
 
 /** Starts one isolated .NET module graph; platform loaders own all data I/O. */
 export async function startTextGraphRuntime(options, manifest, readAsset) {
@@ -26,12 +27,12 @@ export async function startTextGraphRuntime(options, manifest, readAsset) {
   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) {
+    // Data assets are independent: start them together, but verify every response
+    // before importing modules or giving .NET ownership of the bytes.
+    const data = new Map(await Promise.all(plan.filter(item => !/[.](mjs|js)$/.test(item.asset.path)).map(async item => {
       throwIfAborted(options.signal);
-      if (/[.](mjs|js)$/.test(item.asset.path)) continue;
-      data.set(item.asset.path, await readVerifiedAsset(item, options, readAsset));
-    }
+      return [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));
@@ -70,6 +71,7 @@ export async function startTextGraphRuntime(options, manifest, readAsset) {
     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 (manifest.capabilities.includes(fontCapability) && !info.capabilities.includes(fontCapability)) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'Bridge does not implement lazy fonts');
     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) {
@@ -83,7 +85,9 @@ export async function startTextGraphRuntime(options, manifest, readAsset) {
 export function createBridgeRuntime({ manifest, options, readAsset, bridge, info }) {
   const renders = manifest.capabilities.includes(renderingCapability);
   return {
-    abiVersion: info.abiVersion, capabilities: info.capabilities,
+    // A bridge may support operations intentionally omitted by the selected
+    // manifest; advertise only the intersection that this loader exposes.
+    abiVersion: info.abiVersion, capabilities: info.capabilities.filter(capability => manifest.capabilities.includes(capability)),
     validate: source => bridge[manifest.bridge.validate](source),
     ...(renders ? { execute: createRenderingExecutor({ manifest, options, readAsset, execute: request => bridge[manifest.bridge.execute](request) }) } : {}),
     async dispose() {

package/src/runtime/font-resources.js

@@ -0,0 +1,148 @@
+import { DrawMotiveError } from './errors.js';
+import { normalizeFontMetadata } from './language-packs.js';
+import { decodeDiagnostics } from './validation.js';
+import { decodeConfiguration } from './rendering.js';
+import { readVerifiedAsset } from './integrity.js';
+import { throwIfAborted } from './lifecycle.js';
+
+export const fontCapability = 'textgraph-fonts-v1';
+const stagingCatalog = 'https://staging.drawmotive.com/static/font-catalog.json';
+
+export function fontBase64(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(''));
+}
+
+/** Catalog paths stay within their deployment directory, independent of the hosting origin. */
+function decodeCatalog(value, url) {
+  try {
+    if (value?.schemaVersion !== 1 || !Array.isArray(value.fonts) || !value.fonts.length) throw new Error('Invalid font catalog envelope');
+    const ids = new Set(), families = new Set(), paths = new Set();
+    return value.fonts.map(font => {
+      if (!font || typeof font.id !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(font.id) || ids.has(font.id)
+          || typeof font.family !== 'string' || !font.family.trim() || font.family !== font.family.trim() || families.has(font.family)
+          || typeof font.path !== 'string' || !/^[A-Za-z0-9_./-]+[.](ttf|otf)$/.test(font.path) || font.path.startsWith('/')
+          || font.path.split('/').some(segment => !segment || segment === '.' || segment === '..') || paths.has(font.path) || font.coverage === undefined) throw new Error('Invalid or duplicate font catalog entry');
+      ids.add(font.id); families.add(font.family); paths.add(font.path);
+      const metadata = normalizeFontMetadata(font);
+      const source = new URL(font.path, url);
+      // A stable content identity lets HTTP caches distinguish font revisions.
+      // File URLs remain plain paths for local/offline hosts.
+      if (['http:', 'https:'].includes(source.protocol)) source.searchParams.set('v', metadata.sha256);
+      return Object.freeze({ family: font.family, source, ...metadata });
+    });
+  } catch (cause) {
+    throw new DrawMotiveError('INVALID_MANIFEST', 'Invalid font catalog', { cause, details: { url: url.href } });
+  }
+}
+
+function decodePreparation(json) {
+  try {
+    const value = JSON.parse(json);
+    if (value?.protocolVersion !== 1 || typeof value.success !== 'boolean') throw new Error('Invalid envelope');
+    const diagnostics = decodeDiagnostics(value.diagnostics, ['parse', 'semantic', 'layout', 'render', 'font']);
+    if (value.success === diagnostics.some(d => d.severity === 'error')) throw new Error('Inconsistent success');
+    if (!Array.isArray(value.fontRuns) || value.fontRuns.some(run => !run || typeof run.text !== 'string' || !run.text
+        || typeof run.missing !== 'boolean' || (run.language !== undefined && run.language !== null && typeof run.language !== 'string'))) throw new Error('Invalid font runs');
+    return { ...value, diagnostics };
+  } catch (cause) {
+    throw new DrawMotiveError('INVALID_RESPONSE', 'Invalid native font preparation response', { cause });
+  }
+}
+
+function contains(ranges, point) {
+  let low = 0, high = ranges.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >>> 1, range = ranges[middle];
+    if (point < range[0]) high = middle - 1;
+    else if (point > range[1]) low = middle + 1;
+    else return true;
+  }
+  return false;
+}
+
+function matches(font, run) {
+  // Coverage overlap does not grant a language-specific pack authority for another
+  // script: loading history must not turn a JP font into implicit Korean fallback.
+  if (!run.language || !font.languages.some(language => language.split('-')[0] === run.language.split('-')[0])) return false;
+  // Variation selectors and joiners describe shaping; they need no standalone cmap glyph.
+  const points = [...run.text].filter(character => !/[\s\p{Default_Ignorable_Code_Point}]/u.test(character)).map(character => character.codePointAt(0));
+  return points.length > 0 && points.every(point => contains(font.coverage, point));
+}
+
+/** Owns optional font I/O inside the instance queue; native owns text, shaping and final coverage. */
+export function createFontPreparation({ options, readAsset, execute }) {
+  const packs = options.languagePacks ?? [];
+  const fallbackOrder = [...new Set(packs.flatMap(pack => pack.fallbackFamilies))];
+  const descriptors = packs.flatMap(pack => pack.fonts);
+  const explicit = fallbackOrder.map(family => descriptors.find(font => font.family === family)).filter(font => font?.coverage);
+  const installed = new Set(packs.flatMap(pack => pack.fonts).filter(font => !font.coverage).map(font => font.family));
+  const settings = options.fontAssets ?? {};
+  // A configured package is authoritative, including its failures. Never probe another source silently.
+  const catalogUrl = settings.catalog ?? (packs.length ? undefined : settings.fallback === false ? undefined : settings.fallback ?? new URL(stagingCatalog));
+  let catalog;
+  async function candidates(context) {
+    if (!catalogUrl) return explicit;
+    if (!catalog) {
+      const response = await readAsset({ asset: { path: 'font-catalog.json', mediaType: 'application/json' }, url: catalogUrl }, context);
+      throwIfAborted(context.signal);
+      let value;
+      try { value = await response.json(); }
+      catch (cause) { throw new DrawMotiveError('INVALID_MANIFEST', 'Could not decode font catalog', { cause }); }
+      const decoded = decodeCatalog(value, catalogUrl);
+      throwIfAborted(context.signal);
+      const overridden = new Set(packs.flatMap(pack => pack.fonts).map(font => font.family));
+      catalog = decoded.filter(font => !overridden.has(font.family));
+    }
+    return [...explicit, ...catalog];
+  }
+  return async (request, context) => {
+    const render = JSON.parse(request);
+    const loading = { ...options, signal: context.signal };
+    const attempted = new Set();
+    let consumed = false;
+    try {
+      while (true) {
+        throwIfAborted(context.signal);
+        const prepared = decodePreparation(await execute(JSON.stringify({ protocolVersion: 1, operation: 'prepare-fonts', source: render.source, ...(render.language === undefined ? {} : { language: render.language }) })));
+        throwIfAborted(context.signal);
+        if (!prepared.success) return JSON.stringify({ protocolVersion: 1, success: false, diagnostics: prepared.diagnostics });
+        const missing = prepared.fontRuns.filter(run => run.missing && run.language);
+        if (!missing.length) break;
+        const selected = new Set();
+        let available = explicit;
+        for (const run of missing) {
+          const usable = font => !installed.has(font.family) && !attempted.has(font.family) && matches(font, run);
+          let candidate = available.find(usable);
+          if (!candidate && catalogUrl) {
+            available = await candidates(loading);
+            candidate = available.find(usable);
+          }
+          if (candidate) selected.add(candidate);
+        }
+        if (!selected.size) break;
+        const fonts = [];
+        for (const font of selected) {
+          attempted.add(font.family);
+          throwIfAborted(context.signal);
+          const bytes = await readVerifiedAsset({ asset: { path: `font:${font.family}`, bytes: font.bytes, sha256: font.sha256, mediaType: 'font/ttf' }, url: font.source }, loading,
+            font.source instanceof Uint8Array ? async () => new Response(font.source) : readAsset);
+          throwIfAborted(context.signal);
+          fonts.push({ family: font.family, data: fontBase64(bytes), languages: font.languages });
+        }
+        const installedAfter = new Set([...installed, ...fonts.map(font => font.family)]);
+        const order = [...fallbackOrder, ...(catalog ?? []).map(font => font.family)].filter(family => installedAfter.has(family));
+        decodeConfiguration(await execute(JSON.stringify({ protocolVersion: 1, operation: 'install-fonts', fonts, fallbackFamilies: order })), 'font installation');
+        // Native has committed before cancellation can be observed: preserve that installation identity.
+        for (const font of fonts) installed.add(font.family);
+      }
+      throwIfAborted(context.signal);
+      const result = await execute(request);
+      consumed = true;
+      return result;
+    } finally {
+      if (!consumed) decodeConfiguration(await execute(JSON.stringify({ protocolVersion: 1, operation: 'cancel-prepare' })), 'font preparation cleanup');
+    }
+  };
+}

package/src/runtime/language-packs.js

@@ -1,6 +1,37 @@
 import { DrawMotiveError } from './errors.js';
 
 const defaultFamilies = ['NotoSans-Regular', 'FuzzyBubbles-Regular'];
+const fail = message => { throw new DrawMotiveError('INVALID_ARGUMENT', message); };
+
+function copyUrl(value, name) {
+  if (!(value instanceof URL) || !['https:', 'http:', 'file:', 'data:', 'blob:'].includes(value.protocol)) fail(`${name} must be a supported URL`);
+  return new URL(value.href);
+}
+
+/** Host configuration selects a source, never probes the network during initialization. */
+export function normalizeFontAssets(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('fontAssets must be an object');
+  if (value.fallback !== undefined && value.fallback !== false && !(value.fallback instanceof URL)) fail('fontAssets.fallback must be false or a catalog URL');
+  return Object.freeze({
+    ...(value.catalog === undefined ? {} : { catalog: copyUrl(value.catalog, 'fontAssets.catalog') }),
+    ...(value.fallback === undefined ? {} : { fallback: value.fallback === false ? false : copyUrl(value.fallback, 'fontAssets.fallback') }),
+  });
+}
+
+/** Official lazy descriptors carry complete immutable coverage and content identity. */
+export function normalizeFontMetadata(font) {
+  if (font.coverage === undefined) return {};
+  if (!Array.isArray(font.coverage) || !font.coverage.length || !Array.isArray(font.languages) || !font.languages.length
+      || !font.languages.every(language => typeof language === 'string' && /^[a-z]{2,8}(?:-[A-Za-z0-9]+)*$/.test(language))
+      || !Number.isSafeInteger(font.bytes) || font.bytes <= 0 || !/^[a-f0-9]{64}$/.test(font.sha256)) fail('Lazy fonts require coverage, languages, bytes and sha256');
+  let end = -1;
+  const coverage = font.coverage.map(range => {
+    if (!Array.isArray(range) || range.length !== 2 || !range.every(Number.isSafeInteger) || range[0] <= end || range[0] < 0 || range[1] < range[0] || range[1] > 0x10ffff) fail('Font coverage must contain sorted non-overlapping Unicode ranges');
+    end = range[1];
+    return Object.freeze([...range]);
+  });
+  return { coverage: Object.freeze(coverage), languages: Object.freeze([...font.languages]), bytes: font.bytes, sha256: font.sha256 };
+}
 
 /** Copy caller-owned font descriptors before asynchronous startup without performing font I/O. */
 export function normalizeLanguagePacks(packs = []) {
@@ -19,7 +50,7 @@ export function normalizeLanguagePacks(packs = []) {
         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 });
+      return Object.freeze({ family: font.family, source, ...normalizeFontMetadata(font) });
     });
     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');

package/src/runtime/node.js

@@ -1,9 +1,30 @@
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 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) {
+export async function loadNodeRuntime(options, manifest, directory) {
+  if (directory !== undefined) {
+    if (!path.isAbsolute(directory)) throw new DrawMotiveError('INVALID_ARGUMENT', 'DRAWMOTIVE_TEXTGRAPH_RUNTIME must be an absolute generated directory');
+    const manifestPath = path.join(directory, 'wasm-manifest.json');
+    let json;
+    try { json = await readFile(manifestPath, { encoding: 'utf8', signal: options.signal }); }
+    catch (cause) {
+      if (cause?.name === 'AbortError') throw cause;
+      throw new DrawMotiveError('RESOURCE_NOT_FOUND', 'Could not read the selected local runtime manifest', { cause, details: { manifest: manifestPath } });
+    }
+    try { manifest = JSON.parse(json); }
+    catch (cause) { throw new DrawMotiveError('INVALID_MANIFEST', 'The selected local runtime manifest is not valid JSON', { cause }); }
+    const resolveAsset = options.resolveAsset;
+    // Use the selected manifest and directory together for every native module,
+    // theme and font. A missing local artifact must never load packaged bytes.
+    options = { ...options, resolveAsset: asset => {
+      const defaultUrl = pathToFileURL(path.join(directory, asset.path));
+      return resolveAsset ? resolveAsset(asset, defaultUrl) : defaultUrl;
+    } };
+  }
   return startTextGraphRuntime(options, manifest, async (item, context) => {
     try {
       if (item.url.protocol === 'file:') {

package/src/runtime/render-resources.js

@@ -2,19 +2,18 @@ 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(''));
-}
+import { createFontPreparation, fontBase64 as base64, fontCapability } from './font-resources.js';
+import { DrawMotiveError } from './errors.js';
 
 /** Preparation lives inside the instance operation queue; validation never triggers font I/O. */
 export function createRenderingExecutor({ manifest, options, readAsset, execute }) {
   let configured = false;
+  const lazy = manifest.capabilities?.includes(fontCapability);
+  const prepareFonts = lazy ? createFontPreparation({ options, readAsset, execute }) : undefined;
   return async (request, context = {}) => {
     const loadingOptions = { ...options, signal: context.signal };
     throwIfAborted(context.signal);
+    if (!lazy && options.fontAssets?.catalog) throw new DrawMotiveError('UNSUPPORTED_CAPABILITY', 'This runtime does not support lazy font assets');
     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 });
@@ -31,14 +30,16 @@ export function createRenderingExecutor({ manifest, options, readAsset, execute
       const fallbackFamilies = [];
       for (const pack of options.languagePacks ?? []) {
         for (const font of pack.fonts) {
+          if (lazy && font.coverage) continue;
           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());
+          const item = { asset: { path: `font:${font.family}`, mediaType: 'font/ttf', bytes: font.bytes, sha256: font.sha256 }, url: font.source };
+          const bytes = font.coverage
+            ? await readVerifiedAsset(item, loadingOptions, font.source instanceof Uint8Array ? async () => new Response(font.source) : readAsset)
+            : font.source instanceof Uint8Array ? font.source : new Uint8Array(await (await readAsset(item, loadingOptions)).arrayBuffer());
           throwIfAborted(context.signal);
-          fonts.push({ family: font.family, data: base64(bytes) });
+          fonts.push({ family: font.family, data: base64(bytes), ...(font.languages ? { languages: font.languages } : {}) });
         }
-        for (const family of pack.fallbackFamilies) if (!fallbackFamilies.includes(family)) fallbackFamilies.push(family);
+        for (const family of pack.fallbackFamilies) if (fonts.some(font => font.family === family) && !fallbackFamilies.includes(family)) fallbackFamilies.push(family);
       }
       throwIfAborted(context.signal);
       decodeConfiguration(await execute(JSON.stringify({ protocolVersion: 1, operation: 'configure', theme, fonts, fallbackFamilies })));
@@ -46,6 +47,6 @@ export function createRenderingExecutor({ manifest, options, readAsset, execute
       configured = true;
       throwIfAborted(context.signal);
     }
-    return execute(request);
+    return prepareFonts ? prepareFonts(request, context) : execute(request);
   };
 }

package/src/runtime/rendering.js

@@ -7,14 +7,15 @@ const stages = ['parse', 'semantic', 'layout', 'render', 'font'];
 export function normalizeRenderOptions(source, options) {
   const invalid = message => { throw new DrawMotiveError('INVALID_ARGUMENT', message); };
   if (typeof source !== 'string' || !options || typeof options !== 'object' || Array.isArray(options)) invalid('Rendering requires a source string and options object');
-  const { encoding = 'bytes', scale = 2, padding = 10, maxWidth, signal } = options;
+  const { encoding = 'bytes', scale = 1, padding = 10, maxWidth, signal, language } = options;
+  if (language !== undefined && (typeof language !== 'string' || !/^[a-z]{2,8}(?:-[A-Za-z0-9]+)*$/.test(language))) invalid('language must be a language tag');
   if (!['bytes', 'base64'].includes(encoding)) invalid('encoding must be bytes or base64');
   // The native geometry contract uses float32; reject values lost at that boundary.
   if (!Number.isFinite(scale) || !Number.isFinite(Math.fround(scale)) || Math.fround(scale) <= 0) invalid('scale must be positive and representable as a finite float32');
   if (!Number.isFinite(padding) || !Number.isFinite(Math.fround(padding)) || padding < 0) invalid('padding must be non-negative and representable as a finite float32');
   if (maxWidth !== undefined && (!Number.isSafeInteger(maxWidth) || maxWidth <= 0)) invalid('maxWidth must be a positive integer');
   validateSignal(signal);
-  return { encoding, signal, request: { protocolVersion: 1, operation: 'render', source, export: { format: 'png', scale, padding, ...(maxWidth === undefined ? {} : { maxWidth }) } } };
+  return { encoding, signal, request: { protocolVersion: 1, operation: 'render', source, ...(language === undefined ? {} : { language }), export: { format: 'png', scale, padding, ...(maxWidth === undefined ? {} : { maxWidth }) } } };
 }
 
 /** Accept canonical base64 only; platform atob implementations otherwise tolerate corruption. */
@@ -34,17 +35,25 @@ export function decodeRender(json, encoding) {
     const diagnostics = decodeDiagnostics(value.diagnostics, stages);
     if (value.success === diagnostics.some(item => item.severity === 'error')) throw new Error('Inconsistent success');
     if (!value.success) {
-      if (['png', 'width', 'height'].some(key => Object.hasOwn(value, key))) throw new Error('Failure contains image data');
+      if (['png', 'width', 'height', 'displayWidth', 'displayHeight'].some(key => Object.hasOwn(value, key))) throw new Error('Failure contains image data');
       return Object.freeze({ success: false, diagnostics });
     }
     if (![value.width, value.height].every(n => Number.isSafeInteger(n) && n > 0 && n <= 0x7fffffff)) throw new Error('Invalid dimensions');
+    // Only the native exporter knows the effective density after maxWidth clamps
+    // the raster. Older runtimes may omit this additive pair entirely.
+    const displayDimensions = {};
+    if (Object.hasOwn(value, 'displayWidth') || Object.hasOwn(value, 'displayHeight')) {
+      if (![value.displayWidth, value.displayHeight].every(n => Number.isFinite(n) && n > 0)) throw new Error('Invalid display dimensions');
+      displayDimensions.displayWidth = value.displayWidth;
+      displayDimensions.displayHeight = value.displayHeight;
+    }
     const bytes = decodeBase64(value.png);
     const signature = [137, 80, 78, 71, 13, 10, 26, 10];
     if (bytes.length < 33 || !signature.every((byte, index) => bytes[index] === byte)) throw new Error('Invalid PNG signature');
     const header = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
     if (header.getUint32(8) !== 13 || header.getUint32(12) !== 0x49484452
         || header.getUint32(16) !== value.width || header.getUint32(20) !== value.height) throw new Error('PNG dimensions disagree');
-    return Object.freeze({ success: true, png: encoding === 'base64' ? value.png : bytes, width: value.width, height: value.height, diagnostics });
+    return Object.freeze({ success: true, png: encoding === 'base64' ? value.png : bytes, width: value.width, height: value.height, ...displayDimensions, diagnostics });
   } catch (cause) {
     throw new DrawMotiveError('INVALID_RESPONSE', 'The rendering response violates protocol 1', { cause });
   }