flowsvg 0.1.0 → 0.2.0

package/README.md

@@ -1,525 +1,235 @@
-# flowsvg
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/npm/flowsvg@0.2.0/docs/images/flowsvg-wordmark.gif" alt="FlowSVG" width="280">
+</p>
 
-English | [简体中文](README.zh-CN.md)
+<p align="center">Declarative SVG diagrams with timeline playback and SVG/GIF export.</p>
 
-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.
+<p align="center">English | <a href="https://cdn.jsdelivr.net/npm/flowsvg@0.2.0/README.zh-CN.md">简体中文</a></p>
 
-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.
+<p align="center">
+  <a href="#define-a-diagram">Quick&nbsp;start</a> ·
+  <a href="#control-playback">Playback&nbsp;API</a> ·
+  <a href="#core-api--flowsvg">Core&nbsp;API</a> ·
+  <a href="#document-and-actions">Document&nbsp;model</a> ·
+  <a href="#export-api">Export&nbsp;API</a>
+</p>
 
-[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:
+Define the data once and use it in native browser, Vue, React, or Web Component integrations.
 
 ```sh
-pnpm install --frozen-lockfile
-pnpm --filter flowsvg exec npm pack --pack-destination /tmp
+npm install flowsvg
 ```
 
-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:
+## Define a diagram
 
 ```ts
+// diagram.ts
 import type { DiagramDocument } from "flowsvg";
 
-export const diagramDocument: DiagramDocument = {
+export const diagram: DiagramDocument = {
   version: 1,
-  title: "Request flow",
-  viewport: { width: 640, height: 280 },
+  viewport: { width: 640, height: 240 },
   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: 90, width: 140, height: 64, label: "Client" },
+    { id: "service", kind: "roundedRect", x: 400, y: 90, width: 180, height: 64, label: "Service" }
   ],
-  edges: [{ id: "request", from: "client", to: "service", label: "HTTP", route: "straight" }],
+  edges: [{ id: "request", from: "client", to: "service", route: "orthogonal" }],
   scenes: [{
-    id: "request-flow",
-    label: "Request reaches the service",
+    id: "request-response",
+    label: "Request and response",
     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" }] }
+      { durationMs: 1000, caption: "Send request", actions: [
+        { type: "flow", target: "request", direction: "forward", text: "Request" }
+      ] },
+      { durationMs: 1000, caption: "Return response", actions: [
+        { type: "flow", target: "request", direction: "reverse" }
+      ] }
     ]
   }]
 };
 ```
 
-### 2. Evaluate and export SVG
+Nodes use explicit positions and dimensions. Routes are `straight`, `orthogonal` (rounded bends), or `curved`. Flow text produces a capsule; omitting text produces a moving dot.
+
+## Play
+
+```html
+<div id="diagram"></div>
+```
 
 ```ts
-import { createDiagram, renderSvg } from "flowsvg";
-import { diagramDocument } from "./diagram.js";
+import { createPlayer } from "flowsvg/browser";
+import "flowsvg/styles.css";
+import { diagram } from "./diagram.js";
 
-const diagram = createDiagram(diagramDocument);
-const frame = diagram.evaluateAt(125);
-console.log(diagram.totalDuration, frame.sceneId, frame.warnings);
+const player = createPlayer(document.querySelector<HTMLElement>("#diagram")!, diagram, {
+  theme: "light",
+  loop: true,
+  gifExport: true
+});
 
-const svg = diagram.renderSvg(125, { theme: "dark" });
-const finalSvg = renderSvg(diagramDocument, 2000);
+player.play();
+// On disposal: player.destroy();
 ```
 
-`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.
+Players start paused, with playback controls enabled. Loop and GIF downloads default off. Import the CSS once. Call `destroy()` when disposing of a native player; framework components handle cleanup.
 
-## Vue integration
-
-Create a component in your Vue application, with `diagram.ts` in the same directory:
+### Vue
 
 ```vue
 <script setup lang="ts">
-import { ref } from "vue";
-import { FlowPlayer, type FlowPlayerHandle } from "flowsvg/vue";
-import type { PlayerErrorDetail } from "flowsvg/browser";
+import { FlowPlayer } from "flowsvg/vue";
 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);
-}
+import { diagram } from "./diagram.js";
 </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>
+  <FlowPlayer :document="diagram" loop gif-export />
 </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
+### React
 
 ```tsx
-import { useRef } from "react";
-import { FlowPlayer, type FlowPlayerHandle } from "flowsvg/react";
+import { FlowPlayer } 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>
-  );
+import { diagram } from "./diagram.js";
+
+export function Diagram() {
+  return <FlowPlayer document={diagram} loop gifExport />;
 }
 ```
 
-The component releases resources on unmount. Callbacks are `onStepChange`, `onTimeUpdate`, `onPlayStateChange`, and `onError`.
+## Control playback
 
-### Vue / React props and updates
+`createPlayer(host: HTMLElement, document: DiagramDocument, options?: PlayerOptions): FlowPlayer` mounts into the host, replacing its children. Invalid initial documents throw `DiagramValidationError`.
 
-| Prop | Default or behavior |
+| Method / property | 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.
+| `play(): void` / `pause(): void` | Resume / pause at the current position. At the end, `play()` restarts only when Loop is enabled; static diagrams cannot play. |
+| `seek(timeMs: number): void` | Clamp to the timeline; retain playback except at the end. Non-finite values become zero. |
+| `step(direction: 1 \| -1): void` | Pause and move to a beat boundary. Backward from inside a beat goes to that beat's start. |
+| `setSpeed(speed: number): void` | Set a finite positive multiplier; ignore invalid values. Default `1`. |
+| `setLoop(loop: boolean): void` | Change whole-timeline looping without changing position or playback. |
+| `load(document: DiagramDocument): void` | Pause at zero on success; emit `error` and retain the old document/state on failure. |
+| `getState(): PlayerState` | Read `{ timeMs, totalDuration, playing, loop, speed, frame }`. Times are milliseconds. |
+| `destroy(): void` | Release DOM, listeners and animation resources. Safe to repeat. Not exposed by Vue/React refs. |
+| `element: HTMLElement` | Readonly host and event target. Not exposed by Vue/React refs. |
 
-## Native browser
-
-Add a container to your page:
-
-```html
-<div id="diagram" style="width: 100%; height: 360px;"></div>
-```
+Vue/React refs expose the eight playback/state methods above. Replace the `document` object to reload a component. Changes to `theme`, `controls`, `gifExport`, `reducedMotion`, or `hoverFill` recreate the player paused at zero.
 
-Create the player in a client-side application module:
+### Options and component props
 
-```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 |
+| `PlayerOptions` | Default / meaning |
 | --- | --- |
-| `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 |
+| `theme?: "light" \| "dark"` | Document theme, then `"light"`. |
+| `controls?: boolean` | `true`; show playback controls. |
+| `loop?: boolean` | `false`; loop the entire timeline. |
+| `gifExport?: boolean` | `false`; show GIF download controls when `controls` is enabled. |
+| `hoverFill?: boolean` | `false`; hover marks borders only. `true` also highlights backgrounds. |
+| `reducedMotion?: boolean` | Follow browser preference; `true` hides flow markers and completes visual transitions immediately without changing timing. |
 
-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;
-```
+Vue/React `FlowPlayerProps` also accept required `document: DiagramDocument`, `speed?: number` (default `1`), `initialTimeMs?: number` (applied once), `className`, and `style`. Both entries export `FlowPlayerHandle` and `FlowPlayerProps`. Native players start through `play()` and change speed through `setSpeed()`.
 
-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).
+### Events
 
-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.
+Native events are `CustomEvent`s on `player.element`; read `event.detail`. Vue handlers and React callbacks receive the detail directly.
 
+| Native / Vue event | React callback | Detail |
+| --- | --- | --- |
+| `stepchange` | `onStepChange` | `PlayerState`; scene/beat selection changed. |
+| `timeupdate` | `onTimeUpdate` | `PlayerState`; frame updated. |
+| `playstatechange` | `onPlayStateChange` | `PlayerState`; playing state changed. |
+| `loopchange` | `onLoopChange` | `PlayerState`; loop setting changed. |
+| `error` | `onError` | `PlayerErrorDetail`: player state plus `error: Error`. |
+| `hover`, `click` | — | Browser/Web Component: `{ id, type, point, timeMs, sceneId, beatId }`, or `null` for no hit. Aliases: `objecthover`, `objectclick`. |
 
-### Entity graphs inside nodes
+Interaction `point` uses diagram coordinates; `type` is `"node"` or `"edge"`. A frame update emits `stepchange`, when needed, before `timeupdate`. Web Component errors before mounting may omit player-state fields.
 
-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`:
+## Export
 
 ```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.
+import { createDiagram } from "flowsvg";
+import { exportGif } from "flowsvg/export";
+import { diagram } from "./diagram.js";
 
-`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 });
+const compiled = createDiagram(diagram);
+const frame = compiled.evaluateAt(1200);
+const svg = compiled.renderSvg(1200, { theme: "dark" });
+const gif = await exportGif(diagram, { width: 640, fps: 15 });
 ```
 
-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.
+SVG returns a string; GIF returns `Uint8Array`. Browser GIF export supports `signal` and `onProgress`. Use `gifExport: true` for built-in download controls. Node 20+ also provides `renderHtml` and `exportGif` through `flowsvg/node`; Node GIF requires prepared Chromium.
 
-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.
+## Core API — `flowsvg`
 
-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.
+All times are milliseconds; positions and dimensions use diagram units. `options?: EvaluateOptions` accepts `theme?: "light" | "dark"` and `reducedMotion?: boolean` (default `false`).
 
-| Action | Example or update fields |
+| Function | Result / behavior |
 | --- | --- |
-| `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 |
+| `createDiagram(document: DiagramDocument): Diagram` | Validate, copy, freeze and compile the document for repeated queries. |
+| `renderSvg(document: DiagramDocument, timeMs = 0, options?): string` | Compile and render one static SVG. |
+| `validateDocument(input: unknown): ValidationIssue[]` | Check fields and references; return `{ path, message }` issues. An empty array means these checks passed; compilation can still reject non-finite derived flow timing. |
+| `measureNodeContent({ kind, width, content }): NodeContentMeasurement` | Return `{ height, diagnostics }`. `kind`: `rect`, `roundedRect`, or `cylinder`; `content`: one `NodeContent` or a nonempty array of versions. Return the largest required height across versions. |
+| `wrapText(label: string, maxWidth: number, typography?): string[]` | Estimate wrapping without the DOM. Optional typography supplies all three numeric fields: `fontSize`, `lineHeight`, `charWidth`; omitted uses node typography. |
 
-`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 |
+| Compiled `Diagram` | Result / 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.
+| `totalDuration: number` | Readonly effective duration; `0` for static documents. |
+| `beats: readonly DiagramBeat[]` | Compiled `{ sceneId, beatId, beatIndex, startMs, endMs, caption? }` intervals. |
+| `evaluateAt(timeMs: number, options?): DiagramFrameState` | Return `{ timeMs, sceneId, beatId, beatProgress, nodes, edges, camera, caption?, warnings }`. |
+| `renderSvg(timeMs = 0, options?): string` | Render without recompiling. |
+| `hitTest(timeMs: number, point: DiagramPoint, options?): HitObject \| null` | Hit-test `{ x, y }` in diagram coordinates; return `{ id, type }` or `null`. |
 
-`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.
+Query times clamp to `[0, totalDuration]`; non-finite values become zero. `DiagramValidationError.issues` contains validation paths and messages. Measurement diagnostics contain `{ versionIndex, path, dimension, message }`; increasing height does not fix width overflow or overflow inside a fixed-height graph block.
 
-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.
+### Document and actions
 
-### 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 |
+| Type | Core fields |
 | --- | --- |
-| `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.
+| `Viewport` | Required finite positive `width` and `height`; optional `fitHeight: { padding }` with finite nonnegative bottom padding. |
+| `DiagramDocument` | `version: 1`, `viewport`, `nodes`, `edges`, `scenes`; optional `title`, `theme`. Empty `scenes` makes a static diagram. |
+| `DiagramNode` | `id`, `kind`, `x`, `y`, `width`, `height`; optional `label` or `content` (mutually exclusive), `parentId`, `visible`, `style`. Kinds: `rect`, `roundedRect`, `ellipse`, `cylinder`, `group`. |
+| `DiagramEdge` | `id`, `from`, `to`; optional `route` (default `straight`), `fromPort`, `toPort`, `label`, `visible`, `style`. Ports: `top`, `right`, `bottom`, `left`. |
+| `Scene` / `Beat` | Scene: `{ id, label, beats }`. Beat: `{ durationMs, actions, transitionMs?, caption? }`. `durationMs` must be positive. `transitionMs` must be in `[0, durationMs]`, defaults to `min(250, durationMs)`, and is capped at effective beat length. |
+| `Action` | `{ type, target }`; `updateNode` / `updateEdge` also require `value`. `flow` requires `direction` (`forward` / `reverse`), with optional `text` and `highlightParticipants` (default `true`). `focus` targets a node/group ID or `null` for full view. |
 
-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.
+`updateNode.value` supports `x`, `y`, `width`, `height`, `label`, `content` (`null` clears it), `fill`, `stroke`, and `opacity`. `updateEdge.value` supports `label`, `stroke`, `strokeWidth`, and `opacity`. Node/edge IDs are globally unique; child positions are relative to their parent group. `NodeContent` and its block types are exported from `flowsvg`.
 
-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.
+## Export API
 
-`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` |
+| Entry / function | Return / requirements |
 | --- | --- |
-| `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
+| `flowsvg/export` → `exportGif(document, options?: GifExportOptions)` | `Promise<Uint8Array>`; browser canvas and worker support. |
+| `flowsvg/node` → `renderHtml(document, options?: HtmlRenderOptions)` | `Promise<string>`; standalone offline player HTML. Node 20+, no browser required. |
+| `flowsvg/node` → `exportGif(document, options?: NodeGifExportOptions)` | `Promise<Uint8Array>`; Node 20+ and prepared Chromium. Set `executablePath` or supply a Playwright `browser`, never both. A supplied browser remains caller-owned. |
 
-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 |
+| `GifExportOptions` | Default / meaning |
 | --- | --- |
-| `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
-```
+| `theme`, `reducedMotion` | Document theme then `light`; reduced motion defaults to `false`. |
+| `startMs`, `endMs`, `speed` | Full timeline at `1×`; range start is inclusive and end exclusive, except the global end includes the completed state. |
+| `width`, `fps` | `min(viewport.width, 1280)` pixels; `15` samples/second (`1`–`30`, integer). |
+| `includeCaptions`, `captionHeight` | `true`; fixed caption region of `80` pixels. |
+| `loopCount`, `finalHoldMs` | `0` means infinite GIF looping; `1`–`65536` means total plays. Add `1000` ms of final hold by default. Independent of live player looping. |
+| `signal`, `onProgress` | `AbortSignal`; callback receives `{ phase, completed, total }`. Phases: `preparing`, `sampling`, `encoding`, `complete`. |
 
-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`.
+GIF limits: 120 effective seconds, 1800 samples, 1801 encoded frames, final long edge ≤1920 pixels including captions. `GifExportError.code` is `options`, `limit`, `document`, `caption-overflow`, `environment`, `rasterization`, `encoding`, or `cancelled`. Both export entries expose `GifExportError` and their option/progress types.
 
-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.
+`HtmlRenderOptions`: `theme`, `autoplay` (default `false`), `loop` (`false`), `controls` (`true`), `gifExport` (`false`). Built-in GIF downloads export the full timeline at `1×`, using the current theme.
 
-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.
+## Other browser APIs
 
-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.
+- `flowsvg/web-component` (alias `flowsvg/element`): call `defineFlowPlayer(tagName = "flowsvg-player")` in the browser; returns the registered constructor, or `undefined` without a custom-element registry. Set `element.document` to an object, use the `document` JSON attribute, or load a URL through `src`. Playback options use attributes such as `loop`, `gif-export`, and `reduced-motion`; `autoplay` defaults to `false`, `speed` to `1`. Use playback methods except `load()`; assign `.document` to reload. `getState()` can return `undefined` before mounting or after destruction. Events bubble and cross shadow boundaries.
+- `flowsvg/browser`: `new SelectControl(owner: Document, label: string, onChange: (value: string) => void)`. Append `.element`, synchronize with `render(choices: readonly SelectChoice[], value: string, disabled = false)`, and call `destroy()` on disposal. Each choice is `{ value, label }`; the caller owns the committed value.
 
-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.
+## Authoring rules
 
-## License
+- `show`, `hide`, `highlight`, `unhighlight`, `updateNode`, `updateEdge`, and `focus` persist across beats. `flow` lasts for its beat only.
+- A single flow moves at a reference 180 diagram units/second (minimum 400 ms), then uses a 500 ms arrival interval including highlight fades. This replaces authored `durationMs`. Multiple flows and no-flow beats retain authored timing. Read effective boundaries from `compiled.beats`; use separate no-flow beats for reading time.
+- Structured `content` supports titles, paragraphs, lists, tags, and entity graphs in rectangles, rounded rectangles, and cylinders. Use `measureNodeContent({ kind, width, content })` before authoring fixed dimensions; inspect its `diagnostics`. It does not resize nodes during playback.
+- `viewport.fitHeight: { padding: 24 }` fits current full-view height. GIF keeps the authored viewport dimensions and scale.
+- Invalid documents throw `DiagramValidationError` with field paths. Text overflow appears in `frame.warnings`. `validateDocument(input)` checks external JSON before use.
 
-[MIT](LICENSE). Use, modify, and distribute with the license and copyright notice retained.
+ESM with TypeScript declarations. Core runs without DOM on Node 18+; Node tools require Node 20+. Vue 3.5+ / React 18+.
 
-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.
+[Full SDK guide](https://github.com/yokingma/FlowSVG/blob/main/docs/SDK-GUIDE.md) · [Changelog](https://cdn.jsdelivr.net/npm/flowsvg@0.2.0/CHANGELOG.md) · [MIT](https://cdn.jsdelivr.net/npm/flowsvg@0.2.0/LICENSE)