@drawmotive/textgraph 0.2.0 → 0.2.2-alpha.1

package/README.md

@@ -1,133 +1,235 @@
-# TextGraph SDK
+# TextGraph
 
-Render TextGraph diagrams as PNG images and validate diagram source.
+**Turn text into diagrams in your application.**
 
-> **[Report all TextGraph issues on GitHub →](https://github.com/drawmotive/textgraph/issues)**
-> Bugs, feature requests, documentation, playground, SDK, fonts, Markdown, and VS Code issues all belong in this shared tracker.
+Render flowcharts and directed graphs as PNGs in Node.js, browsers, React, and Web
+Workers. TextGraph handles automatic layout and provides source validation and
+rendering diagnostics. The renderer runs where your code runs; no hosted rendering
+API or API key is required.
 
-## Installation
+[Documentation](https://textgraph.dev/diagrams/flowcharts) ·
+[Runnable examples](https://github.com/drawmotive/textgraph/tree/main/samples) ·
+[API reference](https://github.com/drawmotive/textgraph/blob/main/docs/api-v1.md)
+
+## A few lines. A diagram.
+
+```textgraph
+(horizontal)
+browser -> api -> database
+
+browser: Browser
+api(fill primary): API Gateway
+database: Database
+```
+
+![TextGraph output: Browser connects to API Gateway, which connects to Database.](https://raw.githubusercontent.com/drawmotive/textgraph/main/docs/images/service-flow.png)
+
+**[Edit this exact diagram in the playground →](https://textgraph.dev/playground#source=%28horizontal%29%0Abrowser%20-%3E%20api%20-%3E%20database%0A%0Abrowser%3A%20Browser%0Aapi%28fill%20primary%29%3A%20API%20Gateway%0Adatabase%3A%20Database%0A)**
+
+Actual SDK output from
+[service-flow.textgraph](https://github.com/drawmotive/textgraph/blob/main/examples/service-flow.textgraph).
+Keep source in version control and render again when relationships change.
+TextGraph uses a small, structured language; it does not interpret unrestricted prose.
+
+## Choose your workflow
+
+| What you want to do | Use | Working example |
+| --- | --- | --- |
+| Generate diagrams for documentation, reports, or build jobs | Node.js: write PNG bytes to a file | [Node sample](https://github.com/drawmotive/textgraph/tree/main/samples/node) |
+| Embed live diagrams in dashboards or internal tools | React component and shared provider | [React + Vite sample](https://github.com/drawmotive/textgraph/tree/main/samples/react-vite) |
+| Add editable source and previews to a web app | Browser SDK | [Plain JavaScript sample](https://github.com/drawmotive/textgraph/tree/main/samples/browser) |
+| Keep the UI responsive while rendering larger diagrams | SDK in a module Web Worker | [Worker sample](https://github.com/drawmotive/textgraph/tree/main/samples/worker) |
+| Check syntax and references before rendering | The SDK's `validate()` method | [Validation example](https://github.com/drawmotive/textgraph/blob/main/examples/node.mjs) |
+
+For existing documentation, use the
+[Markdown/VitePress plugin](https://textgraph.dev/integrations/markdown) or
+[VS Code Markdown extension](https://textgraph.dev/integrations/vscode).
+
+## Install
 
 ```bash
-npm install @drawmotive/textgraph@0.2.0
+npm install @drawmotive/textgraph@0.2.2-alpha.1
 ```
 
-Requires Node.js 22+ or a modern browser.
+Requires **Node.js 22+** or a modern browser with WebAssembly and Web Crypto.
+Browser applications need HTTPS or localhost. React support is an optional entry
+in this package, compatible with React 18.2+ and 19.
 
-Version `0.2.0` is the first stable release. Install the exact version above or use `@latest` for the current stable release.
+## Render a PNG in Node.js
 
-## Quickstart
+Save as `render.mjs`, then run `node render.mjs`:
 
-```typescript
+```javascript
 import { writeFile } from "node:fs/promises";
-import { initializeTextGraph } from "@drawmotive/textgraph";
+import { initializeTextGraph } from "@drawmotive/textgraph/node";
 
 const textgraph = await initializeTextGraph();
-
 try {
-  const result = await textgraph.renderPng("A -> B");
-
+  const result = await textgraph.renderPng("browser -> api -> database");
   if (result.success) {
     await writeFile("diagram.png", result.png);
+    console.log("Saved diagram.png");
   } else {
-    console.log(result.diagnostics);
+    console.error(result.diagnostics);
+    process.exitCode = 1;
   }
 } finally {
   await textgraph.dispose();
 }
 ```
 
-PNG output defaults to bytes, scale `2`, padding `10`, and a white background. Reuse an instance for multiple diagrams, then call `dispose()`.
-
-## Higher resolution
+Node reads the included runtime from the installed package. No browser, .NET
+installation, or asset-copy step is needed. Reuse an initialized instance for
+multiple diagrams, then dispose it when the job is finished.
 
-```typescript
-const result = await textgraph.renderPng("A -> B", {
-  scale: 4,
-  padding: 24,
-});
-```
+[Complete file-to-PNG sample →](https://github.com/drawmotive/textgraph/tree/main/samples/node)
 
-## Display in a browser
+## Add a diagram to React
 
-For a bundled application, copy the runtime into its public directory before development or build:
+For browser, React, and Worker applications, copy the runtime assets before
+starting development or building:
 
 ```bash
 npx textgraph-copy-assets public/textgraph/wasm
 ```
 
-The copy command and React entry below are available starting with `0.2.0`. The [repository samples](https://github.com/drawmotive/textgraph/tree/main/samples) install and run the SDK as a tarball.
+Then render a component:
+
+```tsx
+import { TextGraph, TextGraphProvider } from "@drawmotive/textgraph/react";
+import type { TextGraphInitializeOptions } from "@drawmotive/textgraph";
+
+const options: TextGraphInitializeOptions = {
+  resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
+};
+
+export function Diagram({ source }: { source: string }) {
+  return (
+    <TextGraphProvider options={options}>
+      <TextGraph source={source} alt="Service dependencies" />
+    </TextGraphProvider>
+  );
+}
+```
+
+Changing `source` updates the image. For several diagrams, put one provider
+around their common parent. Loading states and rendering diagnostics are built in.
+The component renders on the main thread; use the Worker sample for heavier
+interactive workloads.
+
+[React + Vite sample →](https://github.com/drawmotive/textgraph/tree/main/samples/react-vite) ·
+[React guide →](https://github.com/drawmotive/textgraph/blob/main/docs/react.md)
 
-```typescript
+## Render in a browser
+
+After copying assets as shown above, use this in a bundled browser application:
+
+```javascript
 import { initializeTextGraph } from "@drawmotive/textgraph/browser";
 
 const textgraph = await initializeTextGraph({
   resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
 });
-const result = await textgraph.renderPng("A -> B", {
-  encoding: "base64",
-  maxWidth: 1200,
-});
-
-if (result.success) {
-  const image = document.createElement("img");
-  image.src = `data:image/png;base64,${result.png}`;
-  image.alt = "A connects to B";
-  document.body.append(image);
+try {
+  const result = await textgraph.renderPng("browser -> api -> database", {
+    encoding: "base64",
+    scale: 2,
+  });
+  if (result.success) {
+    const image = document.createElement("img");
+    image.src = `data:image/png;base64,${result.png}`;
+    image.alt = "Browser connects to API, which connects to database";
+    image.width = result.displayWidth ?? result.width / 2;
+    image.height = result.displayHeight ?? result.height / 2;
+    image.style.maxWidth = "100%";
+    image.style.height = "auto";
+    document.body.append(image);
+  } else {
+    console.error(result.diagnostics);
+  }
+} finally {
+  await textgraph.dispose();
 }
-
-await textgraph.dispose();
 ```
 
-The npm package includes WASM, .NET runtime modules, fonts, and themes. Bundlers do not automatically deploy these dynamically loaded files. Re-copy assets after SDK updates and use an asset URL matching your deployment base path. Node loads assets from the installed package without this copy step.
+For repeated edits, keep the runtime alive and dispose it when the editor closes.
+An async call still computes on its current thread; the Worker sample moves
+rendering off the UI thread.
 
-## React
+[Browser example →](https://github.com/drawmotive/textgraph/tree/main/samples/browser) ·
+[Worker example →](https://github.com/drawmotive/textgraph/tree/main/samples/worker)
 
-React 18.2+ and 19 use the same SDK through an optional entry; non-React users do not need React. Configure assets once and pass DSL to `TextGraph`:
+### Deploy the browser runtime
 
-```tsx
-import { TextGraph, TextGraphProvider } from "@drawmotive/textgraph/react";
+- Add the asset-copy command to your application's `predev` and `prebuild` scripts.
+- Deploy the complete copied directory: WASM, JavaScript, fonts, themes, and
+  licenses. Re-copy after SDK updates; keep SDK and runtime versions matched.
+- The resolver above assumes hosting at `/`. For a subdirectory, use your deployed
+  base path; the Vite samples demonstrate `import.meta.env.BASE_URL`.
 
-const options = {
-  resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
-};
+[Asset hosting and CSP →](https://github.com/drawmotive/textgraph/blob/main/docs/api-v1.md#assets-csp-and-offline-operation)
 
-export function App() {
-  return (
-    <TextGraphProvider options={options}>
-      <TextGraph source={"A -> B"} alt="Flow diagram" />
-    </TextGraphProvider>
-  );
-}
+## Validation and output options
+
+On an initialized instance:
+
+```javascript
+const validation = await textgraph.validate("browser -> api -> database");
+console.log(validation.valid, validation.diagnostics);
+
+const image = await textgraph.renderPng("browser -> api -> database", {
+  scale: 2,
+  padding: 24,
+  maxWidth: 1200,
+});
 ```
 
-Changing `source` updates the image. The provider shares one lazy runtime across diagrams and disposes it on unmount. See [React integration](docs/react.md) for loading, errors, rendering options, and server rendering.
+Validation checks parsing and semantic references; rendering additionally checks
+layout and output. Diagram failures return diagnostics. Operational failures
+reject with `DrawMotiveError`.
 
-## Runnable samples
+PNG output defaults to bytes, scale `1`, padding `10`, and a white background.
+Use higher scale for more pixels and returned display dimensions for web sizing.
+TypeScript declarations are included for every public entry point.
 
-The [samples directory](https://github.com/drawmotive/textgraph/tree/main/samples) contains browser JavaScript, React/Vite, Web Worker, and Node applications. Each installs a packed SDK and includes complete run instructions. Samples stay in the repository and are excluded from npm.
+[Full API and options →](https://github.com/drawmotive/textgraph/blob/main/docs/api-v1.md)
 
-## Additional languages
+## Run the examples locally
 
-All optional fonts share the `@drawmotive/textgraph-fonts` package, which is not yet published. Select the language descriptors needed by the application; `zhCN` provides Simplified Chinese coverage.
+Samples are complete applications in the public repository and use a local
+package tarball. To try the React sample from a fresh checkout:
 
 ```bash
-npm install @drawmotive/textgraph-fonts
+git clone https://github.com/drawmotive/textgraph.git
+cd textgraph
+node samples/prepare.mjs react-vite
+cd samples/react-vite
+npm run dev
 ```
 
-```typescript
-import { initializeTextGraph } from "@drawmotive/textgraph";
-import { zhCN } from "@drawmotive/textgraph-fonts";
+Vite samples require Node.js **22.12+**. Replace `react-vite` with `browser` or
+`worker` for those samples. The Node sample uses `npm start` instead.
+Preparation packages the checkout and installs sample dependencies; it does not
+publish anything. Samples are not included in the npm package.
 
-const textgraph = await initializeTextGraph({ languagePacks: [zhCN] });
-const result = await textgraph.renderPng("A: 开始\nB: 完成\nA -> B");
-await textgraph.dispose();
-```
+[Sample setup and deployment →](https://github.com/drawmotive/textgraph/blob/main/samples/README.md)
 
-## Validation
+## Current scope
 
-```typescript
-const result = await textgraph.validate("A -> B");
-console.log(result.valid, result.diagnostics);
-```
+- **Available:** flowcharts and directed graphs, automatic layout, PNG rendering,
+  and source validation.
+- **Not available yet:** mind maps, sequence diagrams, slides, and SVG export.
+- **Fonts:** Noto Sans and Fuzzy Bubbles are included. Custom font descriptors are
+  supported; the optional `@drawmotive/textgraph-fonts` package is not published.
+  See [font configuration](https://github.com/drawmotive/textgraph/blob/main/docs/api-v1.md#fonts-and-language-packs).
+
+## Project links
+
+[Language guide](https://textgraph.dev/diagrams/flowcharts) ·
+[Changelog](https://github.com/drawmotive/textgraph/blob/main/CHANGELOG.md) ·
+[Report an issue](https://github.com/drawmotive/textgraph/issues) ·
+[MIT license](https://github.com/drawmotive/textgraph/blob/main/LICENSE)
+
+### Try it in a browser
 
-Diagram errors return diagnostics. Operational errors throw `DrawMotiveError`. See the [API reference](docs/api-v1.md) for options, cancellation, and deployment.
+[Open the runnable HTML/JavaScript example](https://textgraph.dev/examples/textgraph/) to edit source, see its PNG and copy the integration code without installing anything. For visual editing, see [the DrawMotive editor](https://textgraph.dev/editor/).

package/docs/api-v1.md

@@ -20,12 +20,12 @@ Initialization resolves after manifest and real bridge agree on ABI, protocol an
 
 ## PNG rendering
 
-`renderPng(source, options?)` returns `{ success: true, png, width, height, diagnostics }` or `{ success: false, diagnostics }`. Diagram failures resolve with diagnostics and contain no image data. Successful results and diagnostics are frozen; byte output is a detached, caller-owned `Uint8Array`. Output uses a white background.
+`renderPng(source, options?)` returns `{ success: true, png, width, height, displayWidth?, displayHeight?, diagnostics }` or `{ success: false, diagnostics }`. `width` and `height` are raster pixels. The optional display dimensions are positive numbers representing logical size: raster dimensions divided by the effective scale after any `maxWidth` reduction. Older runtimes omit both fields. Diagram failures resolve with diagnostics and contain no image data. Successful results and diagnostics are frozen; byte output is a detached, caller-owned `Uint8Array`. Output uses a white background.
 
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `encoding` | `"bytes"` | `"bytes"` returns `Uint8Array`; `"base64"` returns a string without a data-URL prefix. |
-| `scale` | `2` | Positive finite render scale. |
+| `scale` | `1` | Positive finite raster density relative to logical diagram size. |
 | `padding` | `10` | Non-negative finite padding in diagram units. |
 | `maxWidth` | Omitted | Positive safe integer maximum output width in pixels; preserves proportions and only reduces output size. |
 | `signal` | Omitted | Cancels queued work or discards completed work after cancellation. |
@@ -34,15 +34,48 @@ Literal encodings infer their corresponding PNG type in TypeScript; union encodi
 
 Scale and padding must remain finite when represented as 32-bit floats; scale must also remain greater than zero. Invalid arguments reject with `INVALID_ARGUMENT`.
 
+For web display, use scale `2` and the returned display dimensions as image dimensions, with `max-width: 100%; height: auto`. Increasing density then improves sharpness without enlarging the diagram. DPI metadata does not change CSS sizing. When an older runtime omits display dimensions, dividing raster dimensions by the requested scale works only when `maxWidth` did not reduce the effective density.
+
 After applying `maxWidth`, output is limited to 16,384 pixels per side and 16,777,216 pixels in total. Larger images return the `TG_RENDER_SIZE_LIMIT` diagnostic. PNG dimensions and signature are checked against the response metadata; malformed responses reject with `INVALID_RESPONSE`.
 
 ## Fonts and language packs
 
+Runtimes advertising `textgraph-fonts-v1` prepare actual visible labels before measurement.
+Official Chinese, Japanese and emoji fonts load only when needed, then remain decoded
+until the instance is disposed. Node discovers an installed `@drawmotive/textgraph-fonts`
+package automatically; browser hosts copy its assets and supply their deployed catalog:
+
+```javascript
+const runtime = await initializeTextGraph({
+  fontAssets: { catalog: new URL("/textgraph/fonts/font-catalog.json", location.origin), fallback: false },
+});
+```
+
+`fontAssets.catalog` is authoritative: missing or corrupt files fail without silently
+switching versions. With no catalog or language packs, fonts are resolved on demand
+from `https://staging.drawmotive.com/static/font-catalog.json`. Set `fallback: false`
+to prohibit that external access, or supply another catalog URL as `fallback`.
+Installing a local package takes precedence over fallback even in offline mode.
+Use `languagePacks: []` with `fallback: false` to explicitly disable automatic font sources.
+
+Catalog fonts carry actual Unicode coverage, language hints, byte sizes and SHA-256.
+They are verified before native installation. Catalog URLs are cached per instance;
+HTTP font URLs include the content hash as a stable `v` parameter. HTTP caching remains
+browser/server-owned; there is no new IndexedDB or Service Worker. Offline operation
+requires the complete runtime and font package on a local filesystem or local server;
+an online page cannot fetch an uncached font after losing network access.
+
+`renderPng(source, { language: "ja" })` can disambiguate Han-only labels. Without a hint,
+kana selects Japanese for that label and Han-only labels use Chinese. Grapheme-aware
+emoji selection includes flags, ZWJ sequences, modifiers and keycaps. Font selection
+does not depend on which languages were rendered previously. Unsupported glyphs still
+produce font diagnostics; the font catalog defines coverage, not support for every language.
+
 Default rendering includes Noto Sans and Fuzzy Bubbles. Configure additional fonts with `initializeTextGraph({ languagePacks: [...] })`. A `TextGraphLanguagePack` has a non-empty `fonts` array of `{ family, source }` and optional ordered `fallbackFamilies`. Font sources are `URL` objects or non-empty `Uint8Array` values. In Node, use `pathToFileURL()` for filesystem paths; relative asset modules can use `new URL("./font.ttf", import.meta.url)` across platforms.
 
-The initializer copies byte arrays, URLs and descriptor arrays before asynchronous work, so later caller mutations cannot change rendering resources. Families must be unique across all packs and bundled defaults. Fallback families must name configured fonts. Descriptor validation performs no font I/O. Font contents are loaded and configured on first render; validate-only use does not read fonts or themes. Font-loading or configuration failures reject with `DrawMotiveError`; a later render can retry.
+The initializer copies byte arrays, URLs and descriptor arrays before asynchronous work, so later caller mutations cannot change rendering resources. Families must be unique across all packs and bundled defaults. Fallback families must name configured fonts. Descriptor validation performs no font I/O. Legacy descriptors without coverage load on first render; official descriptors carry coverage, languages, bytes and SHA-256 and load on demand. Validate-only use does not read fonts or themes. Font-loading or configuration failures reject with `DrawMotiveError`; a later render can retry.
 
-Bundled resource URLs use `resolveAsset`. Language-pack sources use their supplied URL directly and the platform data loader, including custom `fetch` or the network adapter for network URLs. All optional fonts share `@drawmotive/textgraph-fonts`, installed separately. It currently exports a `zhCN` descriptor for Simplified Chinese; additional language descriptors will use the same package. The package is not yet published.
+Bundled resource URLs use `resolveAsset`. Language-pack sources use their supplied URL directly and the platform data loader, including custom `fetch` or the network adapter for network URLs. All optional fonts share `@drawmotive/textgraph-fonts`, installed separately. It exports `zhCN`, `ja`, `emoji`, `languagePacks` and `fontCatalogUrl`.
 
 ## Lifecycle
 
@@ -57,15 +90,21 @@ Existing `loadRuntime`, `readonly` and `mutate` hooks remain for development com
 - Node 22 or later: root or `/node`; runtime modules use installed-package `file:` URLs, data uses `node:fs/promises`. HTTP data can use injected fetch, but Node does not import remote HTTP JavaScript. Node `worker_threads` uses `/node`.
 - Browser: `/browser` or browser conditional export. Modern Chromium, Firefox and WebKit with WebAssembly, ESM, fetch, BigInt and Web Crypto are tested. HTTPS or localhost is required for Web Crypto. Exact engine versions are pinned by the Playwright lockfile; historical minimum browser versions are not claimed.
 - Browser module Web Worker: `/worker` inside a host-created Worker; no DOM, window, automatic RPC or Worker pool.
-- React 18.2+ or 19: `/react` provides `TextGraph` and `TextGraphProvider` over the browser runtime. See [React integration](react.md). This entry is an unreleased addition after `0.1.0-alpha.1`.
+- React 18.2+ or 19: `/react` provides `TextGraph` and `TextGraphProvider` over the browser runtime. See [React integration](react.md).
 
 Root condition precedence is worker/browser/node/default. Explicit entries avoid bundler ambiguity. Browser/Worker source graphs exclude Node imports.
 
+The repository development command can set `DRAWMOTIVE_TEXTGRAPH_RUNTIME` to an absolute generated directory for Node and inherited Node Workers. The default Node loader then reads that directory's `wasm-manifest.json` and resolves native modules, fonts, and themes there; existing manifest validation and asset integrity checks still apply. Missing or invalid local artifacts reject initialization or rendering without falling back to packaged assets. A supplied `resolveAsset` receives the selected local URL as its default; an explicit `loadRuntime` remains authoritative. Browser and browser Worker loaders ignore this environment variable.
+
+Keep this selection scoped to the development command. With it absent, package loading is unchanged; `info.packageVersion` identifies the JavaScript wrapper and capabilities reflect the intersection of the selected manifest and native bridge. Native manifests marked `privateSource.development: true` are rejected by release verification.
+
 ## Assets, CSP and offline operation
 
 Defaults resolve relative to the installed module. `resolveAsset(asset, defaultUrl)` may return an absolute URL or URL object for each asset. Deploy the complete `generated/wasm` directory: bundlers must preserve/copy these files and configure the resolver for their deployed location. It covers both JS and data. Instance query parameters isolate mutable .NET ESM state; servers should serve identical module bytes regardless of that query.
 
-`fetch` or `adapters.network.fetch` receives data URLs and the applicable initialization or render signal. JS uses dynamic import, which injected fetch cannot intercept. Offline installations must cache the module graph as well as WASM/data at importable URLs, using a Service Worker or local server. No GitHub Releases download is required.
+`fetch` or `adapters.network.fetch` receives data URLs and the applicable initialization or render signal. Independent startup data assets download concurrently; all must pass integrity checks before native startup. JS uses dynamic import, which injected fetch cannot intercept. Offline installations must cache the module graph as well as WASM/data at importable URLs, using a Service Worker or local server. No GitHub Releases download is required.
+
+Browser, Worker and Node entry points share this concurrent startup loader. Markdown integrations using the Node entry point inherit it when upgraded to the fixed SDK; their default asset reads are local files. Publishing an SDK version does not update pinned dependencies or previously bundled extensions: consumers must update their dependency and lockfile, then rebuild and redeploy or repackage. The separate `@drawmotive/editor` package uses Blazor's own concurrent loader.
 
 Serve WASM as `application/wasm`, JS as `text/javascript`, and provide applicable CORS headers for cross-origin assets. Same-origin CSP: `default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'; worker-src 'self'`. No eval, new Function or DOM script injection is used. Cross-origin isolation and SharedArrayBuffer are not required by this single-threaded runtime.
 
@@ -77,12 +116,19 @@ DSL failures resolve with diagnostics. Operational errors reject with `DrawMotiv
 
 ## ABI and versioning
 
+The additive `textgraph-fonts-v1` capability adds commands to `Execute`:
+`prepare-fonts` takes `source` and optional `language` and returns visible grapheme
+`fontRuns` with `text`, `language` and `missing`; `install-fonts` atomically appends
+fonts with language metadata; `cancel-prepare` releases interrupted preparation.
+Render commands accept the same language hint. Existing configuration/disposal
+envelopes remain unchanged. The wrapper checks this capability before using a catalog.
+
 ABI 1.0.0 retains GetAbiVersion/GetPackageKind/CountParseDiagnostics and adds GetRuntimeInfo(), Validate(source) and Execute(requestJson) on DrawMotive.TextGraph.Bridge.Program. Info returns JSON `{ abiVersion, packageKind, protocolVersion: 1, capabilities }`; Validate returns `{ protocolVersion: 1, valid, diagnostics }`. Wrappers require `textgraph-validate-v1`; PNG rendering additionally requires `textgraph-render-v1` and the manifest `bridge.execute` export. Legacy validation exports remain supported. This is a managed export/JSON protocol, not a raw WASM pointer ABI.
 
 `generated/wasm-manifest.json` is authoritative; its ESM projection avoids JSON-module browser assumptions. Shipped schemas describe the manifest, validation response and rendering response. Manifest schema, ABI, protocol and npm versions are separate. Additive exports use capabilities; incompatible wire changes require a new supported version. npm versions and bundled assets are released together. DSL/file-format versions are not frozen by this milestone.
 
 Assets have relative path, media type, byte count and SHA-256. Packaging checks reject missing/extra assets, debug files, hash/projection/version drift. Runtime data assets are hash-checked before native startup. Bundled fonts and themes are loaded and hash-checked lazily before the first render; license files require no runtime I/O. These checks establish distribution consistency, not authenticated runtime signatures. `privateSource.commit` identifies committed private C# and bridge inputs. Toolchain changes may change bytes; cross-toolchain byte-for-byte reproducibility is not promised.
 
-The rendering wire uses one `Execute(requestJson)` export. Configuration is performed once before the first render with `{ protocolVersion: 1, operation: "configure", theme, fonts: [{ family, data }], fallbackFamilies }`, where `data` is base64 font data. Its response is `{ protocolVersion: 1, success, diagnostics }`. A render request is `{ protocolVersion: 1, operation: "render", source, export: { format: "png", scale, padding, maxWidth? } }`. Native success returns base64 `png`, `width`, `height`, and diagnostics; failures contain only `success: false` and diagnostics beside the protocol version. The JavaScript wrapper converts image data to the requested encoding.
+The rendering wire uses one `Execute(requestJson)` export. Configuration is performed once before the first render with `{ protocolVersion: 1, operation: "configure", theme, fonts: [{ family, data }], fallbackFamilies }`, where `data` is base64 font data. Its response is `{ protocolVersion: 1, success, diagnostics }`. A render request is `{ protocolVersion: 1, operation: "render", source, export: { format: "png", scale, padding, maxWidth? } }`. Native success returns base64 `png`, `width`, `height`, and diagnostics, plus an additive optional `displayWidth`/`displayHeight` pair; failures contain only `success: false` and diagnostics beside the protocol version. The JavaScript wrapper validates the display dimensions when present and converts image data to the requested encoding.
 
 For rendering-capable bridges, disposal sends `{ protocolVersion: 1, operation: "dispose" }` and validates the same success/diagnostics envelope as configuration. This request releases native resources without loading fonts or shutting down the host runtime. Legacy validation-only bridges release wrapper references directly.

package/docs/images/README.md

@@ -0,0 +1,28 @@
+# README preview
+
+`service-flow.png` is actual output from the package's bundled renderer, using
+`examples/service-flow.textgraph`. Keep the root README's source block and
+playground link synchronized with that file.
+
+Regenerate from the repository root with Node.js 22+:
+
+```bash
+node --input-type=module <<'JS'
+import { readFile, writeFile } from 'node:fs/promises';
+import { initializeTextGraph } from '@drawmotive/textgraph/node';
+
+const textgraph = await initializeTextGraph();
+try {
+  const source = await readFile('examples/service-flow.textgraph', 'utf8');
+  const result = await textgraph.renderPng(source, { scale: 2, padding: 24 });
+  if (!result.success) throw new Error(JSON.stringify(result.diagnostics));
+  await writeFile('docs/images/service-flow.png', result.png);
+} finally {
+  await textgraph.dispose();
+}
+JS
+```
+
+The root README uses an absolute GitHub raw URL so the image works on npm as well
+as GitHub. Push the image and source to the public repository before publishing
+the next npm version; npm refreshes its displayed README on publication.

package/docs/react.md

@@ -1,6 +1,6 @@
 # React integration
 
-The `/react` entry is an unreleased addition after `0.1.0-alpha.1`. React is an optional peer dependency (`^18.2.0 || ^19.0.0`); applications without React use the ordinary SDK entries.
+The `/react` entry provides a diagram component and shared runtime provider. React is an optional peer dependency (`^18.2.0 || ^19.0.0`); applications without React use the ordinary SDK entries.
 
 ## Browser assets
 
@@ -18,8 +18,7 @@ export function Diagram({ source }: { source: string }) {
   return (
     <TextGraphProvider options={options}>
       <TextGraph source={source} alt="Process flow"
-        renderOptions={{ scale: 2, maxWidth: 1200 }}
-        style={{ maxWidth: '100%', height: 'auto' }} />
+        renderOptions={{ maxWidth: 1200 }} />
     </TextGraphProvider>
   );
 }
@@ -37,12 +36,16 @@ Use your deployed base path instead of `/` for subdirectory hosting. The [React/
 | --- | --- |
 | `source` | Required DSL string; changes trigger rendering. |
 | `alt` | Image description; defaults to `TextGraph diagram`. |
-| `renderOptions` | `scale`, `padding`, and `maxWidth`, with SDK defaults. |
+| `renderOptions` | Defaults to `scale: 1`; `padding` and `maxWidth` use SDK defaults. Set `scale: 2` explicitly for higher raster density. |
 | `loading` | React content shown with `role="status"`; defaults to `Rendering diagram…`. |
 | Other image attributes | Passed to the successful `<img>`, including `className`, `style`, `width`, and `height`. |
 
 The component owns `src`, encoding, and cancellation. While new input renders, old images are replaced by loading content. A stale result cannot replace newer input. DSL diagnostics and operational failures appear as escaped text with `role="alert"`; corrected input renders again. Changing only `alt` or image styles does not rerun layout.
 
+Images use the render result's logical `displayWidth` and `displayHeight`, so increasing `scale` adds pixels without enlarging the diagram. `maxWidth` limits raster pixels rather than CSS width. Styles default to `maxWidth: '100%'` and `height: 'auto'`; supplied styles merge over these defaults, and explicit image dimensions override the logical dimensions.
+
+Older runtimes omit display dimensions. The component then divides raster dimensions by the requested scale; this preserves logical size unless `maxWidth` has lowered the effective density. Deploy matching updated runtime assets for accurate sizing in that case. PNG DPI metadata does not control CSS size.
+
 An ordinary React render uses the browser main thread. Native layout already running cannot be preempted by cancellation; for heavy interactive workloads use the [Worker sample](https://github.com/drawmotive/textgraph/tree/main/samples/worker) to move SDK execution off the UI thread. The React component does not automatically create a Worker.
 
 ## Server rendering

package/docs/releases.md

@@ -4,16 +4,14 @@ Releases are selected deliberately and published by `.github/workflows/release.y
 
 ## Channels
 
-| Version | npm dist-tag | Installation |
+| Version | npm dist-tag | Install |
 | --- | --- | --- |
-| `0.1.0-alpha.1` | `alpha` | `npm install @drawmotive/textgraph@alpha` |
-| `0.2.0` | `latest` | `npm install @drawmotive/textgraph` |
+| `0.2.1` (stable) | `latest` | `npm install @drawmotive/textgraph@0.2.1` |
+| `0.2.2-alpha.1` (preview) | `alpha` | `npm install @drawmotive/textgraph@0.2.2-alpha.1` |
 
-An exact prerelease version also works: `npm install @drawmotive/textgraph@0.1.0-alpha.1`. npm assigns `latest` on a first publication even when another tag is specified. This default is accepted: `0.1.0-alpha.1` initially owned both `alpha` and `latest`. Subsequent alpha releases update `alpha` and preserve the existing default. A stable release updates `latest`.
+Alpha releases update `alpha` and preserve an existing `latest`. npm may assign `latest` on a package’s first publication even when `alpha` is specified.
 
-No stable release is required before publishing another alpha. The script verifies the existing default and immutable artifact integrity without attempting to delete tags. To graduate an alpha, prepare and publish a new stable version.
-
-The scripts accept stable SemVer and `X.Y.Z-alpha.N`. Other channels require an explicit release-policy change. The shared optional `@drawmotive/textgraph-fonts` package has its own release lifecycle and is not published by this workflow.
+The scripts accept stable SemVer and `X.Y.Z-alpha.N`. The optional `@drawmotive/textgraph-fonts` package uses the separate fonts workflow described below.
 
 ## Account setup
 
@@ -35,10 +33,10 @@ Trusted publishing requires npm 11.5.1+ and Node.js 22.14.0+. Publication from a
 Native builds belong to the private DrawMotive repository. Commit native source, resource, and bridge changes first, then run there:
 
 ```bash
-npm run release:textgraph -- 0.2.0
+npm run release:textgraph -- 0.2.2-alpha.1
 ```
 
-This updates the package and lock versions, builds Release assets from the recorded private source commit, generates matching JSON/ESM manifests, updates the root workspace lock, and verifies asset hashes. It does not commit, push, tag, or publish. The `just release-textgraph 0.2.0` alias runs the same command.
+This updates the package and lock versions, builds Release assets from the recorded private source commit, generates matching JSON/ESM manifests, updates the root workspace lock, and verifies asset hashes. It does not commit, push, tag, or publish. The `just release-textgraph 0.2.2-alpha.1` alias runs the same command.
 
 For a JavaScript-only release reusing already verified native bytes, run in this package:
 
@@ -82,26 +80,47 @@ If npm requires a one-time code, run with `NPM_CONFIG_OTP` set in the local term
 After preparation, tests, and review, create the tag on the verified package commit:
 
 ```bash
-git tag -a textgraph-v0.2.0 -m "Release 0.2.0"
-git push origin textgraph-v0.2.0
+git tag -a textgraph-v0.2.2-alpha.1 -m "Release 0.2.2-alpha.1"
+git push origin textgraph-v0.2.2-alpha.1
 ```
 
-The release workflow resolves the tag to a commit, runs Node.js and three-browser tests on Ubuntu, packs the tested checkout, and passes the artifact to the `npm` environment for publication. All CI and release jobs use `ubuntu-latest`; the browser suite covers Chromium, Firefox, and WebKit. Stable releases select `latest` automatically. Never pass a custom dist-tag to bypass the release policy.
+The release workflow resolves the tag to a commit, runs Node.js and three-browser tests on Ubuntu, packs the tested checkout, and passes the artifact to the `npm` environment for publication. All CI and release jobs use `ubuntu-latest`; the browser suite covers Chromium, Firefox, and WebKit. Alpha releases select `alpha`; stable releases select `latest`. Never pass a custom dist-tag to bypass the release policy.
 
 ## Verify publication and recover
 
 ```bash
 npm view @drawmotive/textgraph dist-tags --json
-npm view @drawmotive/textgraph@0.2.0 dist.integrity
-npm install @drawmotive/textgraph@0.2.0
+npm view @drawmotive/textgraph@0.2.2-alpha.1 dist.integrity
+npm install @drawmotive/textgraph@0.2.2-alpha.1
 ```
 
 If a workflow fails before publishing, fix the configuration and rerun the same tag. For a manual dispatch, select the release tag as the workflow ref and supply the same tag as input; dispatching from `main` is rejected so OIDC and provenance identify the correct commit. For example:
 
 ```bash
-gh workflow run release.yml --ref textgraph-v0.2.0 -f tag=textgraph-v0.2.0
+gh workflow run release.yml --ref textgraph-v0.2.2-alpha.1 -f tag=textgraph-v0.2.2-alpha.1
 ```
 
 If publication succeeded but a later check failed, the script accepts an identical registry artifact with the correct channel and refuses different bytes at the same version. Keep the original workflow artifact for diagnosing integrity differences.
 
 The first alpha owning `latest` is expected and requires no repair. If a later publication unexpectedly changes an existing default, inspect registry state before retrying. Do not unpublish, overwrite versions, or delete tags as a routine recovery step.
+
+## Optional fonts package
+
+`.github/workflows/release-fonts.yml` publishes `@drawmotive/textgraph-fonts` from tags named `textgraph-fonts-v<VERSION>`. It verifies the coordinated release target, font hashes, Unicode coverage, pinned provenance, original license/notice hashes, offline installation, and publication policy before packing. The package has no native build or SDK dependency.
+
+Run these checks from the TextGraph repository after synchronizing the release target and package/lock versions in the parent repository:
+
+```bash
+npm ci --prefix language-packs --workspaces=false
+npm run build --prefix language-packs --workspaces=false
+npm test --prefix language-packs --workspaces=false
+node --test --test-concurrency=1 test/release.test.mjs test/fonts-release.test.mjs
+node scripts/fonts-release.mjs pack
+node scripts/publish-fonts-release.mjs --dry-run
+```
+
+The exact archive and receipt remain in `language-packs/.release/`; CI retains them as the `textgraph-fonts-npm-release` artifact for 30 days and passes them unchanged to the publish job. Font alpha releases use `alpha`, preserve an existing `latest`, and accept npm assigning `latest` on first publication. A retry verifies the existing version's integrity instead of publishing it again.
+
+Allow `textgraph-fonts-v*` tags in the GitHub `npm` environment. For bootstrap, an authorized administrator can set its `NPM_TOKEN` secret to an npm token with permission to create/publish this scoped package. The workflow writes only a token variable reference into a temporary npm configuration; it does not print or retain the credential in the artifact. Once the package exists, configure its trusted publisher with repository `drawmotive/textgraph`, workflow `release-fonts.yml`, and environment `npm`, then remove the bootstrap secret. Without that secret the workflow uses npm trusted publishing with OIDC.
+
+After committing and reviewing the release, publish the matching `textgraph-fonts-v<VERSION>` tag. Manual retries must use the same existing tag for both the workflow ref and the `tag` input. Publish the fonts package before refreshing consumer lockfiles; consumers must resolve the actual public registry tarball and integrity.

package/examples/service-flow.textgraph

@@ -0,0 +1,6 @@
+(horizontal)
+browser -> api -> database
+
+browser: Browser
+api(fill primary): API Gateway
+database: Database