flowchart-sequence-designer 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,159 @@
+# Changelog
+
+All notable changes to `flowchart-sequence-designer` are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- `themeOverrides` prop on `DiagramEditor` and `SequenceEditor` — a
+  `Partial<ThemeColors>` (or `Partial<SequenceThemeColors>`) shallow-merged on
+  top of the resolved light/dark palette so consumers can match the editor to
+  their brand without forking. `ThemeColors` and `SequenceThemeColors` are now
+  exported from `flowchart-sequence-designer/ui`.
+- Multi-selection on the canvas. `Shift+click` a node to toggle it in/out of
+  the selection. `Shift+drag` on the empty canvas runs a box-select (adds
+  every intersected node to the current selection). `Delete`, `Ctrl+D`, and
+  arrow-key nudging now apply to every selected node. Dragging any selected
+  node moves the whole group. The Delete button in the controls bar shows the
+  current count when more than one node is selected.
+- `Ctrl+C` / `Ctrl+V` copy and paste. Copy snapshots the selected nodes plus
+  the edges that connect them, paste materializes fresh IDs offset by 24px
+  and re-selects the new nodes.
+- Alignment guides and snap-to-sibling. When dragging a single node, dashed
+  indigo guide lines appear whenever its left/center/right or top/middle/
+  bottom edge lines up with another node, and the position snaps within a
+  4-pixel threshold. Group drags preserve relative offsets and skip the snap.
+- Edge waypoint rerouting. Hover an edge to reveal a handle at its midpoint;
+  drag it to set a manual routing waypoint and the edge re-renders as two
+  smooth bezier segments through that point. `DiagramEdge.waypoint` is
+  persisted in JSON exports and ignored by the Mermaid / PlantUML serializers
+  (those formats don't encode routing). Right-click an edge → "Reset routing"
+  to clear the waypoint.
+- Touch long-press opens the canvas context menu (Add node here, Re-center,
+  Undo, Redo). Significant finger movement cancels the gesture.
+- Port circles grow from 6 to 9 px on `(pointer: coarse)` devices and stay
+  permanently visible (instead of fading in on hover) so they're tappable on
+  touch.
+- `Alt+Arrow` traverses the graph from the currently selected node — picks the
+  nearest sibling in the chosen direction (45° cone, Euclidean nearest). Plain
+  arrow keys still nudge as before; the `Alt` modifier disambiguates.
+- Focus-visible outlines on every focusable control inside the editor (buttons,
+  inputs, role="button" nodes, the canvas itself) using the active accent
+  color, so keyboard users always see where focus lives.
+- `bun run analyze` — esbuild-metafile bundle analyzer that prints minified
+  bundle size + top input contributors per entry point, and writes
+  `dist/.metafile-{core,ui}.json` for a visual treemap on
+  esbuild.github.io/analyze. Useful before shipping any bundle-shape change.
+- Built-in sample diagrams. `DiagramEditor` and `SequenceEditor` now fall
+  back to a small working preset when mounted without `initialModel` — a
+  6-node order-flow for the flowchart variant, a 3-answer role picker for
+  question, a 5-step onboarding for journey, and a 3-actor login handshake
+  for sequence. New exports `presetFlowchartModel(variant?)`,
+  `presetSequenceModel()`, and `emptyModel(type, variant?)` (the latter is
+  the opt-out for consumers who explicitly want a blank canvas).
+- Demo (live site) gains a Sequence tab so all four variants are
+  reachable from the same nav, each booting with its preset diagram.
+- Import dialog. Clicking **↑ Import** in the toolbar now opens a proper
+  modal with a paste-area, a file picker (`.json` / `.mmd` / `.mermaid` /
+  `.txt`), live format detection (`{` → JSON, otherwise Mermaid), error
+  feedback, focus trap, and Esc/backdrop dismissal. Replaces the previous
+  `window.prompt()` one-liner that couldn't fit a multi-line Mermaid graph
+  or accept file uploads at all.
+
+### Changed
+- Internal refactor: the 1500-line `DiagramEditor.tsx` monolith is split into
+  focused modules (`layout.ts`, `theme.ts`, `render.tsx`, `NodeNavigator.tsx`,
+  `ContextMenu.tsx`, `hooks/useHistory.ts`, `hooks/useSystemTheme.ts`). No
+  public API or visual change — the file is now ~770 lines and the render
+  layer can be imported in isolation.
+- Further refactor: extracted three more canvas hooks —
+  `hooks/useCanvasWheel.ts` (cursor-anchored zoom), `hooks/useCanvasTouch.ts`
+  (pan/pinch/long-press), and `hooks/useElementSize.ts` (ResizeObserver
+  viewport tracking) — and added a `nodeDims(node, variant)` helper to
+  `layout.ts` that collapses the repeated `variant === 'question' ? ... : ...`
+  width/height ternary. `DiagramEditor.tsx` is now ~990 lines.
+
+### Fixed
+- Sequence diagram new-message ID collision. `addMessage()` minted IDs from
+  a module-level counter starting at zero, so the first added message got
+  `m1` — the same ID as the preset's first message. Selection state holds
+  one ID, so clicking the new row highlighted both rows that shared the
+  collided ID. Replaced with `nextMsgId(messages)` which scans existing
+  IDs matching `/^m(\d+)$/` and returns `m{max+1}`, eliminating any chance
+  of collision with the preset or with imported diagrams.
+- Sequence diagram message reorder. The previous drag handler ran
+  `reorderMessage` (which mutates the model + pushes history) on every
+  mouse-move tick, so a single drag could cascade through neighboring rows,
+  swap labels onto the wrong lifeline, and clog the undo stack with hundreds
+  of intermediate states. The new implementation seeds drag state on
+  mousedown, waits for a 5-pixel threshold before activating, renders the
+  dragged row in a virtual "preview" position via `useMemo` without touching
+  `messages`, and commits the reorder exactly once on mouseup. Window-level
+  `mousemove`/`mouseup` listeners replace the SVG-scoped handlers, so
+  releasing outside the canvas still ends the drag cleanly.
+- Node drag operations now push to the undo history. Previously the drag
+  mutated state directly and was lost on `Ctrl+Z`.
+- Edge `style: 'dashed'` and `style: 'dotted'` now render with the correct
+  dash pattern on the canvas. The previous render path computed the pattern
+  but discarded it — the animated `edge-flow` class overrode the value with
+  its own dasharray, so every edge looked solid regardless of style. The
+  animation now only runs on edges whose style is `'solid'` (the default);
+  explicitly dashed/dotted edges render statically with the user's chosen
+  pattern. Mermaid / PlantUML / JSON / SVG export already serialized the
+  style correctly — this was a canvas-only regression.
+
+## [1.0.0] - 2026-05-16
+
+First stable release. The package is now published on npm and considered
+production-ready for the documented surface area.
+
+### Added
+- `LICENSE` (MIT).
+- `CHANGELOG.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`.
+- GitHub issue templates and pull request template.
+- CI workflow that runs `bun test`, typecheck, and build on every push and PR.
+- `repository`, `bugs`, `homepage` metadata in `package.json`.
+- `sideEffects: false` for better tree-shaking.
+- `Model.validate()` returns structural problems (dangling edge refs, duplicate IDs)
+  without throwing — used by tooling and surfaced in the editor UI.
+- `Model.setVariant()` and persistent `variant` field on `DiagramModel` so the UI
+  variant (flowchart / question / journey) survives JSON round-trips.
+- Mermaid importer now strips `%% comments`, `mermaid.initialize(...)` blocks,
+  `classDef` / `class` / `style` / `linkStyle` / `click` directives, and parses
+  `subgraph` blocks by tagging contained nodes with `metadata.group`.
+- Redesigned SVG canvas: smooth cubic-bezier edges, dot grid, drop shadows,
+  glowing selection ring, indigo/slate palette. `StepEditor` matches with
+  indigo accent and softer card styling.
+
+### Changed
+- `Model.addEdge()` now throws on edges that reference unknown source/target
+  node IDs (previously accepted silently). Use `Model.validate()` to inspect
+  imported data without throwing.
+- SVG / PNG exporter rewritten to mirror the canvas visuals — question nodes,
+  dynamic widths, bezier edges, dot grid, and drop shadows. Previously exports
+  used a primitive BFS grid layout with straight lines and no question-node
+  support.
+
+### Fixed
+- Mermaid exporter now emits `-.->` for dashed/dotted edges (previously
+  collapsed all styles to `-->`). PlantUML exporter emits `-[dashed]->` and
+  `-[dotted]->` for non-solid styles.
+- Mermaid importer edge regex anchors correctly so node IDs containing `{[(`
+  characters no longer bleed into the connector.
+
+## [0.1.0] - 2026-05
+
+### Added
+- Initial release.
+- Programmatic API: `flowchart()`, `sequence()`, `Model` class.
+- Exporters: Mermaid, PlantUML, JSON, SVG, PNG.
+- Importers: Mermaid, JSON.
+- React UI: `DiagramEditor` component with pan/zoom canvas, drag-to-connect, undo/redo, context menu, node navigator, light/dark/auto theme.
+- Diagram variants: `flowchart`, `question`, `journey`.
+- GitHub Pages live demo with developer docs.
+
+[Unreleased]: https://github.com/ag-gr-hub/flowchart-sequence-designer/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/ag-gr-hub/flowchart-sequence-designer/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/ag-gr-hub/flowchart-sequence-designer/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ag-gr-hub
+
+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/README.md

@@ -0,0 +1,469 @@
+# flowchart-sequence-designer
+
+A TypeScript-first Bun/npm package for building and editing flowchart and sequence diagrams — both programmatically via a fluent API and visually via a React drag-and-drop canvas editor.
+
+**🔗 [Live demo & developer docs →](https://ag-gr-hub.github.io/flowchart-sequence-designer/)**
+Open it to drive the editor, switch variants (Flowchart / Question / Journey / Sequence), and copy the same API snippets shown below straight from the docs tab. Every variant boots with a working sample diagram so you can poke without any setup.
+
+## Quick start
+
+```tsx
+import { DiagramEditor } from 'flowchart-sequence-designer/ui';
+
+export default function App() {
+  return <DiagramEditor height={520} onChange={(m) => console.log(m)} />;
+}
+```
+
+That's it — no provider, no theme setup, no required props. The editor
+mounts with a sample diagram, a working toolbar, undo/redo, drag-to-pan,
+scroll-to-zoom, and export buttons for Mermaid / PlantUML / JSON / SVG /
+PNG. Pass `theme="dark"` or `themeOverrides={…}` to brand-match, or
+`initialModel={emptyModel('flowchart')}` to start blank.
+
+## Install
+
+```bash
+bun add flowchart-sequence-designer
+# or
+npm install flowchart-sequence-designer
+```
+
+React 18+ is a peer dependency for the UI components. The core API has zero runtime dependencies.
+
+---
+
+## Programmatic API
+
+### Flowchart
+
+```ts
+import { flowchart } from 'flowchart-sequence-designer';
+
+const diagram = flowchart('Order Flow')
+  .node('start',   'Start',           { shape: 'circle' })
+  .node('check',   'Payment valid?',  { shape: 'diamond' })
+  .node('success', 'Confirm order',   { shape: 'rectangle' })
+  .node('fail',    'Reject',          { shape: 'rectangle' })
+  .edge('start',   'check')
+  .edge('check',   'success', { label: 'Yes' })
+  .edge('check',   'fail',    { label: 'No' });
+
+console.log(diagram.toMermaid());
+```
+
+#### Node shapes
+
+| Shape | Description |
+|---|---|
+| `rectangle` | Standard process box (default) |
+| `diamond` | Decision / branch |
+| `circle` | Start or end terminal |
+| `parallelogram` | Input / output |
+
+#### Edge options
+
+```ts
+.edge(from, to, {
+  label?: string,
+  style?: 'solid' | 'dashed' | 'dotted',
+  arrowhead?: 'arrow' | 'open' | 'none',
+})
+```
+
+---
+
+### Sequence diagram
+
+```ts
+import { sequence } from 'flowchart-sequence-designer';
+
+const diagram = sequence('Auth Flow')
+  .actor('User')
+  .actor('Server')
+  .message('User',   'Server', 'POST /login')
+  .message('Server', 'User',   '200 OK + token', { style: 'dashed' });
+
+console.log(diagram.toMermaid());
+```
+
+Actors auto-register from `message()` calls, so you can skip `.actor()` if you prefer.
+
+---
+
+### Export formats
+
+Every builder exposes the same export methods:
+
+```ts
+diagram.toMermaid()   // string
+diagram.toPlantUML()  // string
+diagram.toJSON()      // string (serialised DiagramModel)
+diagram.toSVG()       // string (SVG markup)
+diagram.toPNG()       // Promise<Blob>  (browser only)
+```
+
+---
+
+### Import
+
+```ts
+import { fromMermaid, fromJSON } from 'flowchart-sequence-designer';
+
+const model = fromMermaid('graph TD; A-->B; B-->C');
+const model2 = fromJSON(jsonString);
+```
+
+Round-trip fidelity: `fromMermaid(diagram.toMermaid())` produces an equivalent model.
+
+---
+
+### Exporter / importer round-trip rules
+
+The five export formats trade fidelity for portability. Use this table to
+pick the one that matches what you need:
+
+| Format | Round-trip | Preserved | Dropped or lossy |
+|---|---|---|---|
+| **JSON** | ✅ full | every field — `variant`, `metadata`, `waypoint`, x/y positions, edge arrowheads, message order | nothing |
+| **Mermaid (flowchart)** | partial | node shapes (`[]` `{}` `(())` `[/]`), labels, edge connectors (`-->`, `-.->`, `---`, `-.-`), edge labels, `subgraph` → `metadata.group` | positions, `waypoint`, `metadata.answers`, `variant`. Dotted edges collapse to dashed. |
+| **Mermaid (sequence)** | partial | actor order, message arrows (`->>`, `-->>`), labels | message metadata, styling overrides |
+| **PlantUML (flowchart)** | export-only | edge styles (`-->` / `-[dashed]->` / `-[dotted]->`), labels, node id | shape distinctions (PlantUML state-diagram syntax is coarser), positions, `metadata`, `variant` |
+| **PlantUML (sequence)** | export-only | actor order, message style (`->`, `-->`), labels | – |
+| **SVG** | export-only (rendered) | full visual parity with the canvas — same dot grid, same edge curves, same node styling | – |
+| **PNG** | export-only (rendered, **browser-only**) | same as SVG, rasterized at `devicePixelRatio` | – |
+
+If you need 100% round-trip fidelity, use JSON. If you need a format that
+GitHub renders inline in markdown, use Mermaid. If you need a polished
+image for documentation, use SVG or PNG.
+
+---
+
+### Presets
+
+```ts
+import {
+  presetFlowchartModel,
+  presetSequenceModel,
+  emptyModel,
+} from 'flowchart-sequence-designer/ui';
+
+presetFlowchartModel('flowchart')  // 6-node order flow with one decision
+presetFlowchartModel('question')   // 1-question / 3-answer router
+presetFlowchartModel('journey')    // 5-step onboarding sequence
+presetSequenceModel()              // 3-actor login handshake
+
+emptyModel('flowchart')            // { type:'flowchart', variant:'flowchart', nodes:[], edges:[] }
+emptyModel('flowchart', 'journey') // same with variant: 'journey'
+emptyModel('sequence')             // { type:'sequence', nodes:[], edges:[], actors:[], messages:[] }
+```
+
+All presets return a deep clone — mutate the result freely.
+
+---
+
+### Working with the model directly
+
+```ts
+import { Model } from 'flowchart-sequence-designer';
+import type { DiagramModel } from 'flowchart-sequence-designer';
+
+const m = new Model({ type: 'flowchart', nodes: [], edges: [] });
+m.addNode({ id: 'a', label: 'Step A', shape: 'rectangle' });
+m.addNode({ id: 'b', label: 'Step B', shape: 'rectangle' });
+m.addEdge({ id: 'e1', from: 'a', to: 'b', label: 'next' });
+```
+
+---
+
+## React UI component
+
+Import from the `/ui` sub-entry to keep React out of the bundle for non-UI consumers:
+
+```tsx
+import { DiagramEditor } from 'flowchart-sequence-designer/ui';
+```
+
+### Basic usage
+
+```tsx
+<DiagramEditor />
+```
+
+Mounted without an `initialModel` the editor boots with a small working
+sample diagram for the chosen `variant` — a 6-node order-flow for
+`flowchart`, a role-picker for `question`, a 5-step onboarding for
+`journey`, and a 3-actor login handshake for the `SequenceEditor`. This
+gives anyone evaluating the package something to interact with from the
+first render. To start blank instead:
+
+```tsx
+import { DiagramEditor, emptyModel } from 'flowchart-sequence-designer/ui';
+
+<DiagramEditor initialModel={emptyModel('flowchart')} />
+```
+
+The presets are also exported in case you want to hydrate them from your
+own code: `presetFlowchartModel(variant?)` and `presetSequenceModel()`.
+
+### All props
+
+```tsx
+<DiagramEditor
+  initialModel={model}          // pre-load a DiagramModel
+  onChange={(m) => save(m)}     // fires on every node/edge change
+  onExport={(fmt, content) => …} // intercept exports instead of auto-downloading
+  height="100%"                 // any CSS height (default: 600)
+  variant="flowchart"           // 'flowchart' | 'question' | 'journey'
+  theme="auto"                  // 'light' | 'dark' | 'auto'
+  allowedExports={['json','svg']} // restrict visible export buttons
+  allowImport={true}            // show/hide the Import button
+  themeOverrides={{             // optional per-color overrides
+    canvas: '#0b0f1a',
+    nodeSelectedFill: '#1f2a44',
+  }}
+/>
+```
+
+---
+
+### Diagram variants
+
+| Variant | Description |
+|---|---|
+| `flowchart` | General purpose — any shapes, freeform connections |
+| `question` | Each node is a question with lettered answer options (A, B, C…). Each answer has its own connection port. |
+| `journey` | Numbered milestone steps — user path or process walkthrough |
+
+---
+
+### Editor features
+
+**Canvas**
+- Drag nodes to reposition (snaps to 24px grid)
+- Scroll to zoom in/out (pinch to zoom on touch)
+- Drag the canvas background to pan (one-finger pan on touch)
+- Double-click a node to rename it inline
+- Dashed alignment guides appear when a dragged node lines up with a sibling's edge or center, and it snaps within 4 px
+- Bottom-right minimap — click or drag to pan the viewport
+- Accessibility: every node, port, and control is keyboard-reachable with a visible focus ring; selection / add / delete actions announce via an `aria-live` status region; the edge-flow animation honours `prefers-reduced-motion`
+
+**Connecting nodes**
+- Hover a node to reveal the bottom port dot, then drag it to another node
+- Question variant: each answer row has its own port dot — drag it to route that answer to a specific node
+
+**Node Navigator (left panel)**
+- Lists all nodes with shape badge, label, and connection counts
+- Search/filter by name
+- Click any row to jump to that node and center the canvas on it
+- Collapses to a slim icon strip
+
+**Step Editor (right panel)**
+- Appears when a node is selected
+- Edit the node name, change its shape
+- Manage branches / answer options (add, remove, reorder)
+- Question variant shows connection status per answer
+
+**Context menu** (right-click)
+- On canvas: Add node at cursor, Re-center, Undo, Redo
+- On node: Rename, Duplicate, Disconnect all edges, Delete
+- On edge: Style (solid/dashed/dotted), Arrowhead, Reset routing, Delete
+- On touch devices: long-press the canvas (~550ms) opens the canvas menu
+
+**Keyboard shortcuts**
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+Z` | Undo |
+| `Ctrl+Y` / `Ctrl+Shift+Z` | Redo |
+| `Ctrl+0` | Fit all nodes in view |
+| `Ctrl+C` / `Ctrl+V` | Copy and paste the current selection (internal edges preserved, +24 px offset on paste) |
+| `Ctrl+D` | Duplicate the current selection |
+| `Delete` / `Backspace` | Remove the current selection |
+| `Escape` | Deselect, cancel in-flight edge drag, close context menu |
+| `Arrow` keys | Nudge selection by 1 grid unit (Shift = 4 units) |
+| `Alt+Arrow` | Traverse to the nearest node in that direction from the current selection |
+| `Shift+click` | Toggle a node in/out of the current selection |
+| `Shift+drag` (empty canvas) | Box-select — add every intersected node to the selection |
+| Double-click edge label | Rename the edge label inline |
+| Drag edge midpoint | Route the edge through a waypoint (right-click → Reset routing to clear) |
+
+**Export / Import**
+- Toolbar exports to Mermaid, PlantUML, JSON, SVG, PNG
+- Import accepts Mermaid syntax or JSON
+
+---
+
+### Theming
+
+```tsx
+<DiagramEditor theme="dark" />    // force dark
+<DiagramEditor theme="light" />   // force light
+<DiagramEditor theme="auto" />    // follows system prefers-color-scheme (default)
+```
+
+To match the editor to a host application's brand, pass `themeOverrides` —
+a `Partial<ThemeColors>` that is shallow-merged on top of the resolved
+light/dark palette:
+
+```tsx
+import { DiagramEditor, type ThemeColors } from 'flowchart-sequence-designer/ui';
+
+const brand: Partial<ThemeColors> = {
+  canvas: '#0b1020',
+  nodeFill: '#111a2e',
+  nodeStroke: '#2b3a5a',
+  nodeSelectedFill: '#1a2447',
+  edgeColor: '#7b8aa6',
+  textPrimary: '#e6edf7',
+};
+
+<DiagramEditor theme="dark" themeOverrides={brand} />;
+```
+
+Every field on `ThemeColors` (canvas, nodeFill, nodeStroke, edgeColor, panelBg,
+inputBg, …) is overridable. Sequence diagrams accept the same prop with a
+slightly different shape — `Partial<SequenceThemeColors>` — also exported from
+`flowchart-sequence-designer/ui`.
+
+---
+
+### SequenceEditor
+
+`<DiagramEditor>` auto-delegates to `<SequenceEditor>` when handed a
+sequence model, but you can also mount it directly to avoid the
+type-check redirect:
+
+```tsx
+import { SequenceEditor, presetSequenceModel } from 'flowchart-sequence-designer/ui';
+
+<SequenceEditor
+  initialModel={presetSequenceModel()}
+  height={520}
+  theme="dark"
+  onChange={(m) => save(m)}
+/>
+```
+
+**SequenceEditor props** (mirrors `DiagramEditorProps` minus `variant`):
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `initialModel` | `DiagramModel` | preset | Must have `type: 'sequence'`. Falls back to the preset if a non-sequence model is passed. |
+| `onChange` | `(m: DiagramModel) => void` | – | Fires on every committed mutation. |
+| `onExport` | `(format, content) => void` | download | Receives string for text formats, `Blob` for PNG. |
+| `height` | `number \| string` | `600` | Any CSS height. |
+| `allowedExports` | `ExportFormat[]` | all | Whitelist of toolbar export buttons. |
+| `allowImport` | `boolean` | `true` | Show the Import button. |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | `auto` follows OS `prefers-color-scheme`. |
+| `themeOverrides` | `Partial<SequenceThemeColors>` | – | Per-property palette overrides. |
+
+**Sequence-specific interactions:**
+- Drag a message row by its handle to reorder messages.
+- Double-click a message label to rename inline.
+- Drag the column header of an actor to reorder lifelines.
+
+---
+
+### Restricting exports and import
+
+```tsx
+// Only allow JSON and SVG download
+<DiagramEditor allowedExports={['json', 'svg']} />
+
+// Hide the import button entirely
+<DiagramEditor allowImport={false} />
+
+// Handle exports yourself (e.g. send to an API)
+<DiagramEditor
+  onExport={(format, content) => {
+    if (format === 'json') myApi.save(content as string);
+  }}
+/>
+```
+
+---
+
+## Types
+
+```ts
+import type {
+  DiagramModel,
+  DiagramNode,
+  DiagramEdge,
+  DiagramVariant,
+  DiagramType,
+  NodeShape,
+  ExportFormat,
+  SequenceMessage,
+} from 'flowchart-sequence-designer';
+```
+
+### `DiagramModel`
+
+```ts
+interface DiagramModel {
+  type: 'flowchart' | 'sequence';
+  title?: string;
+  nodes: DiagramNode[];
+  edges: DiagramEdge[];
+  actors?: string[];           // sequence diagrams
+  messages?: SequenceMessage[]; // sequence diagrams
+}
+```
+
+### `DiagramNode`
+
+```ts
+interface DiagramNode {
+  id: string;
+  label: string;
+  shape?: 'rectangle' | 'diamond' | 'circle' | 'parallelogram';
+  x?: number;
+  y?: number;
+  metadata?: Record<string, unknown>;
+  // question variant: metadata.answers = string[]
+}
+```
+
+### `DiagramEdge`
+
+```ts
+interface DiagramEdge {
+  id: string;
+  from: string;
+  to: string;
+  label?: string;
+  style?: 'solid' | 'dashed' | 'dotted';
+  arrowhead?: 'arrow' | 'none' | 'open';
+}
+```
+
+---
+
+## Package structure
+
+```
+flowchart-sequence-designer/
+├── dist/
+│   ├── index.js / index.cjs / index.d.ts   ← core (no React)
+│   └── ui/
+│       └── index.js / index.cjs / index.d.ts ← React UI
+└── src/
+    ├── core/          # types, Model, FlowchartBuilder, SequenceBuilder
+    ├── exporters/     # mermaid, plantuml, json, svg
+    ├── importers/     # mermaid, json
+    └── ui/            # DiagramEditor, StepEditor, Toolbar, NodeNavigator
+```
+
+The `"."` export gives you the core API; `"./ui"` gives you the React components. Consumers that only use the programmatic API never pull in React.
+
+---
+
+## Building from source
+
+```bash
+bun install
+bun run build    # outputs to dist/
+bun test         # runs the test suite
+```