flowsvg 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+## 0.1.1 - 2026-10-20
+
+- Adopted thin neutral node borders, gray edges and blue emphasis in both themes. Separate highlight fills from borders and flow markers, remove the node-label halo, and refresh README previews.
+
+- Expanded the quick-start document to a six-node order workflow with authorization, persistence, asynchronous events and reverse responses.
+
+- Added SDK-rendered previews beside the quick-start, structured-content, list, entity-graph and Facts timeline examples in both package READMEs.
+
+- Include the eight README preview images in the npm tarball. Source READMEs use relative image paths for local previews; the release verifier prepares staged README copies with versioned npm CDN URLs for public readers. Release verification requires every preview and rejects undeclared documentation assets.
+
+- Removed local build, source-layout and release instructions from the package READMEs; repository documentation retains the contributor workflow.
+
+- Completed bilingual module navigation, updated migrated test links, and consolidated architecture implementation and verification records.
+
+- Grouped React, Vue, and Web Component implementations under `src/adapters/` while keeping explicit root entries, shared Web Component registration identity, SSR-safe imports, lifecycle behavior, and cross-host integration tests. Updated nested release artifacts and consumer references.
+
+- Grouped the browser player implementation and its controls, accessibility, lifecycle, and SVG DOM modules under `src/browser/` while preserving the `flowsvg/browser` entry, lifecycle behavior, DOM-free imports, and public player contract. Updated browser tests and release allowlists for nested build output.
+
+- Moved shared hexadecimal color interpolation to the pure `src/core/color.ts` module. Timeline evaluation and diagram paint share the same runtime helper; content painting checks contrast without a timeline dependency.
+
+- Centralized edge routing, path sampling, distance queries, label anchors, hit testing, and SVG number formatting in `src/core/edge-geometry.ts` and `src/core/svg-number.ts` while preserving the existing public frames and SVG output.
+
+- Organized the platform-independent core into shared model, document validation and diagram orchestration modules. Preserved all public values/types, error identity and evaluation behavior; grouped core tests with their implementation.
+- Preserved nested JavaScript and declaration build output and replaced the release file pattern with an explicit module allowlist that rejects source, tests and unrelated files.
+
+## 0.1.0 - 2026-10-17
+
+- Added a release CLI that runs type checks, SDK and release-script tests, tarball consumer verification, example builds and npm publication preview. Default to preview; require `--publish` for upload, and publish the exact verified tarball retained in `dist/releases/`.
+
+- Require Vue 3.5+ and build its declarations against Vue 3.5.0. Verify strict consumer types and server rendering with minimum supported React 18.0.0 / Vue 3.5.0 as well as current framework releases.
+
+- Prepared the first npm release with repository metadata, public registry settings, bilingual package documentation, automatic prepack builds and prepublish type/test checks.
+- Verify packaging from a missing `dist`, every exported JavaScript/type/CSS target, the file allowlist, framework-free imports, strict consumer types and all four host lifecycles.
+
+- Renamed the package and SDK directory to `flowsvg`. Player exports now use the `Flow` prefix: `FlowPlayer`, `FlowPlayerProps`, `FlowPlayerHandle`, `FlowPlayerElement`, `defineFlowPlayer()` and `FLOW_PLAYER_TAG`. The default element is `<flowsvg-player>`; CSS classes and control variables use `flowsvg-` and `--flowsvg-`. Imports, selectors and public API references must use the new names.
+
+- Fixed cylinder SVG fills by rendering the top cap as a separate filled ellipse inside the same node interaction group, so the cap no longer appears hollow.
+
+- Default hover now highlights only borders for all nodes and groups, preserving timeline fill and content paint. Enable background hover with `hoverFill: true` in native/React/Vue integrations or `hover-fill` on the Web Component.
+
+- Added group-boundary edge endpoints and decorative, fixed-coordinate entity graphs inside structured node content.
+- Preserve graph selection during parent highlights and report local graph overflow without shifting following content blocks.
+
+- Added shared content-story acceptance through all four hosts, complete bilingual Facts authoring examples and packed NodeContent replacement/clear checks, including Vue handle and cleanup assertions.
+
+
+- Kept structured-content role colors readable under explicit, flow and browser hover highlights, including intermediate fill transitions. Shared paint preserves authored colors/fills and all text/clip geometry. Added core and DOM regression coverage plus a real-pointer fixture for content/tag hits, clipped bounds, stationary content/mode/size updates, theme reload and destruction.
+
+- Added Facts text tags, multiple tag rows and right-aligned status, shared mixed-font baselines, theme defaults, explicit fill/text provenance, strict nested validation, padded tag geometry and escaped SVG backgrounds. Narrow metadata wraps before body/auxiliary text without resizing nodes.
+
+- Added fixed-node unmarked, bulleted and numbered lists with shared marker columns, wrapped body indentation, optional muted auxiliary text, controlled item styles/spacing, exact nested validation paths and public list indices. Width warnings include reduced body columns, even for right-aligned oversized glyphs. Browser and static SVG reuse the same evaluated lines.
+
+- Added whole `updateNode.value.content` replacement at the beat start, inherited across beats and scenes. Label/content updates switch display modes; `content: null` clears text without restoring historical labels or resizing nodes. Strict validation rejects dual-mode and conflicting beat assignments.
+
+- Added inline text spans with controlled font size, weight and color, shared baselines, per-line heights, public evaluated span geometry, and escaped SVG tspans. Wrapping preserves full Unicode graphemes across source spans, explicit blank lines, English word boundaries, CJK and long URLs without DOM font measurement.
+
+- Added fixed-size content on rounded rectangles and cylinders, with contour clearance before authored padding, current-geometry safe areas during node/group movement and resize, and nonnegative clipping for tiny shapes. Verified that ports, straight/orthogonal/curved routes, focus, and transfers keep their geometry.
+
+- Added initial fixed-size rectangle `content` with ordered titles, paragraphs, auxiliary text, controlled typography/spacing, strict nested validation, evaluated content geometry, safe-area clipping, and directional overflow warnings. Preserved simple-label behavior and added a standalone native example for both themes.
+
+- Preserved collinear cubic reversals in shared geometry so flow distance, hit tests, focus bounds, and labels follow the visible curve. Explicit orthogonal ports now reserve outward endpoint segments and route around endpoint bodies without changing automatic routes. Refreshed public geometry, inherited-state, and reduced-motion JSDoc contracts.
+
+- Replaced the native story with a fixed-view request/response example using curved ports, three-then-two synchronized transfers, dots, text capsules, reverse messages, shared participants, and hover. Added a shared-document integration check through native, Web Component, React, and Vue public controls for both themes and reduced motion.
+
+- Added browser node hover highlights across shapes and nonempty labels, including overflowing wide Unicode glyphs. Hover combines with flow and explicit highlights, follows stationary pointers across frame updates, and clears on leave, cancellation, document replacement, and destruction without changing core frames or SVG exports.
+- Rendered optional `flow.text` messages as horizontal text capsules with deterministic Unicode width estimates, escaped SVG text, and decorative pointer behavior. Message text stays local to its beat; omitted text retains the solid dot. Added browser export and theme checks for request/response capsules.
+
+- Verified parallel transfer groups across beats and scenes, including mixed directions, unequal path lengths, shared-node highlights, seeking, playback speed, reduced motion, and final cleanup. Duplicate flow targets are now reported even when another field on the first flow is invalid.
+
+- Added beat-local `flow` actions for deterministic forward or reverse transfer markers on existing edges. Active transfers highlight the edge and both endpoint nodes, respect visibility and reduced-motion options, and are included in static SVG exports.
+- Added curved edge routing with automatic or explicit cardinal ports. Curved path geometry is shared by SVG output, labels, focus bounds, hit testing, and deterministic opposite-direction separation; endpoint tangents follow the selected port normals.
+
+- Unified evaluated straight and orthogonal edge geometry for SVG paths, labels, focus bounds, hit testing, and distance-based sampling while preserving the existing public path output.
+
+- Improved SVG readability: edge labels use the longest route segment with a background halo, micro-detour turns are widened when safe, and group borders can render as dashed lines. Refined the native example layout to avoid overlapping nodes and response edges.
+
+- Expanded the native browser example into a five-scene order request story covering authentication, cache/database persistence, asynchronous queue processing, analytics, and response handling. Added focus, dynamic label/style updates, and live playback status.
+
+- Fixed focused SVG backgrounds so they cover offset cameras in both the browser and static exports.
+- Matched hit-test priority to SVG paint layers so group backgrounds cannot intercept foreground nodes or edges.
+- Attached straight edges to ellipse contours instead of their rectangular bounds.
+- Preserved Unicode surrogate pairs when wrapping narrow node and edge labels.
+- Kept the React speed prop applied when theme, controls or motion options recreate the player.
+- Removed duplicate Vue onError notifications for a single failed document load.
+- Prevented duplicate animation loops when playback restarts synchronously from player event listeners.
+- Preserved paused and playing Web Component states across visual-option rebuilds instead of reapplying autoplay.
+- Gave each exported or mounted SVG its own accessible name without duplicate title ID references.
+- Added real React mount, props, playback, reload and unmount assertions to tarball release verification.
+
+- 补充核心、时间线、播放器及框架接入的职责和契约注释，展开密集声明与语句，便于源码阅读及编辑器类型提示。
+
+- Strengthened tarball release verification with a real `<flowsvg-player>` lifecycle smoke test that mounts an object document, plays, reloads, inspects state, removes the element, and confirms cleanup.
+- Prepared the public npm package with root, browser, element, Web Component, React, Vue and stylesheet exports, MIT metadata, Node/browser support guidance, performance guidance, and a clean tarball release verification command.
+- Added the SSR-safe `flowsvg/vue` entry with typed props, player events, exposed controls, client lifecycle cleanup, document reloads, and optional Vue peer dependency metadata. Added a built-artifact Vue example.
+
+- Added the SSR-safe `flowsvg/react` entry with typed props, event callbacks, an imperative ref handle, client lifecycle cleanup, document reloads, and optional React peer dependency metadata.
+
+
+- Added interpolated focus cameras with aspect-preserving viewBox snapshots, document-coordinate hit testing, and browser hover/click interaction events that exclude hidden objects.
+- Added the explicit `flowsvg` Web Component entry. `defineFlowPlayer()` is SSR-safe and idempotent; the element accepts object or JSON documents, URL sources with stale-request cancellation, autoplay, controls, speed, theme and reduced-motion attributes, forwards typed player events, and tears down on disconnect.
+- Added explicit light/dark visual options, fully resolved evaluated styles, self-contained accessible SVG titles and the `flowsvg/styles.css` control stylesheet.
+- Added canvas keyboard playback/stepping, visible focus styles, and automatic reduced-motion preference updates with explicit overrides and listener cleanup.
+
+- Added deterministic node and edge visual updates with cubic geometry, numeric style and RGBA color interpolation, immediate label changes, and exact numeric transition endpoints.
+- Preserve ordinary styles beneath highlights, recompute nested group geometry and orthogonal routes for every frame, and verify dynamic SVG equality in a real browser.
+
+- Added transactional document reloads, visibility-driven pause, silent idempotent teardown, and responsive aspect-preserving container sizing.
+- Verified repeated creation/reloads/destruction, disabled controls, error field paths and event consistency in Chromium.
+
+- Added progress, adjacent beat stepping, scene selection and playback speed controls with synchronized typed timeline events.
+- Preserve rendered SVG object elements across frame updates and verify seek/playback/static-export equality in a real browser.
+
+- Added a compiled continuous narrative timeline, inherited scene state, synchronized visibility fades, highlight transitions, and browser play/pause captions.
+
+- Added the platform-independent static diagram compiler, evaluator, and SVG exporter.
+- Added the browser `createPlayer` entry and native static example.
+- Added nested group coordinate resolution, all first-release node shapes, deterministic label wrapping, and layout overflow warnings.
+- Added strict document validation for schema fields, references, timeline values, styles, and actions.
+- Restored deterministic orthogonal edge routing with boundary attachments, obstacle avoidance, stable fallback paths, and SVG direction markers after integrating shape and text layout.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zac_ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PATTERNS.md

@@ -0,0 +1,112 @@
+# Patterns
+
+- Keep default diagram colors and line metrics in the core theme. Use separate highlight fill, border/marker and marker-text colors so active nodes retain readable text in both themes. Browser hover consumes the same theme values; preserve border-only hover by default. Node labels have no halo; edge labels retain background isolation where paths cross text.
+
+- Keep README previews in `docs/images/` inside the SDK package. Package only PNG assets and enumerate the expected images in the release verifier; require each image and reject undeclared files. Use relative image paths in source READMEs for local previews. The release verifier unpacks the built package into a temporary directory and converts only its README copies to npm CDN URLs with the package version. Repack without lifecycle scripts, require the packed file set to remain unchanged, then verify and retain that final tarball. Source READMEs must remain unchanged by release verification.
+
+- Keep shared document/frame types in `src/core/model.ts`, document validation and its single error class in `validation.ts`, and compilation, cloning/freezing, evaluation, SVG and hit-test orchestration in `diagram.ts`. Node-content types and nested validation remain in `node-content.ts`. Import runtime owners directly; use type imports for shared model dependencies.
+- Enumerate public values and types in the root entry, including `wrapText`, `Diagram` and all node-content types. Keep core contract tests in `src/core/` and consume public entries. Four entry-specific TypeScript builds preserve the internal directory hierarchy under `dist`; enumerate each emitted module in the release allowlist instead of accepting arbitrary files below `dist`.
+- Keep the browser player implementation under `src/browser/player.ts`, with controls, accessibility, lifecycle, and SVG DOM synchronization beside it. Keep `src/browser.ts` as the explicit public entry; browser tests use that entry while core remains DOM-free.
+- Keep React, Vue, and Web Component implementations under `src/adapters/`; root adapter files are explicit public entries that export the single implementation and preserve runtime identity. Adapter tests live beside their implementations and cross-host business scenarios live under `tests/integration/`; imports use public entries.
+- Keep color interpolation in the pure `src/core/color.ts` module. Timeline and diagram painting import it directly so generic color rules do not depend on timeline semantics. Content highlight paint retains theme-specific semantic colors and adjusts default ink only when the evaluated fill requires more contrast.
+- Keep route construction, path measurements, label anchors, and path hit testing in `src/core/edge-geometry.ts`; share integer and three-decimal formatting through `src/core/svg-number.ts`. Diagram orchestration consumes these internal results without exposing geometry.
+
+- Run release gates sequentially through the root release CLI. Default to a preview without authentication; check authentication before the gates only for explicit publication. Copy the verified tarball after all consumer checks pass, then preview and publish that file without repacking. Stop on any command failure and keep npm stdio attached for authentication prompts.
+
+- Build Vue declarations against the pinned minimum supported version, 3.5.0; newer Vue patch releases can add inferred `DefineComponent` type parameters that older consumers cannot read. Verify both minimum and current framework versions in the packed-package consumer.
+
+- Build through `prepack` so `npm pack` and directory publishing cannot use missing or stale artifacts. Keep publish-only type/test checks separate from packaging to avoid recursive release verification. Verify the packed exports and strict consumer types before publishing.
+
+- Use FlowSVG as the display name. Publish the SDK as `flowsvg` from `packages/flowsvg`. Use the `Flow` prefix for player exports, `<flowsvg-player>` for the default custom element, and `flowsvg-` / `--flowsvg-` for CSS classes and control variables. Keep package imports, declarations, examples and release verification aligned with these names.
+
+- Apply hover to stroke only by default for every node and group. Preserve core fill and content paint, including active flow or explicit highlights. With `hoverFill: true`, paint fill and readable content as well. Forward the same option through every adapter and restore the current core SVG when the pointer leaves.
+
+- Serialize cylinders as one keyed interaction group containing a filled body and a filled top ellipse. Keep the cap separate from the body path so SVG fill rules cannot create an interior hole, while shared group paint keeps hover and timeline updates consistent.
+
+- Use evaluated group rectangles as ordinary edge endpoints. Keep group frames out of global routing obstacles; apply endpoint/ancestor masking and beat-local flow highlights to the group itself.
+- Keep entity graph IDs local to a content block. Derive absolute primitives and text from authored local coordinates, serialize inside the parent clip, and retain the parent node as the sole interaction identity.
+- Preserve local graph selection in evaluated primitives. Parent timeline/hover paint must keep selected and ordinary entities distinguishable, and graph overflow must not change the following block's authored position.
+
+- Verify combinations through one authored content story and public host handles. Compare core frames/SVG across theme and motion options; assert record replacement/mode semantics independently. Packed release smoke must inspect Vue mounting and content updates, not only mount/unmount.
+
+
+- Apply one content-paint function after core layout for timeline highlights and again to current DOM children for browser hover. Preserve explicit color/fill provenance and reuse current geometry. During fill transitions, check default ink against the evaluated node or tag fill and select contrasting ink when interpolated colors lose readability. Restore the current core SVG before hover paint; never restore saved markup or mutate core frames. Content children remain decorative within one node target.
+
+- Lay out tags in authored rows before status and body. Share a metadata baseline only when natural widths fit, preserve grapheme wrapping inside padded tag boxes, and expose background geometry and explicit-fill provenance alongside text spans. Serialize decorative backgrounds inside the same clip without extra node identities.
+
+- Lay out list entries through the shared deterministic text-part function. Reserve one list-wide marker column and align each marker with the first present text baseline; preserve source item indices and omit height/gaps for absent entries. Aggregate text-part width overflow before checking the outer clip, so alignment cannot conceal an insufficient body column. Include indentation when checking width overflow, and inherit only controlled text fields without allowing undefined item overrides to discard list defaults.
+
+- Store node content in inherited timeline snapshots. Clear the other display mode when applying label/content updates, including `content: null`. Use target text values even at zero transition progress; geometry and paint continue interpolating. Reserve one shared beat assignment key for both node text modes, and validate content with the same nested schema used by initial nodes.
+
+- Segment combined content with `Intl.Segmenter` before applying source styles, so inline boundaries cannot split graphemes or create extra wrapping opportunities. Use the cluster start style for cross-span clusters. Resolve each line's maximum font, shared baseline and left-positioned spans once in the core; preserve author-color provenance and serialize escaped tspans from those results.
+
+- Compute content safe areas from current absolute node geometry. Reserve rounded-corner or cylinder-cap clearance before authored padding, clamp empty dimensions to zero, and use the same area for public layout and SVG clipping. Share the supported-shape predicate between initial content and timeline content validation; keep content separate from node-parent, port, route, focus, and transfer geometry.
+
+- Keep structured node content in a deterministic module that accepts current absolute geometry and a resolved theme. Return the complete layout plus a nonnegative safe area, then consume those same lines and clip geometry in SVG. Keep content child groups keyed separately from the node shape; only the shape uses its node `data-id`. Validate controlled nested fields before cloning, and preserve simple-label overflow behavior.
+
+- Preserve collinear extrema when compacting path points: a reversal contributes distance and bounds even when all samples lie on one axis. For explicit orthogonal ports, reserve outward endpoint stubs before grid search and include inflated endpoint bodies among middle-route obstacles; leave fully automatic routing unchanged.
+
+- Keep hover in the browser paint layer: restore the current core SVG before applying a hovered node's shared-theme highlight colors. Re-hit the saved screen position through the updated camera after each frame. Include nonempty node label bounds using the capsule's shared width estimate for wide characters. Clear interaction causes on pointer cancellation, successful load, and destroy. Never write hover into the core frame or timeline; removing hover must expose the current explicit/flow highlight or ordinary style.
+- Render transfer text from the evaluated beat-local `flow.text`, without changing the edge label. Estimate capsule width by Unicode code points with full-em space for wide characters, retain horizontal text, escape plain SVG content, and disable marker pointer handling. Verify current browser messages and static SVG equality with `tests/browser-flow-text.html`.
+
+- Treat each beat’s transfers as a synchronized group: derive all marker positions from the same linear progress and union endpoint highlight reasons. Reject a second flow for the same edge regardless of direction or other field errors; keep flow assignments separate from visibility, explicit highlights, and base updates.
+
+- Compile `flow` actions as beat-local state: use the full beat progress for distance-based marker sampling, keep static edge arrows unchanged for reverse transfers, and derive temporary edge/endpoint highlights during frame evaluation so they expire without overwriting explicit highlights or ordinary style updates.
+- Generate curved routes from cardinal port normals and use the same sampled geometry for path consumers. Keep endpoint control points on the outward side of each port so the path enters the target along the inverse normal; separate reverse relationships with a deterministic perpendicular lane.
+
+- Keep the native business example in a fixed view: use the same document across public integration checks, synchronize three request paths then two processing paths, and return messages through reverse flows and a separate response relationship. Compare public frame/SVG output at beat boundaries rather than adding adapter clocks or test-only APIs.
+- Place labels on the longest segment of a routed edge and give them a background halo; remove only collision-free micro-turns so arrow paths remain orthogonal and readable.
+
+- Draw the SVG background at the evaluated camera's x/y/width/height; percentage dimensions at the document origin do not cover an offset viewBox.
+- Hit-test ordinary nodes, edges, then group backgrounds, reversing document order within each layer to match SVG paint priority.
+- Project straight edge endpoints onto ellipse contours with normalized ellipse coordinates; preserve cardinal attachment sides for orthogonal routes.
+- Estimate and slice wrapped text by Unicode code point, so narrow labels cannot split surrogate pairs before SVG export.
+- Apply current playback props to every newly created framework player; an effect keyed only by speed cannot initialize replacements when speed is unchanged.
+- Vue's emitted `error` event already calls `onError`; do not call the same prop manually after emitting it.
+- A player owns at most one pending RAF: clear the consumed handle on tick entry and reuse guarded scheduling after events, because listeners can pause and restart synchronously.
+- Web Component option rebuilds restore the prior time/playback state before starting playback; autoplay governs fresh mounts, not rebuilds of a user-paused instance.
+- Name SVG images directly with escaped `aria-label` and retain a readable `<title>`; document-wide ID references must not couple independent deterministic exports.
+- Release smoke tests await React `act` to flush mounting and cleanup, assert SVG and ref state, exercise playback/reload, then verify unmount cleanup; scheduling a render alone proves no client behavior.
+
+- 源码注释遵循 [注释维护规范](https://github.com/yokingma/FlowSVG/blob/HEAD/docs/agents/code-comments.md)：公开 API 说明行为契约，内部实现说明原因与约束，重要模块说明职责；修改实现时同步核对相邻说明。
+
+- Keep release verification outside the published files: build once, pack the exact tarball, install it in a temporary project with each optional framework peer, import every public entry in Node, create a real `<flowsvg-player>` element to exercise object-document assignment, play/load/state, removal and cleanup, and mount/unmount the native, React and Vue adapters in a DOM smoke test. Keep the package ESM-only and declare CSS as a side effect so bundlers retain control styles.
+
+- Derive focus camera bounds from evaluated geometry and interpolate camera state with the same transition progress as visual values; serialize that camera into the SVG viewBox so static export and browser frames stay equal. Map browser pointer coordinates through the live SVG viewBox before calling the core hit-test seam, and ignore objects whose effective opacity is zero.
+- Keep Web Component registration explicit and idempotent; never touch `customElements` or instantiate a browser player during module evaluation. Convert object/JSON attributes at the element boundary, validate before replacing the current document, and guard URL responses with an abort controller plus request token so stale loads cannot win. Forward player events with bubbling/composed details and destroy the wrapped player on disconnect.
+
+- Keep the React entry as a lifecycle adapter around `createPlayer`: instantiate only from an effect, remove event listeners before destroying a replaced player, and expose the browser player's methods through `useImperativeHandle`. Importing the entry must remain DOM-free for SSR; `initialTimeMs` applies once per mounted component.
+- Keep the Vue entry as a `defineComponent` lifecycle adapter around `createPlayer`: instantiate only from `onMounted`, detach events before `onBeforeUnmount`, and expose the browser player methods with setup `expose`. Importing the entry must remain DOM-free for SSR; `initialTimeMs` applies once per mounted component and option changes recreate the browser player.
+
+- Pass serializable theme and reduced-motion values from the browser to the core; explicit options override document theme and browser motion preferences. With no theme, use light without reading the system color scheme.
+- Resolve all diagram paint and typography in the core SVG; CSS variables customize controls only. Give each SVG its own accessible name without cross-player title ID references.
+- Scope Space/Arrow shortcuts to the focusable canvas and preserve editable/native control keys, key modifiers and repeated key behavior. Own keyboard/media-query listeners and detach them on destroy.
+- Verify automatic reduced motion with real browser media emulation at a fixed transition midpoint; compare player SVG with the core export using the same options. Accessibility checks live in `tests/browser-accessibility.html`.
+
+- Compile ordinary visual values independently of visibility/highlight layers; interpolate base colors first and apply the highlight color afterward, regardless of action order within a beat.
+- Keep theme defaults unresolved until evaluation so interpolated source colors follow the caller's theme. Labels change at beat start; numeric endpoints return exact values and weighted interpolation avoids overflowing a finite endpoint difference.
+- Resolve parent-relative positions and text dimensions from current visual values on each frame before routing against effective visible obstacles; reveal begins blocking at zero opacity and hide stops blocking only when its transition finishes.
+- Validate dynamic browser/core/export equality with `tests/browser-visual-updates.html` at transition starts, middles and ends for both themes and reduced motion settings.
+
+- Validate and compile replacement documents before pausing or replacing a valid player; a failed load reports the retained state with validation field paths.
+- Mark players destroyed before cancelling scheduled work and detaching document listeners; guard event dispatch and rescheduling against destruction during event handlers.
+- Use native flex layout and SVG aspect-preserving scaling for responsive containment, so container changes need no ResizeObserver or resize listener. Restore host styles when tearing down.
+- Run lifecycle checks from `tests/browser-lifecycle.html` in Chromium after building; observe public state, events, rendered geometry and post-destroy behavior.
+
+- Derive controls, captions and typed `stepchange`/`timeupdate`/`playstatechange` events from one evaluated player state; error details include that same state and a typed error.
+- Step to the closest beat start strictly before/after the current time and pause; previous from inside a beat returns to that beat start, while previous at its exact start selects the preceding beat.
+- Apply the core SVG serialization to retained DOM elements keyed by object ID; preserve live object interactions while synchronizing attributes, labels and paint order.
+- Browser behavior checks live in `tests/browser-controls.html`; build first, serve the repository root and inspect `window.browserTestResults` in a real browser.
+
+- Compile beat offsets and before/after visibility and highlight layers once; evaluate the active beat with a binary time lookup and fixed cubic transitions.
+- Keep edge visibility independent from endpoint masking; effective opacity is the minimum of the object, ancestor groups, and endpoints, never multiplied.
+- Derive browser SVG and captions from the same compiled core timeline used by static export.
+
+- Keep document compilation and SVG serialization platform independent. The core package does not read browser globals, use a clock, or make network requests.
+- Compile by cloning and freezing serializable input so later caller mutations cannot change a `Diagram` result.
+- Test the public seams (`createDiagram`, `Diagram.evaluateAt`, `renderSvg`, and browser entry imports) rather than private rendering helpers.
+- Resolve child geometry and inherited visibility during frame construction; SVG serialization consumes the same evaluated lines and geometry as browser output.
+- Keep text wrapping deterministic with fixed typography metrics and retain all lines, reporting overflow through `LayoutWarning` entries with object identifiers.
+- Validate every document field and reference before compilation; reject unsafe colors and duplicate timeline assignments with field paths.
+- Route orthogonal edges against evaluated absolute geometry and inherited visibility; exclude group frames from obstacles and serialize direction markers with the same paths.
+- Build each evaluated edge once as internal path geometry with its serialized path, points, length, bounds, and distance-based sampling; use that geometry for labels, focus bounds, hit testing, and active flow sampling so consumers cannot drift apart.