@drawmotive/textgraph 0.1.0-alpha.1 → 0.2.1

package/scripts/copy-assets.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { cp, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const source = fileURLToPath(new URL('../generated/wasm/', import.meta.url));
+
+/** Resolve existing ancestors too, so an output symlink cannot point into the installed runtime. */
+async function canonicalPath(directory) {
+  try {
+    return await realpath(directory);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return path.join(await canonicalPath(path.dirname(directory)), path.basename(directory));
+  }
+}
+
+function contains(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/** Copy the complete installed runtime, including scripts, fonts and licenses, without deleting output. */
+export async function copyRuntimeAssets(destination) {
+  if (typeof destination !== 'string' || destination.trim() === '') {
+    throw new Error('Usage: textgraph-copy-assets <destination>');
+  }
+  const runtime = await realpath(source);
+  const output = await canonicalPath(path.resolve(destination));
+  if (output === path.parse(output).root || contains(runtime, output) || contains(output, runtime)) {
+    throw new Error('Choose a destination outside the installed runtime and below a static asset directory.');
+  }
+  await mkdir(output, { recursive: true });
+  await cp(runtime, output, { recursive: true, force: true });
+  return output;
+}
+
+// Canonicalize both paths: Windows short temp paths and directory aliases can
+// give argv and the ESM loader different spellings for the same executable.
+if (process.argv[1] && await realpath(process.argv[1]) === await realpath(fileURLToPath(import.meta.url))) {
+  try {
+    const [destination, ...extra] = process.argv.slice(2);
+    if (extra.length) throw new Error('Usage: textgraph-copy-assets <destination>');
+    console.log(`TextGraph runtime copied to ${await copyRuntimeAssets(destination)}`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/src/index.d.ts

@@ -114,7 +114,7 @@ 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. */
+  /** 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 +125,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/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

@@ -6,7 +6,10 @@ 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)) });
+  // 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;
+  return initialize({ ...options, loadRuntime: options.loadRuntime ?? (context => loadNodeRuntime(context, manifest, directory)) });
 }
 
 export const platform = 'node';

package/src/react/index.d.ts

@@ -0,0 +1,20 @@
+import type { ImgHTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { TextGraphInitializeOptions, TextGraphRenderPngOptions } from '../index.js';
+
+/** Keep options stable (module constant or useMemo); replacing them replaces the runtime. */
+export interface TextGraphProviderProps {
+  options?: TextGraphInitializeOptions;
+  children?: ReactNode;
+}
+
+/** The component owns its image source and cancellation; other image attributes pass through. */
+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;
+}
+
+export declare function TextGraphProvider(props: TextGraphProviderProps): ReactElement;
+export declare function TextGraph(props: TextGraphProps): ReactElement;

package/src/react/index.js

@@ -0,0 +1,59 @@
+'use client';
+
+import { createContext, createElement, useContext, useEffect, useMemo, useState } from 'react';
+import { createRuntimeResource } from './runtime.js';
+
+const RuntimeContext = createContext(null);
+const defaultOptions = Object.freeze({});
+
+/** Shares a lazy browser runtime across diagrams and owns its eventual disposal. */
+export function TextGraphProvider({ options = defaultOptions, children }) {
+  const resource = useMemo(() => createRuntimeResource(options), [options]);
+  useEffect(() => resource.retain(), [resource]);
+  return createElement(RuntimeContext.Provider, { value: resource }, 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…', style, ...imageProps }) {
+  const shared = useContext(RuntimeContext);
+  const resource = useMemo(() => shared ?? createRuntimeResource(defaultOptions), [shared]);
+  const { scale = 1, padding, maxWidth } = renderOptions;
+  const request = useMemo(() => ({ source, scale, padding, maxWidth, resource }),
+    [source, scale, padding, maxWidth, resource]);
+  const [state, setState] = useState(null);
+
+  useEffect(() => {
+    const release = resource.retain();
+    const controller = new AbortController();
+    void (async () => {
+      try {
+        const runtime = await resource.get();
+        if (controller.signal.aborted) return;
+        const result = await runtime.renderPng(source, { scale, padding, maxWidth, encoding: 'base64', signal: controller.signal });
+        if (!controller.signal.aborted) setState({ request, result });
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          // Host loaders may reject arbitrary values, including null. Keep the
+          // failure branch explicit so reporting an error cannot break React render.
+          setState({ request, error: error instanceof Error ? error : new Error(String(error ?? 'Could not render diagram')) });
+        }
+      }
+    })();
+    return () => { controller.abort(); release(); };
+  }, [request]);
+
+  // State is keyed by the whole request so old images disappear immediately,
+  // even before passive effects clean up the previous asynchronous render.
+  if (state?.request !== request) return createElement('span', { role: 'status' }, loading);
+  if (state.error || !state.result.success) {
+    const message = state.error?.message ?? state.result.diagnostics.map(item => item.message).join('\n');
+    return createElement('span', { role: 'alert' }, message || 'Could not render diagram');
+  }
+  const result = state.result;
+  // 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/react/runtime.js

@@ -0,0 +1,37 @@
+import { initializeTextGraph } from '../platform/browser.js';
+
+/** A provider owns one lazy runtime; retaining it has no I/O during React render. */
+export function createRuntimeResource(options) {
+  let users = 0;
+  let pending;
+  return {
+    retain() {
+      users++;
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        users--;
+        // StrictMode replays effects synchronously. Defer final release so that
+        // replay reuses the same .NET module graph instead of starting another.
+        queueMicrotask(() => {
+          if (users !== 0 || !pending) return;
+          const retiring = pending;
+          pending = undefined;
+          // Startup may finish after unmount. Dispose that instance as well;
+          // there is no mounted view to receive startup or cleanup errors.
+          void retiring.then(runtime => runtime.dispose()).catch(() => undefined);
+        });
+      };
+    },
+    get() {
+      if (!pending) {
+        const attempt = initializeTextGraph(options);
+        pending = attempt;
+        // A later input change may retry a failed startup.
+        void attempt.catch(() => { if (pending === attempt) pending = undefined; });
+      }
+      return pending;
+    },
+  };
+}

package/src/runtime/dotnet.js

@@ -83,7 +83,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/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/rendering.js

@@ -7,7 +7,7 @@ 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 } = options;
   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');
@@ -34,17 +34,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 });
   }