@drawmotive/textgraph 0.2.1 → 0.2.2-alpha.2

package/README.md

@@ -1,140 +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.1
+npm install @drawmotive/textgraph@0.2.2-alpha.2
 ```
 
-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.1` defaults React PNG rendering to scale `1`, matching the base SDK. Version `0.2.0` was the first stable release. The exact installation command above becomes available after `0.2.1` is published; `@latest` selects the current published 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 `1`, padding `10`, and a white background. Reuse an instance for multiple diagrams, then call `dispose()`.
+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.
 
-## Higher resolution
-
-```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)
+
+## Render in a browser
 
-```typescript
+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",
-  scale: 2,
-  maxWidth: 1200,
-});
-
-if (result.success) {
-  const image = document.createElement("img");
-  image.src = `data:image/png;base64,${result.png}`;
-  image.alt = "A connects to B";
-  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);
+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();
 ```
 
-Scale `2` supplies more pixels for sharper web images; `displayWidth` and `displayHeight` keep the diagram at its logical size, including when `maxWidth` lowers the raster density. PNG DPI metadata does not control its CSS size. Older runtimes omit display dimensions; dividing pixel dimensions by the requested scale is a fallback that cannot recover logical size after `maxWidth` clamps the output.
+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.
 
-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.
+[Browser example →](https://github.com/drawmotive/textgraph/tree/main/samples/browser) ·
+[Worker example →](https://github.com/drawmotive/textgraph/tree/main/samples/worker)
 
-## React
+### Deploy the browser runtime
 
-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`:
+- 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`.
 
-```tsx
-import { TextGraph, TextGraphProvider } from "@drawmotive/textgraph/react";
+[Asset hosting and CSP →](https://github.com/drawmotive/textgraph/blob/main/docs/api-v1.md#assets-csp-and-offline-operation)
 
-const options = {
-  resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
-};
+## Validation and output options
 
-export function App() {
-  return (
-    <TextGraphProvider options={options}>
-      <TextGraph source={"A -> B"} alt="Flow diagram" />
-    </TextGraphProvider>
-  );
-}
+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,
+});
 ```
 
-The component defaults to scale `1`, displays at logical size, and shrinks to fit its container. Set `scale: 2` explicitly for higher raster density. 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

@@ -40,11 +40,42 @@ After applying `maxWidth`, output is limited to 16,384 pixels per side and 16,77
 
 ## 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
 
@@ -59,7 +90,7 @@ 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.
 
@@ -71,7 +102,9 @@ Keep this selection scoped to the development command. With it absent, package l
 
 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.
 
@@ -83,6 +116,13 @@ 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.

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
 

package/docs/releases.md

@@ -4,17 +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` (published) | `latest` | `npm install @drawmotive/textgraph` |
-| `0.2.1` (next target) | `latest` after publication | `npm install @drawmotive/textgraph@0.2.1` after publication |
+| `0.2.1` (stable) | `latest` | `npm install @drawmotive/textgraph@0.2.1` |
+| `0.2.2-alpha.2` (preview) | `alpha` | `npm install @drawmotive/textgraph@0.2.2-alpha.2` |
 
-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
 
@@ -36,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.1
+npm run release:textgraph -- 0.2.2-alpha.2
 ```
 
-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.1` 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.2` alias runs the same command.
 
 For a JavaScript-only release reusing already verified native bytes, run in this package:
 
@@ -83,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.1 -m "Release 0.2.1"
-git push origin textgraph-v0.2.1
+git tag -a textgraph-v0.2.2-alpha.2 -m "Release 0.2.2-alpha.2"
+git push origin textgraph-v0.2.2-alpha.2
 ```
 
-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.1 dist.integrity
-npm install @drawmotive/textgraph@0.2.1
+npm view @drawmotive/textgraph@0.2.2-alpha.2 dist.integrity
+npm install @drawmotive/textgraph@0.2.2-alpha.2
 ```
 
 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.1 -f tag=textgraph-v0.2.1
+gh workflow run release.yml --ref textgraph-v0.2.2-alpha.2 -f tag=textgraph-v0.2.2-alpha.2
 ```
 
 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