flowsvg 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.1 - 2026-10-20
+
+- Adopted thin neutral node borders, gray edges and blue emphasis in both themes. Separate highlight fills from borders and flow markers, remove the node-label halo, and refresh README previews.
+
+- Expanded the quick-start document to a six-node order workflow with authorization, persistence, asynchronous events and reverse responses.
+
+- Added SDK-rendered previews beside the quick-start, structured-content, list, entity-graph and Facts timeline examples in both package READMEs.
+
+- Include the eight README preview images in the npm tarball. Source READMEs use relative image paths for local previews; the release verifier prepares staged README copies with versioned npm CDN URLs for public readers. Release verification requires every preview and rejects undeclared documentation assets.
+
+- Removed local build, source-layout and release instructions from the package READMEs; repository documentation retains the contributor workflow.
+
+- Completed bilingual module navigation, updated migrated test links, and consolidated architecture implementation and verification records.
+
+- Grouped React, Vue, and Web Component implementations under `src/adapters/` while keeping explicit root entries, shared Web Component registration identity, SSR-safe imports, lifecycle behavior, and cross-host integration tests. Updated nested release artifacts and consumer references.
+
+- Grouped the browser player implementation and its controls, accessibility, lifecycle, and SVG DOM modules under `src/browser/` while preserving the `flowsvg/browser` entry, lifecycle behavior, DOM-free imports, and public player contract. Updated browser tests and release allowlists for nested build output.
+
+- Moved shared hexadecimal color interpolation to the pure `src/core/color.ts` module. Timeline evaluation and diagram paint share the same runtime helper; content painting checks contrast without a timeline dependency.
+
+- Centralized edge routing, path sampling, distance queries, label anchors, hit testing, and SVG number formatting in `src/core/edge-geometry.ts` and `src/core/svg-number.ts` while preserving the existing public frames and SVG output.
+
+- Organized the platform-independent core into shared model, document validation and diagram orchestration modules. Preserved all public values/types, error identity and evaluation behavior; grouped core tests with their implementation.
+- Preserved nested JavaScript and declaration build output and replaced the release file pattern with an explicit module allowlist that rejects source, tests and unrelated files.
+
 ## 0.1.0 - 2026-10-17
 
 - Added a release CLI that runs type checks, SDK and release-script tests, tarball consumer verification, example builds and npm publication preview. Default to preview; require `--publish` for upload, and publish the exact verified tarball retained in `dist/releases/`.
@@ -9,7 +34,7 @@
 - Prepared the first npm release with repository metadata, public registry settings, bilingual package documentation, automatic prepack builds and prepublish type/test checks.
 - Verify packaging from a missing `dist`, every exported JavaScript/type/CSS target, the file allowlist, framework-free imports, strict consumer types and all four host lifecycles.
 
-- Renamed the package and SDK directory to `flowsvg` (流形). Player exports now use the `Flow` prefix: `FlowPlayer`, `FlowPlayerProps`, `FlowPlayerHandle`, `FlowPlayerElement`, `defineFlowPlayer()` and `FLOW_PLAYER_TAG`. The default element is `<flowsvg-player>`; CSS classes and control variables use `flowsvg-` and `--flowsvg-`. Imports, selectors and public API references must use the new names.
+- Renamed the package and SDK directory to `flowsvg`. Player exports now use the `Flow` prefix: `FlowPlayer`, `FlowPlayerProps`, `FlowPlayerHandle`, `FlowPlayerElement`, `defineFlowPlayer()` and `FLOW_PLAYER_TAG`. The default element is `<flowsvg-player>`; CSS classes and control variables use `flowsvg-` and `--flowsvg-`. Imports, selectors and public API references must use the new names.
 
 - Fixed cylinder SVG fills by rendering the top cap as a separate filled ellipse inside the same node interaction group, so the cap no longer appears hollow.
 

package/PATTERNS.md

@@ -1,12 +1,23 @@
 # Patterns
 
+- Keep default diagram colors and line metrics in the core theme. Use separate highlight fill, border/marker and marker-text colors so active nodes retain readable text in both themes. Browser hover consumes the same theme values; preserve border-only hover by default. Node labels have no halo; edge labels retain background isolation where paths cross text.
+
+- Keep README previews in `docs/images/` inside the SDK package. Package only PNG assets and enumerate the expected images in the release verifier; require each image and reject undeclared files. Use relative image paths in source READMEs for local previews. The release verifier unpacks the built package into a temporary directory and converts only its README copies to npm CDN URLs with the package version. Repack without lifecycle scripts, require the packed file set to remain unchanged, then verify and retain that final tarball. Source READMEs must remain unchanged by release verification.
+
+- Keep shared document/frame types in `src/core/model.ts`, document validation and its single error class in `validation.ts`, and compilation, cloning/freezing, evaluation, SVG and hit-test orchestration in `diagram.ts`. Node-content types and nested validation remain in `node-content.ts`. Import runtime owners directly; use type imports for shared model dependencies.
+- Enumerate public values and types in the root entry, including `wrapText`, `Diagram` and all node-content types. Keep core contract tests in `src/core/` and consume public entries. Four entry-specific TypeScript builds preserve the internal directory hierarchy under `dist`; enumerate each emitted module in the release allowlist instead of accepting arbitrary files below `dist`.
+- Keep the browser player implementation under `src/browser/player.ts`, with controls, accessibility, lifecycle, and SVG DOM synchronization beside it. Keep `src/browser.ts` as the explicit public entry; browser tests use that entry while core remains DOM-free.
+- Keep React, Vue, and Web Component implementations under `src/adapters/`; root adapter files are explicit public entries that export the single implementation and preserve runtime identity. Adapter tests live beside their implementations and cross-host business scenarios live under `tests/integration/`; imports use public entries.
+- Keep color interpolation in the pure `src/core/color.ts` module. Timeline and diagram painting import it directly so generic color rules do not depend on timeline semantics. Content highlight paint retains theme-specific semantic colors and adjusts default ink only when the evaluated fill requires more contrast.
+- Keep route construction, path measurements, label anchors, and path hit testing in `src/core/edge-geometry.ts`; share integer and three-decimal formatting through `src/core/svg-number.ts`. Diagram orchestration consumes these internal results without exposing geometry.
+
 - Run release gates sequentially through the root release CLI. Default to a preview without authentication; check authentication before the gates only for explicit publication. Copy the verified tarball after all consumer checks pass, then preview and publish that file without repacking. Stop on any command failure and keep npm stdio attached for authentication prompts.
 
 - Build Vue declarations against the pinned minimum supported version, 3.5.0; newer Vue patch releases can add inferred `DefineComponent` type parameters that older consumers cannot read. Verify both minimum and current framework versions in the packed-package consumer.
 
 - Build through `prepack` so `npm pack` and directory publishing cannot use missing or stale artifacts. Keep publish-only type/test checks separate from packaging to avoid recursive release verification. Verify the packed exports and strict consumer types before publishing.
 
-- Publish the SDK as `flowsvg` from `packages/flowsvg`. Use the `Flow` prefix for player exports, `<flowsvg-player>` for the default custom element, and `flowsvg-` / `--flowsvg-` for CSS classes and control variables. Keep package imports, declarations, examples and release verification aligned with these names.
+- Use FlowSVG as the display name. Publish the SDK as `flowsvg` from `packages/flowsvg`. Use the `Flow` prefix for player exports, `<flowsvg-player>` for the default custom element, and `flowsvg-` / `--flowsvg-` for CSS classes and control variables. Keep package imports, declarations, examples and release verification aligned with these names.
 
 - Apply hover to stroke only by default for every node and group. Preserve core fill and content paint, including active flow or explicit highlights. With `hoverFill: true`, paint fill and readable content as well. Forward the same option through every adapter and restore the current core SVG when the pointer leaves.
 

package/README.md

@@ -1,12 +1,12 @@
-# flowsvg
+# FlowSVG
 
 English | [简体中文](README.zh-CN.md)
 
-flowsvg (流形) is a TypeScript ESM SDK for declarative SVG diagram playback. Describe logic and architecture diagrams with nodes, edges, scenes, and beats in JSON or TypeScript objects, then play the diagram in a browser or export an SVG at a specific time without a DOM.
+FlowSVG plays logic and architecture diagrams with SVG. Define nodes, edges, scenes, and beats in JSON or TypeScript, then play them in a browser or export a static SVG.
 
-The core handles validation, time evaluation, geometry, and SVG output. Browser and framework adapters handle playback, interaction, and lifecycle. The same document, time, and visual options produce the same core frame. Node hover adds temporary browser feedback.
+The ESM SDK includes a DOM-free core and native browser, Vue, React, and Web Component integrations. All integrations share the same document and timeline.
 
-[Installation](#installation) · [Quick start](#quick-start) · [Vue](#vue-integration) · [React](#react-integration) · [Native browser](#native-browser) · [Web Component](#web-component) · [API](#api) · [Development](#development-and-verification) · [License](#license)
+[Installation](#installation) · [Quick start](#quick-start) · [Vue](#vue-integration) · [React](#react-integration) · [Native browser](#native-browser) · [Web Component](#web-component) · [API](#api) · [License](#license)
 
 ## Installation
 
@@ -27,16 +27,7 @@ pnpm add react react-dom
 pnpm add -D @types/react @types/react-dom
 ```
 
-The core and native browser entries require neither framework. To build a local tarball before publication, run from the repository root:
-
-```sh
-pnpm install --frozen-lockfile
-pnpm --filter flowsvg exec npm pack --pack-destination /tmp
-```
-
-The packaging hook builds the SDK. Install the resulting `0.1.0` tarball with `pnpm add /tmp/flowsvg-0.1.0.tgz`.
-
-The core requires Node.js 18+ or an environment supporting ES2022 ESM. Browser playback requires a DOM, SVG, and `requestAnimationFrame`. Minimum framework versions are Vue 3.5 and React 18. TypeScript declarations are included; React TypeScript applications also need the matching `@types/react` and `@types/react-dom` packages.
+The core and native browser entries need no framework. TypeScript declarations are included. Core: Node.js 18+ or ES2022 ESM. Browser: DOM, SVG, and `requestAnimationFrame`. Frameworks: Vue 3.5+ or React 18+.
 
 | Import path | Purpose |
 | --- | --- |
@@ -51,31 +42,63 @@ The core requires Node.js 18+ or an environment supporting ES2022 ESM. Browser p
 
 ### 1. Create a diagram document
 
-Save this as `diagram.ts`. The integration examples below reuse this file:
+Save this as `diagram.ts`. This 5.2-second example uses six nodes, three scenes and five beats. It separates authorization, order persistence, and the final response with an asynchronous event. The integration examples below reuse this file:
 
 ```ts
 import type { DiagramDocument } from "flowsvg";
 
 export const diagramDocument: DiagramDocument = {
   version: 1,
-  title: "Request flow",
-  viewport: { width: 640, height: 280 },
+  title: "Order request lifecycle",
+  viewport: { width: 960, height: 440 },
   nodes: [
-    { id: "client", kind: "roundedRect", x: 40, y: 100, width: 140, height: 80, label: "Client" },
-    { id: "service", kind: "rect", x: 420, y: 100, width: 160, height: 80, label: "Service", visible: false }
+    { id: "client", kind: "roundedRect", x: 40, y: 205, width: 120, height: 70, label: "Client" },
+    { id: "gateway", kind: "roundedRect", x: 260, y: 205, width: 130, height: 70, label: "API gateway" },
+    { id: "auth", kind: "ellipse", x: 260, y: 40, width: 130, height: 72, label: "Auth" },
+    { id: "orders", kind: "roundedRect", x: 500, y: 205, width: 150, height: 70, label: "Order service" },
+    { id: "database", kind: "cylinder", x: 780, y: 65, width: 140, height: 90, label: "Orders" },
+    { id: "events", kind: "rect", x: 780, y: 330, width: 140, height: 70, label: "Event queue" }
   ],
-  edges: [{ id: "request", from: "client", to: "service", label: "HTTP", route: "straight" }],
-  scenes: [{
-    id: "request-flow",
-    label: "Request reaches the service",
-    beats: [
-      { durationMs: 1000, transitionMs: 250, caption: "Show the service", actions: [{ type: "show", target: "service" }] },
-      { durationMs: 1000, caption: "The service handles the request", actions: [{ type: "highlight", target: "service" }] }
-    ]
-  }]
+  edges: [
+    { id: "request", from: "client", to: "gateway", route: "straight" },
+    { id: "authorize", from: "gateway", to: "auth", route: "straight", fromPort: "top", toPort: "bottom" },
+    { id: "create", from: "gateway", to: "orders", route: "straight" },
+    { id: "persist", from: "orders", to: "database", route: "orthogonal", fromPort: "right", toPort: "left" },
+    { id: "publish", from: "orders", to: "events", route: "curved", fromPort: "bottom", toPort: "left" },
+    { id: "result", from: "orders", to: "gateway", route: "curved", fromPort: "bottom", toPort: "bottom" }
+  ],
+  scenes: [
+    { id: "request", label: "Receive and authorize", beats: [
+      { durationMs: 800, caption: "Receive the order request", actions: [
+        { type: "flow", target: "request", direction: "forward", text: "POST" }
+      ] },
+      { durationMs: 800, caption: "Validate the access token", actions: [
+        { type: "flow", target: "authorize", direction: "forward", text: "Token" }
+      ] }
+    ] },
+    { id: "create-order", label: "Create the order", beats: [
+      { durationMs: 1000, caption: "Send the authorized request to the order service", actions: [
+        { type: "flow", target: "create", direction: "forward", text: "Create" }
+      ] },
+      { durationMs: 1000, caption: "Persist the new order", actions: [
+        { type: "flow", target: "persist", direction: "forward", text: "INSERT" }
+      ] }
+    ] },
+    { id: "response", label: "Publish and respond", beats: [
+      { durationMs: 1600, caption: "Publish OrderCreated and return the order number", actions: [
+        { type: "flow", target: "publish", direction: "forward", text: "OrderCreated" },
+        { type: "flow", target: "result", direction: "forward", text: "201 Created" },
+        { type: "flow", target: "request", direction: "reverse", text: "Order ID" }
+      ] }
+    ] }
+  ]
 };
 ```
 
+At 4400 ms with the light theme, the event and response messages move together. Only their participating nodes are highlighted.
+
+![Order workflow with Client, API gateway, Auth, Order service, Orders database and Event queue; OrderCreated and response messages are in flight](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/quick-start.png)
+
 ### 2. Evaluate and export SVG
 
 ```ts
@@ -87,10 +110,10 @@ const frame = diagram.evaluateAt(125);
 console.log(diagram.totalDuration, frame.sceneId, frame.warnings);
 
 const svg = diagram.renderSvg(125, { theme: "dark" });
-const finalSvg = renderSvg(diagramDocument, 2000);
+const finalSvg = renderSvg(diagramDocument, 5200);
 ```
 
-`svg` and `finalSvg` are complete static SVG strings, ready to save to a file or preview. Reuse the result of `createDiagram` for repeated queries; use `renderSvg` for a single export. Choose one of the integrations below for browser playback.
+Both results are static SVG strings. Reuse `createDiagram` for repeated queries; use `renderSvg` for a single export.
 
 ## Vue integration
 
@@ -127,7 +150,7 @@ function handleError({ error }: PlayerErrorDetail): void {
 </template>
 ```
 
-The component destroys the player on unmount. Use `player.value` to call handle methods in script; templates unwrap the ref automatically. Events are `stepchange`, `timeupdate`, `playstatechange`, and `error`, with the event detail passed directly as the argument. Corresponding callback props are also available.
+Unmounting destroys the player. In scripts, call methods through `player.value`; templates unwrap the ref. Events pass their detail directly: `stepchange`, `timeupdate`, `playstatechange`, and `error`. Callback props are also supported.
 
 ## React integration
 
@@ -171,9 +194,9 @@ The component releases resources on unmount. Callbacks are `onStepChange`, `onTi
 | `initialTimeMs` | Applied only on initial mount; use `seek` for later changes |
 | `className` / `style` | Host container styles |
 
-Changing `theme`, `controls`, `reducedMotion`, or `hoverFill` recreates the player, paused at zero; `initialTimeMs` is not reapplied. Provide a new object reference when changing the document. The ref / exposed handle provides the seven control and state methods in the Player API below; the component owns cleanup. Calling a retained handle before mounting or after unmounting throws a not-mounted error.
+Changing `theme`, `controls`, `reducedMotion`, or `hoverFill` recreates the player, paused at zero, without reapplying `initialTimeMs`. Reload documents with a new object reference. Handles expose seven methods listed under [Player API](#player-api); calls before mount or after unmount throw.
 
-Both framework entries are safe to import on the server. SSR renders a host container, and the player is created after client mounting. Use the core `renderSvg` for a server-rendered diagram preview.
+Both entries support server-side imports. SSR renders a container; the player is created on client mount. Use `renderSvg` for server-side diagram previews.
 
 ## Native browser
 
@@ -197,11 +220,9 @@ const player = createPlayer(host, diagramDocument, { theme: "light" });
 player.play();
 ```
 
-`createPlayer` takes over the container and replaces its children. Call `player.destroy()` when the page or component is disposed, and destroy the old instance before creating another player in the same container. Bare imports in plain HTML need an import map or application build tooling; the repository's native example includes an import map.
+`createPlayer` replaces the container children. Call `destroy()` on disposal and before reusing the container. Plain HTML requires an import map or build tooling for package imports.
 
-The repository example at `apps/native-example/` keeps the camera and layout fixed throughout an order request and response. At 0–2400 ms, three curved edges carry a dot, a `Token` capsule, and a reverse precheck capsule. At 2400–4800 ms, two other curves carry the order request and inventory confirmation. At 4800–7200 ms, response messages return to the gateway and client; the final beat ends at 8200 ms with no temporary highlights. Opposite relationship edges remain separate, and hovering a participant adds only a browser highlight.
-
-Reuse `apps/native-example/request-chain.js` as the `document` input for native, Web Component, React, or Vue integration. Each host uses the same `seek(timeMs)`, `setSpeed(speed)`, `play()`, and `pause()` behavior. `src/business-integration.test.ts` verifies this shared example through all four public entries, including both themes, reduced motion, beat boundaries, and core SVG equality.
+The [native example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/README.md) demonstrates request/response flows. Its shared document also works with the other three integrations.
 
 ## Web Component
 
@@ -221,13 +242,13 @@ const element = document.querySelector<FlowPlayerElement>("flowsvg-player");
 if (element) element.document = diagramDocument;
 ```
 
-The default element name is `flowsvg-player`; repeated registration is safe. Pass objects through the `document` property. The HTML `document` attribute accepts a JSON string; `src` accepts a JSON URL resolved relative to the page. URL requests follow browser same-origin and CORS rules.
+Registration defaults to `<flowsvg-player>` and is idempotent. Assign objects to `element.document`, JSON strings to the HTML `document` attribute, or a JSON URL to `src`. URLs resolve against the page and follow browser CORS rules.
 
-Supported options are `autoplay`, `controls`, `speed`, `theme`, `reduced-motion`, and `hover-fill`. Hover fill is off by default; set `hover-fill` to enable background and content feedback. Use `controls="false"` to hide the controls, which are visible by default. Autoplay is off by default. Option changes preserve the current time and playing/paused state. Removing the element cleans up the player and pending requests; reconnecting can mount it again from its retained document.
+Attributes: `autoplay`, `controls`, `speed`, `theme`, `reduced-motion`, and `hover-fill`. Controls default on; autoplay and hover fill default off. Use `controls="false"` to hide controls. Changes to theme, controls, or motion/hover options preserve time and playback state; `autoplay` explicitly starts or pauses playback. Removal cancels requests and destroys the player; reconnection uses the retained document.
 
-The element exposes `play`, `pause`, `seek`, `step`, `setSpeed`, `getState`, and `destroy`. Replace the document through the `document` property. Before mounting, `getState()` returns `undefined`. The element forwards the four playback/error event types as bubbling, composed CustomEvents that can cross Shadow DOM boundaries.
+Methods: `play`, `pause`, `seek`, `step`, `setSpeed`, `getState`, and `destroy`. Update documents through `element.document`. Before mount or after destruction, `getState()` returns `undefined`. Playback/error events bubble across Shadow DOM boundaries.
 
-Load this entry in a DOM environment for actual registration. Importing without a DOM is safe, but module evaluation fixes the HTMLElement base class; the same module instance imported without a DOM cannot register directly after a DOM is added later.
+Register in a DOM environment. DOM-free imports are safe, but that module instance cannot register after a DOM is added later.
 
 ## Documents and timelines
 
@@ -240,17 +261,19 @@ Load this entry in a DOM environment for actual registration. Importing without
 | `scenes` | `[]` creates a static diagram; each scene has a unique `id`, a `label`, and nonempty `beats` |
 | `title` / `theme` | Optional title and `light` / `dark` document theme |
 
-Node and edge IDs are globally unique. Node shapes are `rect`, `roundedRect`, `ellipse`, `cylinder`, and `group`. A node's `parentId` references its parent group; child coordinates are relative to the group origin. Labels are plain text; `visible` defaults to `true`. Node `style` supports `fill`, `stroke`, `strokeWidth`, `textColor`, and `dashed` (used for group borders); edge `style` supports `stroke`, `strokeWidth`, and `dashed`. Colors use hexadecimal RGB/RGBA, such as `#2563eb` or `#2563eb80`.
+Node and edge IDs are globally unique. Shapes: `rect`, `roundedRect`, `ellipse`, `cylinder`, `group`. `parentId` names a parent group; child coordinates are group-relative. Labels are plain text; `visible` defaults to `true`. Node styles: `fill`, `stroke`, `strokeWidth`, `textColor`, `dashed` (group borders). Edge styles: `stroke`, `strokeWidth`, `dashed`. Colors use hexadecimal RGB/RGBA, such as `#2563eb` or `#2563eb80`.
 
-Edge `route` is `straight` by default, `orthogonal`, or `curved`. Curved routes are smooth cubic paths generated from endpoint ports; they do not auto-avoid other nodes. Orthogonal paths avoid visible ordinary nodes, with a deterministic fallback when no route is found; shortest paths and zero crossings are not guaranteed. Use `fromPort` and `toPort` (`top`, `right`, `bottom`, or `left`) when a specific side is required. Explicit orthogonal ports reserve outward endpoint segments and route around endpoint bodies; curved ports set endpoint tangents. Omitted ports are selected from the dominant center-to-center axis, and ellipse ports use the ellipse contour. Simple labels wrap using deterministic width estimates. Insufficient node height preserves the full label and emits a `text-overflow` warning.
+Routes: `straight` (default), `orthogonal`, or `curved`. Curves follow endpoint ports without avoiding other nodes. Orthogonal routes avoid visible ordinary nodes and use a fixed fallback if blocked; shortest paths and zero crossings are not guaranteed. Set `fromPort` / `toPort` to `top`, `right`, `bottom`, or `left`. Explicit orthogonal ports reserve outward endpoint segments; curved ports set tangents. Omitted ports follow the dominant center-to-center axis; ellipse endpoints lie on the contour. Simple labels wrap by estimated width and remain visible on height overflow, with a `text-overflow` warning.
 
-Edges may connect ordinary nodes, groups, or one of each. A group endpoint uses the evaluated group rectangle, including nested movement and explicit ports. Hiding an endpoint group or its ancestor masks the edge. A transfer highlights the endpoint group itself; descendants keep their own highlight state. Group frames remain excluded from routing obstacles.
+Edges can connect nodes or group boundaries. Group endpoints follow evaluated geometry and explicit ports. Hidden ancestors mask connected edges. Transfers highlight the endpoint group, not its descendants. Group frames are excluded from routing obstacles.
 
 ### Fixed-size node content
 
-A `rect`, `roundedRect`, or `cylinder` node may declare `content` instead of `label`. Ellipses and groups accept simple labels only. Declaring both fields, including an empty label, is invalid. `content.blocks` is an ordered array of `title`, `paragraph`, `list` and `graph` blocks. Paragraph `role` is `body` (default) or `auxiliary`. An empty block array displays only the shape. Import the `DiagramNode` type from `flowsvg` for this example:
+`rect`, `roundedRect`, and `cylinder` support `content`; ellipses and groups support labels only. `content` and `label` are mutually exclusive, even with an empty label. `content.blocks` contains ordered `title`, `paragraph`, `list`, or `graph` blocks. Paragraph roles are `body` (default) and `auxiliary`. An empty block array displays only the shape.
 
 ```ts
+import type { DiagramNode } from "flowsvg";
+
 const service = {
   id: "service", kind: "rect", x: 24, y: 24, width: 260, height: 312,
   content: {
@@ -265,40 +288,55 @@ const service = {
 } satisfies DiagramNode;
 ```
 
-Title/paragraph `text` and list-item `body`/`auxiliary`/`status`/tag `text` accept a string or `ContentTextSpan[]`. Each span is `{ text, style?: { fontSize, fontWeight, color } }`; alignment stays on the block. For example: `text: [{ text: "Saved", style: { fontWeight: 700 } }, { text: " 2026-10-17", style: { fontSize: 12 } }]`. Spans inherit block defaults and share each line's baseline. Line height uses that line's largest font, and style boundaries do not force line breaks. Wrapping prefers English spaces, then breaks CJK, long words and URLs between graphemes. `Intl.Segmenter` preserves combining accents, skin-tone emoji, ZWJ sequences, flags and keycaps. A grapheme crossing source spans uses its first character's style. Layout does not read DOM measurements or font-loading state.
+The `service` node rendered with the light theme:
 
-Each block accepts `style.fontSize` (finite and positive), `fontWeight` (integer 100–900), hexadecimal `color`, and `align` (`left`, `center`, `right`). Content style accepts nonnegative finite `padding` and `blockGap`. Sizes and spacing use diagram units. Defaults are title 20/700, body 14/400, auxiliary 12/400, padding 16, block gap 14, and line height at least 20 or font size × 1.35. Auxiliary text uses a muted theme color; explicit content colors retain their authored values.
+![Fixed-size Order service node with title, auxiliary text, body and a blue right-aligned paragraph](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/node-content.png)
 
-A list is `{ type: "list", marker?: "none" | "bullet" | "number", items: ContentListItem[], style?: ContentListStyle }`. The default marker is `none`. Each item accepts optional `tags`, `status`, `body`, `auxiliary`, body `style`, `auxiliaryStyle`, and `statusStyle`. List `style` supplies body typography and a nonnegative finite `itemGap` (default 12). Item body styles override the list's body styles; auxiliary text keeps its muted 12-unit defaults unless `auxiliaryStyle` overrides them. Marked lists reserve one common marker column, including multi-digit numbers, then an 8-unit gap. Body continuation lines and auxiliary text use the same body column. Markers align with the first present text part's baseline. Absent parts and completely absent entries consume no height or item gap; explicit empty strings and blank lines still consume authored lines. For example:
+Text fields accept strings or `ContentTextSpan[]`: `{ text, style?: { fontSize, fontWeight, color } }`. Spans inherit block styles and share a baseline; alignment belongs to the block. Each line uses its largest font. Wrapping preserves newlines and Unicode graphemes, prefers English spaces, and breaks long words/URLs as needed. A grapheme spanning source styles uses its first character’s style. Layout uses width estimates, without DOM measurement.
+
+Text styles: positive finite `fontSize`, integer `fontWeight` from 100–900, hexadecimal `color`, and `align` (`left`, `center`, `right`). Content `padding` and `blockGap` are finite and nonnegative. Defaults in diagram units: title 20/700, body 14/400, auxiliary 12/400, padding 16, block gap 14. Line height is `max(20, fontSize × 1.35)`. Explicit colors override theme defaults.
+
+Lists accept `marker` (`none` by default, `bullet`, or `number`), `items`, and `style`. Items support `tags`, `status`, `body`, `auxiliary`, `style`, `auxiliaryStyle`, and `statusStyle`. List style sets body typography and nonnegative finite `itemGap` (default 12); item body style overrides it. Auxiliary text defaults to muted 12-unit text. Markers share a column followed by an 8-unit gap; continuation and auxiliary lines align with the body. Markers use the first present text baseline. Omitted items/parts take no space; explicit blank text preserves a line.
 
 ```ts
-{ type: "list", marker: "number", style: { itemGap: 16 }, items: [
+import type { ContentBlock } from "flowsvg";
+
+const steps: ContentBlock = { type: "list", marker: "number", style: { itemGap: 16 }, items: [
   { body: "Validate the request.", auxiliary: "Input checks" },
   { body: [{ text: "Save", style: { fontWeight: 700 } }, { text: " the order." }] }
-] }
+] };
 ```
 
-Tags use `{ text: ContentText, style?: { fontSize, fontWeight, color, fill } }`. Tag font size defaults to 11; each background reserves 6 units on each horizontal side and 2 on each vertical side, with a 3-unit corner radius. List `style.tagGap` is finite and nonnegative (default 6), separating tags, tag rows and same-row status. Tags use theme background/text colors unless explicitly overridden. Status defaults to 12-unit theme accent text; `statusStyle` accepts only `fontSize`, `fontWeight`, and `color`, and status remains right-aligned. A single tag row shares a baseline with a single-line status when their natural widths fit. Otherwise tags wrap first and status starts below all tags. Long tags and status use the same mixed-style grapheme wrapping. Body follows the metadata row(s), then auxiliary text. Omitted parts reserve no space. For example:
+The `steps` block rendered in a 300 × 180 rectangle with `content: { blocks: [steps] }`:
+
+![Two numbered steps with auxiliary text and bold Save text](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/numbered-list.png)
+
+Tags accept `{ text, style?: { fontSize, fontWeight, color, fill } }`. Defaults: font size 11, padding 6 horizontal / 2 vertical, corner radius 3. List `tagGap` defaults to 6 and must be finite and nonnegative. Status is right-aligned, defaults to 12-unit accent text, and accepts `fontSize`, `fontWeight`, and `color` in `statusStyle`. Tags and status share a baseline when they fit; otherwise tags wrap first and status moves below. Body and auxiliary text follow. Explicit colors/fills override the theme.
 
 ```ts
-{ type: "list", items: [{
+import type { ContentBlock } from "flowsvg";
+
+const records: ContentBlock = { type: "list", items: [{
   tags: [{ text: "world" }, { text: "experience", style: { fill: "#eadfff", color: "#57319b" } }],
   status: "new", body: "Alice joined Google", auxiliary: "Mar 2026"
-}] }
+}] };
 ```
 
-Node dimensions stay fixed. Rectangles apply the authored padding. Rounded rectangles reserve an additional 4 units on each side before padding. Cylinders reserve twice the current cap radius above and below content before padding; the cap radius is `min(14, height / 4)`. The safe area has nonnegative dimensions, including when shape clearance and padding consume the entire node. Content starts at the top of its safe area and wraps using deterministic width estimates. Explicit line endings and blank lines are preserved. SVG clips text to the safe area. Insufficient width or height emits a separate `text-overflow` warning with the node ID, `nodes[index].content` path, and direction. Empty safe areas remain valid. Clipped text does not extend node hit bounds. Simple labels retain their existing overflow behavior.
+The `records` block rendered in a 300 × 180 rectangle with `content: { blocks: [records] }`:
 
-`EvaluatedNode.contentLayout` exposes `safeArea`, ordered `lines`, tag backgrounds `tags`, `widthOverflow`, and `heightOverflow`. Each line provides text, baseline coordinates, estimated width, typography, alignment, semantic role (`title`, `body`, `auxiliary`, `marker`, `tag` or `status`), source `blockIndex`, and optional list `itemIndex`. Tag lines also expose `tagIndex`. Each tag background provides absolute `x`, `y`, `width`, `height`, resolved `fill`, author provenance `explicitFill`, and source `blockIndex`/`itemIndex`/`tagIndex`. Each line's `spans` provide text, absolute left coordinates, shared baseline, estimated width, and resolved typography/color. `explicitColor` records whether the block or source span supplied its color. The same values drive browser SVG and static export. Content follows current absolute geometry, including interpolated dimensions and parent-group movement, ancestor visibility, and effective opacity. Content does not change ports, edge routes, transfer geometry, or node-parent rules. See the runnable [title and paragraph example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/node-content.html) and [list example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/list-content.html).
+![Record with world and experience tags, new status, body and date](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/record-tags.png)
 
-All three content shapes support initial content, styled spans, lists and timeline replacement. Tags, status and readable default colors under explicit, flow and hover highlights are supported.
+Content keeps authored node dimensions. Safe areas reserve padding plus 4 units per side for rounded rectangles, or twice the cylinder cap radius above/below (`min(14, height / 4)`). Dimensions clamp to zero. SVG clips content to this area; width/height overflow emits `text-overflow` with node ID, `nodes[index].content`, and direction. Clipped text adds no hit area. Simple labels retain their separate overflow behavior.
 
+`EvaluatedNode.contentLayout` provides the safe area, lines/spans, tag backgrounds, optional graph primitives, and width/height overflow flags. Geometry is absolute and follows node resizing, parent movement, visibility, and opacity. Lines retain source block/item/tag indexes; `explicitColor` and `explicitFill` identify authored paint. Browser rendering and SVG export use the same layout. Content does not change ports, routes, transfer geometry, or parent relationships. See the [paragraph](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/node-content.html) and [list](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/list-content.html) examples.
 
 ### Entity graphs inside nodes
 
-A `graph` block draws a small, undirected entity graph inside any supported content shape. Authors specify local coordinates; the SDK does not arrange entities automatically. Use `ContentGraphBlock` from `flowsvg`:
+A `graph` block draws an undirected entity graph with authored local coordinates:
 
 ```ts
+import type { ContentGraphBlock } from "flowsvg";
+
 const entities: ContentGraphBlock = {
   type: "graph", height: 130,
   nodes: [
@@ -310,13 +348,17 @@ const entities: ContentGraphBlock = {
 };
 ```
 
-`height` is positive and reserves a fixed vertical section, followed by the ordinary block gap. Entity centers `x`/`y` are nonnegative finite offsets from the section's top-left corner in diagram units. IDs must be unique within each graph block; each relation references two local IDs. Labels use escaped plain text at 12 units, centered above 4-unit dots. Selected entities use accent dots and bold labels; a relation uses accent paint when both endpoints are selected. Text and primitives share the parent content clip and theme/highlight paint. Coordinates or labels outside the graph section produce directional overflow warnings without moving the following block. Leave enough room above each dot for its label. Entities remain decorative: clicking or hovering them targets the parent node.
+The `entities` block rendered in a 280 × 180 rectangle with `content: { blocks: [entities] }`:
+
+![Entity graph with highlighted Alice and Google, and an unselected ML project](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/entity-graph.png)
 
-`contentLayout.graphs`, when present, provides absolute circle/line geometry, local `highlighted` state and resolved colors per `blockIndex`. Graph labels join `contentLayout.lines`. Replace the complete `content` at a beat start to change local selections. The [complete Hindsight example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/hindsight.html) demonstrates all three acts and 25 beats, including group endpoints and changing entity selections.
+`height` reserves a positive fixed section. Entity centers use nonnegative finite `x`/`y` offsets from its top-left. IDs are local to each block; edges reference those IDs. Labels are 12-unit plain text above radius-4 dots. Highlighted entities use accent dots and bold labels; an edge uses accent paint when both endpoints are highlighted. Overflow reports its direction without shifting later blocks. Graphs share the parent clip and theme; interactions target the parent node.
+
+`contentLayout.graphs` contains absolute primitives and highlight state by `blockIndex`; labels join `contentLayout.lines`. Replace `content` to change selections at a beat start. See the [Hindsight example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/hindsight.html).
 
 ### Author a complete Facts timeline
 
-Start with fixed shape dimensions, then choose ordered blocks. Use `marker: "none"` for records, `"bullet"` for capabilities, and `"number"` for steps. Give each entry only the parts it needs. Dates are plain text; a small inline span keeps a date on the body baseline. This complete document can be passed unchanged to any host:
+Choose fixed dimensions and ordered blocks. Use unmarked lists for records, bullets for capabilities, and numbers for steps. This document works with all four integrations:
 
 ```ts
 import { createDiagram, type DiagramDocument, type NodeContent } from "flowsvg";
@@ -351,9 +393,13 @@ console.log(diagram.evaluateAt(1000).warnings);
 const svg = diagram.renderSvg(1000, { theme: "dark", reducedMotion: true });
 ```
 
-Review `contentLayout.safeArea` and `frame.warnings` before sharing a document. If content exceeds the safe area, increase the authored dimensions or shorten the text. The SDK clips overflow and never resizes nodes or shrinks fonts. Prefer default role colors when switching themes or highlighting; explicit colors remain the author's responsibility. Content is one node interaction target, with no internal links, buttons, images, HTML, or independent timeline targets.
+The initial light-theme frame at 0 ms and the updated dark-theme frame at 1000 ms:
+
+![Facts timeline before and after record replacement, shown in light and dark themes](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/facts-timeline.png)
 
-The [official content story](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.html) combines Facts, service capabilities and numbered steps with nested group movement, node resizing, explicit ports, all three edge routes, synchronized flows and focus. Its [shared document](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.js) is also used by the React and Vue example applications. Native and Web Component hosts appear together. Normal, narrow and long-text links expose fixed-area clipping; theme and reduced-motion controls apply the same visual options. All hosts use the built-in play/pause, speed, step, scene and progress controls.
+Check `frame.warnings` before sharing. Increase node dimensions or shorten overflowing text; the SDK does not resize nodes or shrink fonts. Prefer default colors for theme/highlight contrast. Content has one node-level interaction target, without internal links, buttons, images, or HTML.
+
+The [content story](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.html) combines Facts, lists, node updates, flows, and focus. Its [shared document](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.js) also runs in the Vue and React examples.
 
 Each beat has a positive `durationMs` and an `actions` array, with optional `transitionMs` and `caption`. Transition duration defaults to `min(250, durationMs)` and must be within `[0, durationMs]`. An omitted caption inherits the previous caption; an empty string clears it.
 
@@ -366,7 +412,7 @@ Each beat has a positive `durationMs` and an `actions` array, with optional `tra
 | `updateEdge` | `value` supports `label`, `stroke`, `strokeWidth`, and `opacity` |
 | `focus` | `target` is a node/group ID; `null` restores the full viewport |
 
-`updateNode.value.content` replaces the complete content object at the beat start, including when `transitionMs` is nonzero. The result persists into later beats and scenes. A `label` update switches to simple-label mode; a content update switches to structured-content mode. `content: null` clears either text mode and leaves only the shape. Clearing never restores an earlier label or changes node dimensions. Do not assign both `label` and `content`, or assign either mode more than once in the same beat; these declarations produce field-path errors. Seeking, pausing, playback speed, and reduced motion use the same content time boundary.
+`updateNode.value.content` replaces all content at beat start, regardless of transition duration, and persists across beats/scenes. `label` switches to simple-label mode; `content` switches to structured content. `content: null` clears either mode without restoring old labels or resizing. Assigning both modes, or assigning one repeatedly within a beat, produces a field-path error.
 
 ```ts
 // Each value belongs to a separate beat's updateNode action.
@@ -377,13 +423,13 @@ const simpleLabel: NodeVisualState = { label: "Summary" };
 const clearText: NodeVisualState = { content: null };
 ```
 
-All scenes share a global timeline in milliseconds. Each scene inherits the previous scene's final state. Labels and captions change at beat start; interpolated properties change during the transition. Beat intervals include their start and exclude their end; the final time returns the completed final frame. Hiding a node or group also masks connected edges; showing it again restores visibility according to each object's saved state.
+Scenes share a millisecond timeline and inherit the previous scene’s final state. Text changes at beat start; interpolated values change during the transition. Beats include their start and exclude their end; the final time returns the completed frame. Hidden nodes/groups mask connected edges; showing them restores each edge’s saved visibility.
 
-A beat can transfer along several distinct edges at once. All transfers start at the beat start, use the same linear completion ratio over `durationMs`, and disappear at the beat end. Different path lengths therefore produce different physical speeds. Shared endpoint nodes remain highlighted while any current transfer uses them. The next beat replaces the complete transfer group, including across scene boundaries. Transfer highlights do not inherit; explicit highlights and ordinary styles retain their existing inheritance rules.
+A beat supports one transfer per distinct edge. Transfers share linear progress over `durationMs`, so longer paths move faster. Markers and endpoint highlights expire at beat end; the next beat supplies a new transfer group. Explicit highlights and ordinary styles persist.
 
-## API
+Transfer `text` is escaped, stays horizontal, and uses estimated capsule widths without font measurement. It does not replace the edge label or create an interaction target. An empty string still produces a capsule.
 
-Transfer text belongs to one action and does not replace the edge's static `label`. Capsule width uses deterministic Unicode code-point estimates with padding; it does not use browser font measurements. Text remains horizontal on every route and is escaped as plain text. Capsules are decorative, with no independent pointer or keyboard interaction. A provided empty string still uses a capsule.
+## API
 
 ### Core API
 
@@ -400,11 +446,11 @@ Import from `flowsvg`:
 | `diagram.hitTest(timeMs, point, options?)` | Returns `{ id, type: "node" \| "edge" }` or `null`, using document coordinates |
 | `wrapText(label, maxWidth, typography?)` | Wraps text with fixed width estimates and returns an array of lines |
 
-`EvaluateOptions` is `{ theme?: "light" | "dark"; reducedMotion?: boolean }`. Finite times are clamped to `[0, totalDuration]`; non-finite times become zero. Hit testing ignores hidden or zero-opacity objects and checks ordinary nodes, then edges, then group backgrounds. Group hover highlights only the border and preserves the evaluated fill, including any active timeline highlight.
+`EvaluateOptions`: `{ theme?: "light" | "dark"; reducedMotion?: boolean }`. Times clamp to `[0, totalDuration]`; non-finite values become zero. Hit testing skips hidden/zero-opacity objects, then checks ordinary nodes, edges, and group backgrounds in that order.
 
-`DiagramFrameState` includes `timeMs`, `sceneId`, `beatId`, `beatProgress`, `nodes`, `edges`, `camera`, optional `caption`, and `warnings`. An active `EvaluatedEdge` may include `flow` with its direction, linear beat progress, document-coordinate point, and optional message `text`; the marker is omitted at the beat end, when the edge is hidden, or when reduced motion is enabled. Evaluated node coordinates are absolute document coordinates. Scene and beat IDs are `null` for static documents. Beat IDs use `${scene.id}:${beatIndex}`, with zero-based indexes.
+`DiagramFrameState` includes time, scene/beat IDs, progress, evaluated nodes/edges, camera, caption, and warnings. Coordinates are absolute. Static documents have `null` scene/beat IDs; beat IDs use `${scene.id}:${beatIndex}` with zero-based indexes. Active edges expose `flow` direction, progress, point, and optional text. Markers are absent after the beat, on hidden edges, or with reduced motion.
 
-Main public types include `DiagramDocument`, `DiagramNode`, `DiagramEdge`, `Scene`, `Beat`, `Action`, `Diagram`, `DiagramFrameState`, `EvaluateOptions`, `ValidationIssue`, and `LayoutWarning`. Type declarations and JSDoc for key members are included in the package.
+Types and member JSDoc are included: `DiagramDocument`, `DiagramNode`, `DiagramEdge`, `Scene`, `Beat`, `Action`, `Diagram`, `DiagramFrameState`, `EvaluateOptions`, `ValidationIssue`, and `LayoutWarning`.
 
 ### Player API
 
@@ -421,13 +467,13 @@ Import `createPlayer(host, document, options?)` from `flowsvg/browser`. `PlayerO
 | `getState()` | Returns `PlayerState`: `timeMs`, `totalDuration`, `playing`, `speed`, and `frame` |
 | `destroy()` | Idempotently cleans up DOM, listeners, and scheduling; stops events, while state remains readable |
 
-Players start paused at zero, with built-in controls enabled. Hiding the page pauses playback; making it visible again leaves playback paused. Playback stops at the final frame. Static diagrams disable timeline controls. Framework handles provide the control and state methods above, excluding `element` and `destroy`; frameworks manage the host and cleanup.
+Players start paused at zero with controls enabled. Page hiding pauses playback; returning leaves it paused. Playback stops at the end; static diagrams disable timeline controls. Framework handles expose these methods except `element` and `destroy`.
 
-Hovering a visible node's shape, simple label, or structured content highlights that node's border during playback or pause. The default border-only feedback preserves the evaluated fill and content paint. Set `hoverFill: true` to also paint the background and structured content. Hover does not highlight neighboring nodes or edges. Leaving the node removes only the hover cause; active flow and explicit highlights remain. After all causes end, the current ordinary style is shown. The player rechecks a stationary pointer after frame updates and clears hover on pointer cancellation, successful document replacement, or destruction.
+Hover highlights the current node’s border, including hits on labels or content. Set `hoverFill: true` to include background and content paint, including groups. Leaving removes only the hover highlight; active flow/explicit highlights remain. Frame updates recheck stationary pointers. Pointer cancellation, successful document replacement, and destruction clear hover.
 
-Default title/body/marker, auxiliary, tag, and status paint stays readable in both themes and during explicit, flow, and hover highlights. Intermediate highlight frames select contrasting default ink against the current evaluated fill. Authored span/block colors and tag fills remain unchanged. Highlight paint never changes text metrics, safe areas, or hit bounds. Content children have no separate IDs, keyboard focus, links, or buttons; content clicks report the node. Clipped text adds no hit area. Content replacement, text-mode changes, and node geometry updates reapply hover to the current frame; successful load clears the old document's hover.
+Default content colors adapt to the theme and highlight fill; authored colors and tag fills stay unchanged. Highlighting preserves layout and hit bounds. Content interactions report the parent node; clipped text adds no hit area.
 
-`PlayerState.frame` remains the core frame and excludes hover. Static SVG exports also exclude hover; browser output matches the same-time export when no node is hovered.
+`PlayerState.frame` and static SVG exclude hover. Browser output matches the same-time export when no node is hovered.
 
 ### Events
 
@@ -441,9 +487,9 @@ Native players dispatch `CustomEvent` on the host element:
 | `error` | `PlayerErrorDetail`: retained player state and `error` |
 | `hover` / `click` | `PlayerInteractionDetail` or `null`; aliases are `objecthover` / `objectclick` |
 
-Interaction details contain `id`, `type`, document-coordinate `point`, `timeMs`, `sceneId`, and `beatId`; a miss produces `null`. Vue, React, and Web Component wrappers forward the first four event types. Web Component errors before mounting may lack player state.
+Interaction detail contains `id`, `type`, `point` (document coordinates), `timeMs`, `sceneId`, and `beatId`; misses return `null`. Adapters forward the four playback/error events. Web Component errors before mount may lack player state.
 
-Pointer movement emits `hover`; frame updates also emit it when the object under a stationary pointer changes. Leaving or cancelling the pointer emits `null`.
+`hover` also updates when a frame change moves another object under a stationary pointer. Pointer leave/cancel emits `null`.
 
 ```ts
 import type { PlayerEventMap } from "flowsvg/browser";
@@ -460,7 +506,19 @@ This example reuses `player` from the native integration. Remove any listeners y
 
 ## Themes and accessibility
 
-Theme precedence is explicit option → document theme → light. The core does not read the system theme. Core `reducedMotion` defaults to off; the browser follows `prefers-reduced-motion` and responds to changes unless an explicit option is supplied. Reduced motion completes transitions immediately while preserving duration and time position.
+Theme: explicit option → document theme → light. The core ignores system preferences. Browser motion follows `prefers-reduced-motion` unless overridden; the core defaults to full motion. Reduced motion completes transitions immediately and hides transfer markers, preserving duration.
+
+Defaults use neutral borders and edges with blue emphasis:
+
+| Paint | Light | Dark |
+| --- | --- | --- |
+| Background / node fill | `#ffffff` / `#ffffff` | `#101828` / `#1d2939` |
+| Node border / text | `#cfd8e3` / `#1d2939` | `#475467` / `#f2f4f7` |
+| Edge | `#8892a4` | `#98a2b3` |
+| Highlight fill / border | `#eaf1ff` / `#2a63c8` | `#233b60` / `#8ab4f8` |
+| Flow marker / marker text | `#2a63c8` / `#ffffff` | `#8ab4f8` / `#101828` |
+
+Default node borders are 1.2 diagram units; edges are 2. Rounded rectangles use a radius of at most 8. Node labels use plain text; edge labels retain a background halo for readability across paths. Diagram text uses system fonts with Chinese fallbacks. Explicit styles replace ordinary defaults; timeline and hover highlights overlay those styles and restore the current ordinary paint when removed.
 
 Import `flowsvg/styles.css` for control layout and focus styles. CSS variables customize controls only; core themes and document styles determine diagram colors:
 
@@ -474,52 +532,16 @@ Import `flowsvg/styles.css` for control layout and focus styles. CSS variables c
 }
 ```
 
-Add the `flowsvg` class to a native host to use this rule; framework components add it automatically. With the canvas focused, Space plays/pauses and the left/right arrow keys step through beats. Form controls retain their native key behavior. Captions use a polite live region, and each SVG has its own accessible name.
+Add `flowsvg` to a native host to apply these variables; framework components add it automatically. With canvas focus, Space toggles playback and arrow keys step through beats. Form controls keep native keys. Captions use a polite live region; SVGs have accessible names.
 
 ## Validation and errors
 
-Loading rejects unknown fields, invalid references, cyclic groups, duplicate assignments within a beat, invalid colors, and invalid dimensions/durations. Text is escaped as plain text. To check external JSON first, call `validateDocument` and display each issue's `path` and `message`.
+Validation rejects unknown fields, bad references, cyclic groups, duplicate beat assignments, invalid colors, and invalid dimensions/durations. Text is escaped. For external JSON, call `validateDocument` and inspect each issue’s `path` and `message`.
 
-`createDiagram` and `createPlayer` with an invalid initial document throw `DiagramValidationError`, whose `issues` contain field paths. An existing player's `load` reports validation failure through the `error` event and preserves the old state. Text height overflow is a nonblocking layout warning; inspect `frame.warnings` to decide whether to resize nodes.
-
-Each beat permits at most one `flow` per edge, even when directions or text differ. Repeating an edge reports `duplicate beat assignment` at the later action’s `target`, independently of other field errors. A flow can coexist with visibility, explicit highlight, and ordinary style actions on the same edge; those actions retain their own validation rules.
-
-## Development and verification
-
-Run these commands from the source repository root. Development uses Node.js 22.12+ and pnpm 10.12.1; Vue/React examples use Vite 7.
-
-| Command | Purpose |
-| --- | --- |
-| `pnpm install` | Install workspace dependencies |
-| `pnpm build` | Build SDK JavaScript, declarations, and styles |
-| `pnpm typecheck` | Check core, browser, and framework entry types |
-| `pnpm test` | Run Vitest behavior tests |
-| `pnpm --filter flowsvg-vue-example dev` | Start the Vue example |
-| `pnpm --filter flowsvg-react-example dev` | Start the React example |
-| `pnpm release:verify` | Pack from a missing `dist`, verify the file allowlist and every export, then check framework-free imports, strict consumer types and all four host lifecycles |
-| `pnpm release` | Run all release gates and npm preview; retain the verified tarball in `dist/releases/` without uploading |
-| `pnpm release:publish` | Check npm authentication, repeat all release gates and preview, then upload the verified tarball |
+`createDiagram` and initial `createPlayer` calls throw `DiagramValidationError` for invalid documents. Its `issues` contain field paths. Later `load` failures emit `error` and retain the old state. Text overflow is nonblocking; inspect `frame.warnings`.
 
-Maintainers: follow the [npm release guide](https://github.com/yokingma/FlowSVG/blob/HEAD/docs/RELEASING.md). Run SDK packaging before example builds; packaging removes and rebuilds `dist`.
-
-After building, run the Node.js static server from the repository root:
-
-```sh
-pnpm dlx http-server@14.1.1 . -p 4175 -c-1
-```
-
-The first run downloads the CLI without adding a project dependency. Open <http://localhost:4175/apps/native-example/> for the native example. For browser acceptance checks, open the `/packages/flowsvg/tests/browser-*.html` pages: `controls`, `lifecycle`, `visual-updates`, `focus`, `accessibility`, `web-component`, `flow-text`, and `parallel-flows`. Inspect the corresponding `window.browserTestResults`, `window.browserFocusResults`, `window.browserAccessibilityResults`, `window.browserWebComponentResults`, or `window.browserFlowTextResults`; every result's `passed` must be `true`.
-
-Open `/packages/flowsvg/tests/browser-hover.html` for real-pointer hover checks. Hover the source shape and overflowing label, use the flow/after-flow controls, and verify that leaving preserves active flow highlights and restores the latest ordinary style afterward. Check stationary-pointer updates, reload cleanup, and destroy cleanup with the remaining controls.
-
-To verify automatic reduced motion, open the accessibility page, change the browser's reduced-motion media emulation, then call `window.verifyMotionPreference(true)` or `false`. Check that preference changes match SVG export with the same options.
-
-Reuse compiled diagrams during playback and avoid recreating players on every render. Measure frame costs for large diagrams on target devices. See [CHANGELOG](CHANGELOG.md) for changes and [PATTERNS](PATTERNS.md) for implementation conventions.
-
-Parallel transfer checks and a playable three-then-two transfer demo are in `tests/browser-parallel-flows.html`. The checks compare public frames and SVG output across scene boundaries, themes, and reduced motion.
+Duplicate `flow` actions on one edge report `duplicate beat assignment` at the later `target`, regardless of direction, text, or other field errors. Flows may coexist with visibility, explicit highlight, and style actions.
 
 ## License
 
 [MIT](LICENSE). Use, modify, and distribute with the license and copyright notice retained.
-
-Open [the node-content pointer fixture](https://github.com/yokingma/FlowSVG/blob/HEAD/packages/flowsvg/tests/browser-node-content.html) (add `?theme=dark` for dark mode) to check all three shapes, tags, clipped long text, explicit/flow/hover layering, stationary-pointer content/text-mode/size updates, theme replacement and destruction.