@drawmotive/textgraph 0.1.0-alpha.1 → 0.2.0

package/README.md

@@ -2,15 +2,18 @@
 
 Render TextGraph diagrams as PNG images and validate diagram source.
 
+> **[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.
+
 ## Installation
 
 ```bash
-npm install @drawmotive/textgraph@alpha
+npm install @drawmotive/textgraph@0.2.0
 ```
 
 Requires Node.js 22+ or a modern browser.
 
-Alpha releases require `@alpha` or an exact version such as `@0.1.0-alpha.1`. Once a stable release is available, `npm install @drawmotive/textgraph` installs the stable version.
+Version `0.2.0` is the first stable release. Install the exact version above or use `@latest` for the current stable release.
 
 ## Quickstart
 
@@ -46,10 +49,20 @@ const result = await textgraph.renderPng("A -> B", {
 
 ## Display in a browser
 
+For a bundled application, copy the runtime into its public directory before development or build:
+
+```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.
+
 ```typescript
 import { initializeTextGraph } from "@drawmotive/textgraph/browser";
 
-const textgraph = await initializeTextGraph();
+const textgraph = await initializeTextGraph({
+  resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
+});
 const result = await textgraph.renderPng("A -> B", {
   encoding: "base64",
   maxWidth: 1200,
@@ -65,17 +78,45 @@ if (result.success) {
 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.
+
+## React
+
+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`:
+
+```tsx
+import { TextGraph, TextGraphProvider } from "@drawmotive/textgraph/react";
+
+const options = {
+  resolveAsset: (asset) => new URL(`/textgraph/${asset.path}`, location.origin),
+};
+
+export function App() {
+  return (
+    <TextGraphProvider options={options}>
+      <TextGraph source={"A -> B"} alt="Flow diagram" />
+    </TextGraphProvider>
+  );
+}
+```
+
+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.
+
+## Runnable samples
+
+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.
+
 ## Additional languages
 
-Additional language packages are not yet published.
+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.
 
 ```bash
-npm install @drawmotive/textgraph-fonts-zh-cn
+npm install @drawmotive/textgraph-fonts
 ```
 
 ```typescript
 import { initializeTextGraph } from "@drawmotive/textgraph";
-import { zhCN } from "@drawmotive/textgraph-fonts-zh-cn";
+import { zhCN } from "@drawmotive/textgraph-fonts";
 
 const textgraph = await initializeTextGraph({ languagePacks: [zhCN] });
 const result = await textgraph.renderPng("A: 开始\nB: 完成\nA -> B");

package/docs/api-v1.md

@@ -42,7 +42,7 @@ Default rendering includes Noto Sans and Fuzzy Bubbles. Configure additional fon
 
 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.
 
-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. `@drawmotive/textgraph-fonts-zh-cn` exports a `zhCN` descriptor for Simplified Chinese. The optional package is installed separately.
+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.
 
 ## Lifecycle
 
@@ -57,6 +57,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`.
 
 Root condition precedence is worker/browser/node/default. Explicit entries avoid bundler ambiguity. Browser/Worker source graphs exclude Node imports.
 

package/docs/react.md

@@ -0,0 +1,52 @@
+# 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.
+
+## Browser assets
+
+Run `textgraph-copy-assets public/textgraph/wasm` in your application after installing the SDK, and again after updates. Put it in `predev` and `prebuild` scripts. Serve the public directory, then resolve assets to that URL:
+
+```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="Process flow"
+        renderOptions={{ scale: 2, maxWidth: 1200 }}
+        style={{ maxWidth: '100%', height: 'auto' }} />
+    </TextGraphProvider>
+  );
+}
+```
+
+For several diagrams, place a single provider around their common parent. Keep `options` stable using a module constant or `useMemo`; replacing it replaces the runtime, for example when changing language packs. Startup occurs only when a diagram mounts. StrictMode effect replay reuses startup, and final unmount disposes even an instance that is still initializing.
+
+`TextGraph` can run without a provider when the SDK's default package-relative URLs are served intact. Each standalone component owns its runtime. Bundled applications should use a provider with explicit asset resolution.
+
+Use your deployed base path instead of `/` for subdirectory hosting. The [React/Vite sample](https://github.com/drawmotive/textgraph/tree/main/samples/react-vite) demonstrates Vite's `BASE_URL`. No external CDN is needed. Assets follow the [SDK's MIME, CSP and offline requirements](api-v1.md#assets-csp-and-offline-operation); PNG data URLs need `img-src 'self' data:`.
+
+## Component behavior
+
+| Prop | Behavior |
+| --- | --- |
+| `source` | Required DSL string; changes trigger rendering. |
+| `alt` | Image description; defaults to `TextGraph diagram`. |
+| `renderOptions` | `scale`, `padding`, and `maxWidth`, with SDK defaults. |
+| `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.
+
+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
+
+The entry carries `'use client'`. Server rendering emits the same loading placeholder without starting WASM; the browser renders the diagram after hydration. In frameworks such as Next.js, place the provider and resolver function in your own client component, because functions cannot be passed across a server/client serialization boundary.
+
+To deliver a finished image in the initial HTML, call `@drawmotive/textgraph/node` during server/build work, persist the PNG, and render a normal `<img>` with its URL. That workflow does not load WASM in the reader's browser.

package/docs/releases.md

@@ -7,11 +7,13 @@ Releases are selected deliberately and published by `.github/workflows/release.y
 | Version | npm dist-tag | Installation |
 | --- | --- | --- |
 | `0.1.0-alpha.1` | `alpha` | `npm install @drawmotive/textgraph@alpha` |
-| `0.1.0` | `latest` | `npm install @drawmotive/textgraph` |
+| `0.2.0` | `latest` | `npm install @drawmotive/textgraph` |
 
-An exact prerelease version also works: `npm install @drawmotive/textgraph@0.1.0-alpha.1`. Alpha releases never change `latest`. Until a real stable version exists, default installation has no matching stable version and fails; no placeholder stable version is published. Versions are immutable. To graduate an alpha, prepare and publish a new stable version instead of moving `latest` to an alpha.
+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`.
 
-The scripts accept stable SemVer and `X.Y.Z-alpha.N`. Other channels require an explicit release-policy change. The Chinese font package has its own release lifecycle and is not published by this workflow.
+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.
 
 ## Account setup
 
@@ -20,6 +22,12 @@ The scripts accept stable SemVer and `X.Y.Z-alpha.N`. Other channels require an
 3. Once the npm package exists, open its Settings and add a GitHub Actions trusted publisher: owner `drawmotive`, repository `textgraph`, workflow filename `release.yml`, environment `npm`.
 4. The workflow uses a GitHub-hosted runner, Node.js 22, npm 11.11.1, and `id-token: write`. No long-lived npm token is needed for subsequent releases.
 
+The trusted publisher for `drawmotive/textgraph`, `release.yml`, and environment `npm` is configured. To configure the equivalent account setting from a terminal, use npm 11.15.0+ (the older CLI omits permissions required by the current API):
+
+```bash
+npm trust github @drawmotive/textgraph --repo drawmotive/textgraph --file release.yml --env npm --allow-publish --yes
+```
+
 Trusted publishing requires npm 11.5.1+ and Node.js 22.14.0+. Publication from a public repository automatically includes provenance. A private repository does not produce public npm provenance; repository visibility is a separate owner decision. See [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/).
 
 ## Prepare a version
@@ -27,15 +35,15 @@ 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.1.0-alpha.1
+npm run release:textgraph -- 0.2.0
 ```
 
-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.1.0-alpha.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.0` alias runs the same command.
 
 For a JavaScript-only release reusing already verified native bytes, run in this package:
 
 ```bash
-npm run release:prepare -- 0.1.0-alpha.2
+npm run release:prepare -- VERSION_MATCHING_RELEASE_TARGET
 npm run release:verify
 ```
 
@@ -59,7 +67,7 @@ Commit the package changes on the task branch, review them, and integrate accord
 
 ## First publication
 
-When the package does not exist yet, its trusted publisher may not be configurable. Bootstrap the verified release once from an authenticated terminal:
+When the package does not exist yet, its trusted publisher may not be configurable. Bootstrap the verified release once from an authenticated terminal; an initial alpha can also become the npm default:
 
 ```bash
 npm login --registry=https://registry.npmjs.org/
@@ -74,27 +82,26 @@ 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.1.0-alpha.2 -m "Release 0.1.0-alpha.2"
-git push origin main
-git push origin textgraph-v0.1.0-alpha.2
+git tag -a textgraph-v0.2.0 -m "Release 0.2.0"
+git push origin textgraph-v0.2.0
 ```
 
-The release workflow resolves the tag to a commit, runs the existing three-platform Node.js and three-browser tests, packs the tested checkout, and passes the artifact to the `npm` environment for publication. Stable releases use the same procedure with a version such as `0.1.0`; the script selects `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. Stable releases select `latest` automatically. 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.1.0-alpha.1 dist.integrity
-npm install @drawmotive/textgraph@0.1.0-alpha.1
+npm view @drawmotive/textgraph@0.2.0 dist.integrity
+npm install @drawmotive/textgraph@0.2.0
 ```
 
 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.1.0-alpha.1 -f tag=textgraph-v0.1.0-alpha.1
+gh workflow run release.yml --ref textgraph-v0.2.0 -f tag=textgraph-v0.2.0
 ```
 
 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.
 
-If an alpha accidentally acquires `latest` outside this workflow, restore the previously verified stable version using `npm dist-tag add @drawmotive/textgraph@<STABLE_VERSION> latest`. If no stable version exists, remove only the accidental tag using `npm dist-tag rm @drawmotive/textgraph latest`. Confirm registry state before retrying. Do not unpublish or overwrite versions as a routine recovery step.
+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.

package/generated/wasm/DrawMotive.TextGraph.Bridge.runtimeconfig.json

@@ -4,7 +4,7 @@
     "includedFrameworks": [
       {
         "name": "Microsoft.NETCore.App",
-        "version": "10.0.8"
+        "version": "10.0.12"
       }
     ],
     "wasmHostProperties": {