flowsvg 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,525 @@
-# Temporary Holding Version
+# flowsvg
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+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.
+
+[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
+
+Install from npm:
+
+```sh
+pnpm add flowsvg
+```
+
+Install only the framework for your chosen entry:
+
+```sh
+# Vue applications
+pnpm add vue
+# React applications
+pnpm add react react-dom
+# React TypeScript applications
+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.
+
+| Import path | Purpose |
+| --- | --- |
+| `flowsvg` | DOM-free document validation, compilation, evaluation, hit testing, and SVG export |
+| `flowsvg/browser` | Native browser player |
+| `flowsvg/vue` | Vue component and handle types |
+| `flowsvg/react` | React component and ref types |
+| `flowsvg/web-component` | Explicit custom element registration; also available as `flowsvg/element` |
+| `flowsvg/styles.css` | Control layout and visible focus styles |
+
+## Quick start
+
+### 1. Create a diagram document
+
+Save this as `diagram.ts`. 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 },
+  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 }
+  ],
+  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" }] }
+    ]
+  }]
+};
+```
+
+### 2. Evaluate and export SVG
+
+```ts
+import { createDiagram, renderSvg } from "flowsvg";
+import { diagramDocument } from "./diagram.js";
+
+const diagram = createDiagram(diagramDocument);
+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);
+```
+
+`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.
+
+## Vue integration
+
+Create a component in your Vue application, with `diagram.ts` in the same directory:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FlowPlayer, type FlowPlayerHandle } from "flowsvg/vue";
+import type { PlayerErrorDetail } from "flowsvg/browser";
+import "flowsvg/styles.css";
+import { diagramDocument } from "./diagram.js";
+
+const player = ref<FlowPlayerHandle | null>(null);
+const timeMs = ref(0);
+
+function handleError({ error }: PlayerErrorDetail): void {
+  console.error(error);
+}
+</script>
+
+<template>
+  <FlowPlayer
+    ref="player"
+    :document="diagramDocument"
+    :speed="1.25"
+    theme="dark"
+    @timeupdate="timeMs = $event.timeMs"
+    @error="handleError"
+  />
+  <button type="button" @click="player?.play()">Play</button>
+  <button type="button" @click="player?.seek(0)">Back to start</button>
+  <output>{{ timeMs }} ms</output>
+</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.
+
+## React integration
+
+```tsx
+import { useRef } from "react";
+import { FlowPlayer, type FlowPlayerHandle } from "flowsvg/react";
+import "flowsvg/styles.css";
+import { diagramDocument } from "./diagram.js";
+
+export default function DiagramExample() {
+  const player = useRef<FlowPlayerHandle | null>(null);
+
+  return (
+    <section>
+      <FlowPlayer
+        ref={player}
+        document={diagramDocument}
+        speed={1.25}
+        theme="dark"
+        onError={({ error }) => console.error(error)}
+      />
+      <button type="button" onClick={() => player.current?.play()}>Play</button>
+      <button type="button" onClick={() => player.current?.seek(0)}>Back to start</button>
+    </section>
+  );
+}
+```
+
+The component releases resources on unmount. Callbacks are `onStepChange`, `onTimeUpdate`, `onPlayStateChange`, and `onError`.
+
+### Vue / React props and updates
+
+| Prop | Default or behavior |
+| --- | --- |
+| `document` | Required diagram document; a new object reference triggers a reload, pausing at zero on success |
+| `speed` | Positive playback multiplier, default `1`; changes update the speed |
+| `theme` | `light` / `dark`; falls back to the document theme, then light |
+| `controls` | Default `true`; set to `false` to hide built-in controls |
+| `reducedMotion` | Follows the browser's reduced-motion preference when omitted |
+| `hoverFill` | Default `false`: hover highlights the border only; set `true` to also highlight the background and content |
+| `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.
+
+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.
+
+## Native browser
+
+Add a container to your page:
+
+```html
+<div id="diagram" style="width: 100%; height: 360px;"></div>
+```
+
+Create the player in a client-side application module:
+
+```ts
+import { createPlayer } from "flowsvg/browser";
+import "flowsvg/styles.css";
+import { diagramDocument } from "./diagram.js";
+
+const host = document.querySelector<HTMLElement>("#diagram");
+if (!host) throw new Error("Diagram host is missing");
+
+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.
+
+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.
+
+## Web Component
+
+Place the element in HTML, then register it explicitly from a client-side module:
+
+```html
+<flowsvg-player controls="false"></flowsvg-player>
+```
+
+```ts
+import { defineFlowPlayer, type FlowPlayerElement } from "flowsvg/web-component";
+import "flowsvg/styles.css";
+import { diagramDocument } from "./diagram.js";
+
+defineFlowPlayer();
+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.
+
+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.
+
+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.
+
+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.
+
+## Documents and timelines
+
+| Document field | Contract |
+| --- | --- |
+| `version` | Currently `1` |
+| `viewport` | Finite positive `width` and `height`, defining the initial viewport |
+| `nodes` | Node array; `id`, `kind`, `x`, `y`, `width`, and `height` are required |
+| `edges` | Edge array; `id`, `from`, and `to` are required; endpoints reference nodes or group boundaries |
+| `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`.
+
+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.
+
+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.
+
+### 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:
+
+```ts
+const service = {
+  id: "service", kind: "rect", x: 24, y: 24, width: 260, height: 312,
+  content: {
+    style: { padding: 16, blockGap: 14 },
+    blocks: [
+      { type: "title", text: "Order service" },
+      { type: "paragraph", role: "auxiliary", text: "Core responsibilities" },
+      { type: "paragraph", text: "Validate and persist incoming orders." },
+      { type: "paragraph", text: "Return the order number.", style: { color: "#2563eb", align: "right" } }
+    ]
+  }
+} 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.
+
+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.
+
+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:
+
+```ts
+{ 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:
+
+```ts
+{ 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.
+
+`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).
+
+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.
+
+
+### 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`:
+
+```ts
+const entities: ContentGraphBlock = {
+  type: "graph", height: 130,
+  nodes: [
+    { id: "alice", label: "Alice", x: 120, y: 30, highlighted: true },
+    { id: "google", label: "Google", x: 50, y: 110, highlighted: true },
+    { id: "ml", label: "ML project", x: 190, y: 110 }
+  ],
+  edges: [{ from: "alice", to: "google" }, { from: "alice", to: "ml" }]
+};
+```
+
+`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.
+
+`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.
+
+### 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:
+
+```ts
+import { createDiagram, type DiagramDocument, type NodeContent } from "flowsvg";
+
+const facts: NodeContent = { blocks: [
+  { type: "title", text: "Facts" },
+  { type: "paragraph", role: "auxiliary", text: "Confirmed records" },
+  { type: "list", marker: "none", items: [{
+    tags: [{ text: "world" }, { text: "orders", style: { fill: "#eadfff", color: "#57319b" } }],
+    status: "new",
+    body: [{ text: "Order saved", style: { fontWeight: 700 } }, { text: " 2026-10-17", style: { fontSize: 11 } }],
+    auxiliary: "Ready for payment."
+  }] }
+] };
+const updated: NodeContent = { blocks: [
+  { type: "title", text: "Facts" },
+  { type: "list", items: [{ tags: [{ text: "verified" }], status: "done", body: "Payment confirmed", auxiliary: "2026-10-18" }] }
+] };
+const document: DiagramDocument = {
+  version: 1, viewport: { width: 300, height: 480 },
+  nodes: [{ id: "facts", kind: "cylinder", x: 24, y: 20, width: 240, height: 440, content: facts }], edges: [],
+  scenes: [{ id: "records", label: "Records", beats: [
+    { durationMs: 1000, actions: [] },
+    { durationMs: 1000, actions: [{ type: "updateNode", target: "facts", value: { content: updated } }] },
+    { durationMs: 1000, actions: [{ type: "updateNode", target: "facts", value: { label: "Archived" } }] },
+    { durationMs: 1000, actions: [{ type: "updateNode", target: "facts", value: { content: facts } }] },
+    { durationMs: 1000, actions: [{ type: "updateNode", target: "facts", value: { content: null } }] }
+  ] }]
+};
+const diagram = createDiagram(document);
+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 [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.
+
+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.
+
+| Action | Example or update fields |
+| --- | --- |
+| `show` / `hide` | `{ type: "show", target: "service" }`; targets a node, group, or edge |
+| `highlight` / `unhighlight` | Changes the highlight layer; removing a highlight reveals the latest ordinary style |
+| `flow` | `{ type: "flow", target: "request", direction: "forward" }`; moves a beat-local marker along an edge. `direction` is `forward` or `reverse`; the static edge arrow does not change. Add `text: "Request"` for a horizontal text capsule; omit `text` for a solid dot. |
+| `updateNode` | `value` supports `x`, `y`, `width`, `height`, `label`, `content`, `fill`, `stroke`, and `opacity` |
+| `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.
+
+```ts
+// Each value belongs to a separate beat's updateNode action.
+import type { NodeVisualState } from "flowsvg";
+
+const replacement: NodeVisualState = { content: { blocks: [{ type: "title", text: "Updated" }] } };
+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.
+
+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.
+
+## API
+
+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.
+
+### Core API
+
+Import from `flowsvg`:
+
+| API | Result and behavior |
+| --- | --- |
+| `validateDocument(input: unknown)` | Returns `{ path, message }[]`; an empty array means valid |
+| `createDiagram(document)` | Validates, copies, and compiles into a `Diagram`; invalid documents throw `DiagramValidationError` |
+| `renderSvg(document, timeMs = 0, options?)` | Compiles once and exports a static SVG string |
+| `diagram.totalDuration` | Total timeline duration; `0` for a static document |
+| `diagram.evaluateAt(timeMs, options?)` | Returns `DiagramFrameState` |
+| `diagram.renderSvg(timeMs = 0, options?)` | Exports SVG from the same evaluation result |
+| `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.
+
+`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.
+
+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.
+
+### Player API
+
+Import `createPlayer(host, document, options?)` from `flowsvg/browser`. `PlayerOptions` extends core visual options with `controls?: boolean` and `hoverFill?: boolean`.
+
+| Method or property | Behavior |
+| --- | --- |
+| `element` | The original host element and event target |
+| `play()` / `pause()` | Starts playback or pauses on the current frame; static diagrams and the timeline end cannot start playback |
+| `seek(timeMs)` | Clamps to the timeline and retains playback state; reaching the end pauses |
+| `step(1)` / `step(-1)` | Pauses and jumps to the adjacent beat start; stepping backward inside a beat goes to its start, and backward at a beat start goes to the previous beat |
+| `setSpeed(speed)` | Sets a finite positive multiplier; ignores invalid values |
+| `load(document)` | Pauses at zero on success; validation failure emits error and retains the document, time, and playback state |
+| `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.
+
+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.
+
+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.
+
+`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.
+
+### Events
+
+Native players dispatch `CustomEvent` on the host element:
+
+| Event | `detail` |
+| --- | --- |
+| `timeupdate` | Current `PlayerState`, sent after the frame updates |
+| `stepchange` | Current `PlayerState`, sent when the scene or beat changes, before that update's timeupdate |
+| `playstatechange` | Current `PlayerState`, sent when playing/paused state changes |
+| `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.
+
+Pointer movement emits `hover`; frame updates also emit it when the object under a stationary pointer changes. Leaving or cancelling the pointer emits `null`.
+
+```ts
+import type { PlayerEventMap } from "flowsvg/browser";
+
+function handleTimeUpdate(event: Event): void {
+  const { detail } = event as PlayerEventMap["timeupdate"];
+  console.log(detail.timeMs, detail.frame.caption);
+}
+
+player.element.addEventListener("timeupdate", handleTimeUpdate);
+```
+
+This example reuses `player` from the native integration. Remove any listeners your application adds when disposing of the host.
+
+## 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.
+
+Import `flowsvg/styles.css` for control layout and focus styles. CSS variables customize controls only; core themes and document styles determine diagram colors:
+
+```css
+.flowsvg {
+  --flowsvg-control-background: #101828;
+  --flowsvg-control-color: #f4f7fb;
+  --flowsvg-control-border: #64748b;
+  --flowsvg-control-accent: #60a5fa;
+  --flowsvg-control-focus: #fbbf24;
+}
+```
+
+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.
+
+## 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`.
+
+`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 |
+
+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.
+
+## 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.