flowsvg 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,547 @@
-# 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 plays logic and architecture diagrams with SVG. Define nodes, edges, scenes, and beats in JSON or TypeScript, then play them in a browser or export a static SVG.
+
+The ESM SDK includes a DOM-free core and native browser, Vue, React, and Web Component integrations. All integrations share the same document and timeline.
+
+[Installation](#installation) · [Quick start](#quick-start) · [Vue](#vue-integration) · [React](#react-integration) · [Native browser](#native-browser) · [Web Component](#web-component) · [API](#api) · [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 need no framework. TypeScript declarations are included. Core: Node.js 18+ or ES2022 ESM. Browser: DOM, SVG, and `requestAnimationFrame`. Frameworks: Vue 3.5+ or React 18+.
+
+| Import path | Purpose |
+| --- | --- |
+| `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`. This 5.2-second example uses six nodes, three scenes and five beats. It separates authorization, order persistence, and the final response with an asynchronous event. The integration examples below reuse this file:
+
+```ts
+import type { DiagramDocument } from "flowsvg";
+
+export const diagramDocument: DiagramDocument = {
+  version: 1,
+  title: "Order request lifecycle",
+  viewport: { width: 960, height: 440 },
+  nodes: [
+    { id: "client", kind: "roundedRect", x: 40, y: 205, width: 120, height: 70, label: "Client" },
+    { id: "gateway", kind: "roundedRect", x: 260, y: 205, width: 130, height: 70, label: "API gateway" },
+    { id: "auth", kind: "ellipse", x: 260, y: 40, width: 130, height: 72, label: "Auth" },
+    { id: "orders", kind: "roundedRect", x: 500, y: 205, width: 150, height: 70, label: "Order service" },
+    { id: "database", kind: "cylinder", x: 780, y: 65, width: 140, height: 90, label: "Orders" },
+    { id: "events", kind: "rect", x: 780, y: 330, width: 140, height: 70, label: "Event queue" }
+  ],
+  edges: [
+    { id: "request", from: "client", to: "gateway", route: "straight" },
+    { id: "authorize", from: "gateway", to: "auth", route: "straight", fromPort: "top", toPort: "bottom" },
+    { id: "create", from: "gateway", to: "orders", route: "straight" },
+    { id: "persist", from: "orders", to: "database", route: "orthogonal", fromPort: "right", toPort: "left" },
+    { id: "publish", from: "orders", to: "events", route: "curved", fromPort: "bottom", toPort: "left" },
+    { id: "result", from: "orders", to: "gateway", route: "curved", fromPort: "bottom", toPort: "bottom" }
+  ],
+  scenes: [
+    { id: "request", label: "Receive and authorize", beats: [
+      { durationMs: 800, caption: "Receive the order request", actions: [
+        { type: "flow", target: "request", direction: "forward", text: "POST" }
+      ] },
+      { durationMs: 800, caption: "Validate the access token", actions: [
+        { type: "flow", target: "authorize", direction: "forward", text: "Token" }
+      ] }
+    ] },
+    { id: "create-order", label: "Create the order", beats: [
+      { durationMs: 1000, caption: "Send the authorized request to the order service", actions: [
+        { type: "flow", target: "create", direction: "forward", text: "Create" }
+      ] },
+      { durationMs: 1000, caption: "Persist the new order", actions: [
+        { type: "flow", target: "persist", direction: "forward", text: "INSERT" }
+      ] }
+    ] },
+    { id: "response", label: "Publish and respond", beats: [
+      { durationMs: 1600, caption: "Publish OrderCreated and return the order number", actions: [
+        { type: "flow", target: "publish", direction: "forward", text: "OrderCreated" },
+        { type: "flow", target: "result", direction: "forward", text: "201 Created" },
+        { type: "flow", target: "request", direction: "reverse", text: "Order ID" }
+      ] }
+    ] }
+  ]
+};
+```
+
+At 4400 ms with the light theme, the event and response messages move together. Only their participating nodes are highlighted.
+
+![Order workflow with Client, API gateway, Auth, Order service, Orders database and Event queue; OrderCreated and response messages are in flight](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/quick-start.png)
+
+### 2. Evaluate and export SVG
+
+```ts
+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, 5200);
+```
+
+Both results are static SVG strings. Reuse `createDiagram` for repeated queries; use `renderSvg` for a single export.
+
+## 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>
+```
+
+Unmounting destroys the player. In scripts, call methods through `player.value`; templates unwrap the ref. Events pass their detail directly: `stepchange`, `timeupdate`, `playstatechange`, and `error`. Callback props are also supported.
+
+## React integration
+
+```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, without reapplying `initialTimeMs`. Reload documents with a new object reference. Handles expose seven methods listed under [Player API](#player-api); calls before mount or after unmount throw.
+
+Both entries support server-side imports. SSR renders a container; the player is created on client mount. Use `renderSvg` for server-side diagram previews.
+
+## Native browser
+
+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` replaces the container children. Call `destroy()` on disposal and before reusing the container. Plain HTML requires an import map or build tooling for package imports.
+
+The [native example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/README.md) demonstrates request/response flows. Its shared document also works with the other three integrations.
+
+## Web Component
+
+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;
+```
+
+Registration defaults to `<flowsvg-player>` and is idempotent. Assign objects to `element.document`, JSON strings to the HTML `document` attribute, or a JSON URL to `src`. URLs resolve against the page and follow browser CORS rules.
+
+Attributes: `autoplay`, `controls`, `speed`, `theme`, `reduced-motion`, and `hover-fill`. Controls default on; autoplay and hover fill default off. Use `controls="false"` to hide controls. Changes to theme, controls, or motion/hover options preserve time and playback state; `autoplay` explicitly starts or pauses playback. Removal cancels requests and destroys the player; reconnection uses the retained document.
+
+Methods: `play`, `pause`, `seek`, `step`, `setSpeed`, `getState`, and `destroy`. Update documents through `element.document`. Before mount or after destruction, `getState()` returns `undefined`. Playback/error events bubble across Shadow DOM boundaries.
+
+Register in a DOM environment. DOM-free imports are safe, but that module instance cannot register after a DOM is added later.
+
+## Documents and timelines
+
+| 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. Shapes: `rect`, `roundedRect`, `ellipse`, `cylinder`, `group`. `parentId` names a parent group; child coordinates are group-relative. Labels are plain text; `visible` defaults to `true`. Node styles: `fill`, `stroke`, `strokeWidth`, `textColor`, `dashed` (group borders). Edge styles: `stroke`, `strokeWidth`, `dashed`. Colors use hexadecimal RGB/RGBA, such as `#2563eb` or `#2563eb80`.
+
+Routes: `straight` (default), `orthogonal`, or `curved`. Curves follow endpoint ports without avoiding other nodes. Orthogonal routes avoid visible ordinary nodes and use a fixed fallback if blocked; shortest paths and zero crossings are not guaranteed. Set `fromPort` / `toPort` to `top`, `right`, `bottom`, or `left`. Explicit orthogonal ports reserve outward endpoint segments; curved ports set tangents. Omitted ports follow the dominant center-to-center axis; ellipse endpoints lie on the contour. Simple labels wrap by estimated width and remain visible on height overflow, with a `text-overflow` warning.
+
+Edges can connect nodes or group boundaries. Group endpoints follow evaluated geometry and explicit ports. Hidden ancestors mask connected edges. Transfers highlight the endpoint group, not its descendants. Group frames are excluded from routing obstacles.
+
+### Fixed-size node content
+
+`rect`, `roundedRect`, and `cylinder` support `content`; ellipses and groups support labels only. `content` and `label` are mutually exclusive, even with an empty label. `content.blocks` contains ordered `title`, `paragraph`, `list`, or `graph` blocks. Paragraph roles are `body` (default) and `auxiliary`. An empty block array displays only the shape.
+
+```ts
+import type { DiagramNode } from "flowsvg";
+
+const service = {
+  id: "service", kind: "rect", x: 24, y: 24, width: 260, height: 312,
+  content: {
+    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;
+```
+
+The `service` node rendered with the light theme:
+
+![Fixed-size Order service node with title, auxiliary text, body and a blue right-aligned paragraph](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/node-content.png)
+
+Text fields accept strings or `ContentTextSpan[]`: `{ text, style?: { fontSize, fontWeight, color } }`. Spans inherit block styles and share a baseline; alignment belongs to the block. Each line uses its largest font. Wrapping preserves newlines and Unicode graphemes, prefers English spaces, and breaks long words/URLs as needed. A grapheme spanning source styles uses its first character’s style. Layout uses width estimates, without DOM measurement.
+
+Text styles: positive finite `fontSize`, integer `fontWeight` from 100–900, hexadecimal `color`, and `align` (`left`, `center`, `right`). Content `padding` and `blockGap` are finite and nonnegative. Defaults in diagram units: title 20/700, body 14/400, auxiliary 12/400, padding 16, block gap 14. Line height is `max(20, fontSize × 1.35)`. Explicit colors override theme defaults.
+
+Lists accept `marker` (`none` by default, `bullet`, or `number`), `items`, and `style`. Items support `tags`, `status`, `body`, `auxiliary`, `style`, `auxiliaryStyle`, and `statusStyle`. List style sets body typography and nonnegative finite `itemGap` (default 12); item body style overrides it. Auxiliary text defaults to muted 12-unit text. Markers share a column followed by an 8-unit gap; continuation and auxiliary lines align with the body. Markers use the first present text baseline. Omitted items/parts take no space; explicit blank text preserves a line.
+
+```ts
+import type { ContentBlock } from "flowsvg";
+
+const steps: ContentBlock = { type: "list", marker: "number", style: { itemGap: 16 }, items: [
+  { body: "Validate the request.", auxiliary: "Input checks" },
+  { body: [{ text: "Save", style: { fontWeight: 700 } }, { text: " the order." }] }
+] };
+```
+
+The `steps` block rendered in a 300 × 180 rectangle with `content: { blocks: [steps] }`:
+
+![Two numbered steps with auxiliary text and bold Save text](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/numbered-list.png)
+
+Tags accept `{ text, style?: { fontSize, fontWeight, color, fill } }`. Defaults: font size 11, padding 6 horizontal / 2 vertical, corner radius 3. List `tagGap` defaults to 6 and must be finite and nonnegative. Status is right-aligned, defaults to 12-unit accent text, and accepts `fontSize`, `fontWeight`, and `color` in `statusStyle`. Tags and status share a baseline when they fit; otherwise tags wrap first and status moves below. Body and auxiliary text follow. Explicit colors/fills override the theme.
+
+```ts
+import type { ContentBlock } from "flowsvg";
+
+const records: ContentBlock = { type: "list", items: [{
+  tags: [{ text: "world" }, { text: "experience", style: { fill: "#eadfff", color: "#57319b" } }],
+  status: "new", body: "Alice joined Google", auxiliary: "Mar 2026"
+}] };
+```
+
+The `records` block rendered in a 300 × 180 rectangle with `content: { blocks: [records] }`:
+
+![Record with world and experience tags, new status, body and date](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/record-tags.png)
+
+Content keeps authored node dimensions. Safe areas reserve padding plus 4 units per side for rounded rectangles, or twice the cylinder cap radius above/below (`min(14, height / 4)`). Dimensions clamp to zero. SVG clips content to this area; width/height overflow emits `text-overflow` with node ID, `nodes[index].content`, and direction. Clipped text adds no hit area. Simple labels retain their separate overflow behavior.
+
+`EvaluatedNode.contentLayout` provides the safe area, lines/spans, tag backgrounds, optional graph primitives, and width/height overflow flags. Geometry is absolute and follows node resizing, parent movement, visibility, and opacity. Lines retain source block/item/tag indexes; `explicitColor` and `explicitFill` identify authored paint. Browser rendering and SVG export use the same layout. Content does not change ports, routes, transfer geometry, or parent relationships. See the [paragraph](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/node-content.html) and [list](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/list-content.html) examples.
+
+### Entity graphs inside nodes
+
+A `graph` block draws an undirected entity graph with authored local coordinates:
+
+```ts
+import type { ContentGraphBlock } from "flowsvg";
+
+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" }]
+};
+```
+
+The `entities` block rendered in a 280 × 180 rectangle with `content: { blocks: [entities] }`:
+
+![Entity graph with highlighted Alice and Google, and an unselected ML project](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/entity-graph.png)
+
+`height` reserves a positive fixed section. Entity centers use nonnegative finite `x`/`y` offsets from its top-left. IDs are local to each block; edges reference those IDs. Labels are 12-unit plain text above radius-4 dots. Highlighted entities use accent dots and bold labels; an edge uses accent paint when both endpoints are highlighted. Overflow reports its direction without shifting later blocks. Graphs share the parent clip and theme; interactions target the parent node.
+
+`contentLayout.graphs` contains absolute primitives and highlight state by `blockIndex`; labels join `contentLayout.lines`. Replace `content` to change selections at a beat start. See the [Hindsight example](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/hindsight.html).
+
+### Author a complete Facts timeline
+
+Choose fixed dimensions and ordered blocks. Use unmarked lists for records, bullets for capabilities, and numbers for steps. This document works with all four integrations:
+
+```ts
+import { createDiagram, type DiagramDocument, type NodeContent } from "flowsvg";
+
+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 });
+```
+
+The initial light-theme frame at 0 ms and the updated dark-theme frame at 1000 ms:
+
+![Facts timeline before and after record replacement, shown in light and dark themes](https://cdn.jsdelivr.net/npm/flowsvg@0.1.1/docs/images/facts-timeline.png)
+
+Check `frame.warnings` before sharing. Increase node dimensions or shorten overflowing text; the SDK does not resize nodes or shrink fonts. Prefer default colors for theme/highlight contrast. Content has one node-level interaction target, without internal links, buttons, images, or HTML.
+
+The [content story](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.html) combines Facts, lists, node updates, flows, and focus. Its [shared document](https://github.com/yokingma/FlowSVG/blob/HEAD/apps/native-example/content-story.js) also runs in the Vue and React examples.
+
+Each beat has a positive `durationMs` and an `actions` array, with optional `transitionMs` and `caption`. Transition duration defaults to `min(250, durationMs)` and must be within `[0, durationMs]`. An omitted caption inherits the previous caption; an empty string clears it.
+
+| 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 all content at beat start, regardless of transition duration, and persists across beats/scenes. `label` switches to simple-label mode; `content` switches to structured content. `content: null` clears either mode without restoring old labels or resizing. Assigning both modes, or assigning one repeatedly within a beat, produces a field-path error.
+
+```ts
+// Each value belongs to a separate beat's updateNode action.
+import type { NodeVisualState } from "flowsvg";
+
+const replacement: NodeVisualState = { content: { blocks: [{ type: "title", text: "Updated" }] } };
+const simpleLabel: NodeVisualState = { label: "Summary" };
+const clearText: NodeVisualState = { content: null };
+```
+
+Scenes share a millisecond timeline and inherit the previous scene’s final state. Text changes at beat start; interpolated values change during the transition. Beats include their start and exclude their end; the final time returns the completed frame. Hidden nodes/groups mask connected edges; showing them restores each edge’s saved visibility.
+
+A beat supports one transfer per distinct edge. Transfers share linear progress over `durationMs`, so longer paths move faster. Markers and endpoint highlights expire at beat end; the next beat supplies a new transfer group. Explicit highlights and ordinary styles persist.
+
+Transfer `text` is escaped, stays horizontal, and uses estimated capsule widths without font measurement. It does not replace the edge label or create an interaction target. An empty string still produces a capsule.
+
+## API
+
+### 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`: `{ theme?: "light" | "dark"; reducedMotion?: boolean }`. Times clamp to `[0, totalDuration]`; non-finite values become zero. Hit testing skips hidden/zero-opacity objects, then checks ordinary nodes, edges, and group backgrounds in that order.
+
+`DiagramFrameState` includes time, scene/beat IDs, progress, evaluated nodes/edges, camera, caption, and warnings. Coordinates are absolute. Static documents have `null` scene/beat IDs; beat IDs use `${scene.id}:${beatIndex}` with zero-based indexes. Active edges expose `flow` direction, progress, point, and optional text. Markers are absent after the beat, on hidden edges, or with reduced motion.
+
+Types and member JSDoc are included: `DiagramDocument`, `DiagramNode`, `DiagramEdge`, `Scene`, `Beat`, `Action`, `Diagram`, `DiagramFrameState`, `EvaluateOptions`, `ValidationIssue`, and `LayoutWarning`.
+
+### 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 controls enabled. Page hiding pauses playback; returning leaves it paused. Playback stops at the end; static diagrams disable timeline controls. Framework handles expose these methods except `element` and `destroy`.
+
+Hover highlights the current node’s border, including hits on labels or content. Set `hoverFill: true` to include background and content paint, including groups. Leaving removes only the hover highlight; active flow/explicit highlights remain. Frame updates recheck stationary pointers. Pointer cancellation, successful document replacement, and destruction clear hover.
+
+Default content colors adapt to the theme and highlight fill; authored colors and tag fills stay unchanged. Highlighting preserves layout and hit bounds. Content interactions report the parent node; clipped text adds no hit area.
+
+`PlayerState.frame` and static SVG 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 detail contains `id`, `type`, `point` (document coordinates), `timeMs`, `sceneId`, and `beatId`; misses return `null`. Adapters forward the four playback/error events. Web Component errors before mount may lack player state.
+
+`hover` also updates when a frame change moves another object under a stationary pointer. Pointer leave/cancel emits `null`.
+
+```ts
+import type { PlayerEventMap } from "flowsvg/browser";
+
+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: explicit option → document theme → light. The core ignores system preferences. Browser motion follows `prefers-reduced-motion` unless overridden; the core defaults to full motion. Reduced motion completes transitions immediately and hides transfer markers, preserving duration.
+
+Defaults use neutral borders and edges with blue emphasis:
+
+| Paint | Light | Dark |
+| --- | --- | --- |
+| Background / node fill | `#ffffff` / `#ffffff` | `#101828` / `#1d2939` |
+| Node border / text | `#cfd8e3` / `#1d2939` | `#475467` / `#f2f4f7` |
+| Edge | `#8892a4` | `#98a2b3` |
+| Highlight fill / border | `#eaf1ff` / `#2a63c8` | `#233b60` / `#8ab4f8` |
+| Flow marker / marker text | `#2a63c8` / `#ffffff` | `#8ab4f8` / `#101828` |
+
+Default node borders are 1.2 diagram units; edges are 2. Rounded rectangles use a radius of at most 8. Node labels use plain text; edge labels retain a background halo for readability across paths. Diagram text uses system fonts with Chinese fallbacks. Explicit styles replace ordinary defaults; timeline and hover highlights overlay those styles and restore the current ordinary paint when removed.
+
+Import `flowsvg/styles.css` for control layout and focus styles. CSS variables customize controls only; core themes and document styles determine diagram colors:
+
+```css
+.flowsvg {
+  --flowsvg-control-background: #101828;
+  --flowsvg-control-color: #f4f7fb;
+  --flowsvg-control-border: #64748b;
+  --flowsvg-control-accent: #60a5fa;
+  --flowsvg-control-focus: #fbbf24;
+}
+```
+
+Add `flowsvg` to a native host to apply these variables; framework components add it automatically. With canvas focus, Space toggles playback and arrow keys step through beats. Form controls keep native keys. Captions use a polite live region; SVGs have accessible names.
+
+## Validation and errors
+
+Validation rejects unknown fields, bad references, cyclic groups, duplicate beat assignments, invalid colors, and invalid dimensions/durations. Text is escaped. For external JSON, call `validateDocument` and inspect each issue’s `path` and `message`.
+
+`createDiagram` and initial `createPlayer` calls throw `DiagramValidationError` for invalid documents. Its `issues` contain field paths. Later `load` failures emit `error` and retain the old state. Text overflow is nonblocking; inspect `frame.warnings`.
+
+Duplicate `flow` actions on one edge report `duplicate beat assignment` at the later `target`, regardless of direction, text, or other field errors. Flows may coexist with visibility, explicit highlight, and style actions.
+
+## License
+
+[MIT](LICENSE). Use, modify, and distribute with the license and copyright notice retained.