@draftably/editor 0.3.0 → 0.5.0

package/dist/types/src/graph-api/core.d.ts

@@ -0,0 +1,125 @@
+import type { Point, RoutingSettings, Side } from '../model/types';
+export type Shape = 'box' | 'pill' | 'circle' | 'diamond' | 'text';
+/** How a scope arranges its children: a recipe, or a layout engine as `engine:<name>`. */
+export type Arrange = 'flow' | 'row' | 'column' | 'lanes' | 'sequence' | `engine:${string}`;
+/**
+ * How hard the router works. `full` repairs crossings and evens out lanes; `quick` routes each
+ * line once. `auto` (the default) routes quickly first, and fully when that will stay fast.
+ */
+export type Quality = 'auto' | 'full' | 'quick';
+export interface RoutingOptions extends Partial<RoutingSettings> {
+    quality?: Quality;
+}
+export interface NodeIn {
+    id: string;
+    label?: string;
+    parent?: string;
+    shape?: Shape;
+    /** Fixed size, kept within 40–1200 by 24–1200. Without one, the box fits its label. */
+    width?: number;
+    height?: number;
+}
+export interface GroupIn {
+    id: string;
+    label?: string;
+    parent?: string;
+    /** How the group arranges its own children; `column` by default. */
+    arrange?: Arrange;
+    direction?: 'right' | 'down';
+    gap?: number;
+}
+export interface EdgeIn {
+    /** Unique among edges. Without one, the edge is `e1`, `e2`, … by position. */
+    id?: string;
+    source: string;
+    target: string;
+    label?: string;
+    dashed?: boolean;
+    sourceSide?: Side;
+    targetSide?: Side;
+}
+export interface GraphIn {
+    nodes: NodeIn[];
+    groups?: GroupIn[];
+    edges?: EdgeIn[];
+    /** How the top level is arranged; `flow` by default. */
+    arrange?: Arrange;
+    direction?: 'right' | 'down';
+    gap?: number;
+    fit?: 'wide' | 'slide' | 'square' | 'page' | 'tall';
+    /**
+     * `auto` (the default) folds a long `flow` into rows, like lines of text, when it is much
+     * wider than a 1100×720 page; `never` keeps one row.
+     */
+    fold?: 'auto' | 'never';
+    routing?: RoutingOptions;
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PlacedBox extends Box {
+    parent?: string;
+}
+export interface EdgeOut {
+    source: string;
+    target: string;
+    sourceSide: Side;
+    targetSide: Side;
+    /** From the source's outline to the target's. The host draws the arrowhead at the last point. */
+    points: Point[];
+    /** SVG path data with the rounded corners draftably draws. */
+    path: string;
+    /** The label's box. Draw a backing behind it: other lines may pass under it. */
+    label: Box | null;
+    /** True when the router found no clear way and drew a fallback line. */
+    blocked: boolean;
+}
+export interface Routed {
+    edges: Record<string, EdgeOut>;
+    /** The router mode that drew the lines. */
+    quality: 'full' | 'quick';
+    warnings: string[];
+}
+export interface LayoutResult extends Routed {
+    nodes: Record<string, PlacedBox>;
+    groups: Record<string, PlacedBox>;
+    /** Everything drawn: boxes, lines and labels. */
+    bounds: Box;
+    /** The `.draft` file this graph is. Open it in the viewer, or pass it to `renderSvg`. */
+    draft: string;
+}
+/**
+ * `auto` routes fully when the quick routes predict a full pass within the budget. The full
+ * pass reroutes each line with a crossing or crowded lane against all the others, so its cost
+ * grows with lines times conflicts; this limit keeps it near the 1 s load budget.
+ */
+export declare const AUTO_FULL_LIMIT = 1200;
+/** Place and route a graph the way a `.draft` file with the same content draws. */
+export declare function layout(graph: GraphIn): Promise<LayoutResult>;
+/**
+ * `layout` without a promise, for callers that cannot wait, such as a stand-in for a synchronous
+ * library. It cannot run a layout engine (`engine:` arrangements) or `fit`, which need `layout`.
+ */
+export declare function layoutSync(graph: GraphIn): LayoutResult;
+export interface PlacedNodeIn extends Box {
+    id: string;
+    parent?: string;
+    shape?: Shape;
+}
+export interface PlacedGroupIn extends Box {
+    id: string;
+    parent?: string;
+    /** The title, so lines keep out of its band at the top of the group. */
+    label?: string;
+}
+export interface RouteIn {
+    nodes: PlacedNodeIn[];
+    groups?: PlacedGroupIn[];
+    edges: EdgeIn[];
+    routing?: RoutingOptions;
+}
+/** Route lines between boxes the caller placed. Nothing moves. */
+export declare function route(graph: RouteIn): Routed;

package/dist/types/src/model/appearance.d.ts

@@ -9,7 +9,7 @@ import type { Footnote } from './footnote';
 import type { Note } from './note';
 import { type FontRole, type TypeProfile } from './fonts';
 import type { FileConfig } from './link';
-export type ThemeId = 'drafting' | 'fieldnotes' | 'signal' | 'ink' | 'blueprint';
+export type ThemeId = 'drafting' | 'fieldnotes' | 'signal' | 'ink' | 'blueprint' | 'drafting-dark';
 export declare const THEME_IDS: ThemeId[];
 export declare const DEFAULT_THEME: ThemeId;
 /** Shade stops. Lower numbers are lighter and higher numbers darker, in every theme. */
@@ -18,6 +18,12 @@ export type Shade = (typeof SHADES)[number];
 export declare const isShade: (n: unknown) => n is Shade;
 /** Shade of a node that names a color without a shade. */
 export declare const NODE_SHADE: Shade;
+/**
+ * Shade of a member card: a node drawn in its container's family with no shade of its own. It is
+ * the palest stop on the canvas side of the frame (50 in light themes, 950 in dark ones), so the
+ * card stands apart from its frame by fill and keeps the family's outline and ink.
+ */
+export declare const memberShadeFor: (theme: ThemeId) => Shade;
 /**
  * Shade of a group that names a color without a shade. Groups are quiet surfaces behind nodes, so
  * this is a pale shade in light themes and a deep one in dark themes; the scale itself never flips.
@@ -148,6 +154,15 @@ interface Preset {
     hues?: Partial<Record<string, [number, number]>>;
 }
 export declare const PRESETS: Record<ThemeId, Preset>;
+/**
+ * The appearance to draw on a page of this scheme. The default theme follows the page, with or
+ * without a `theme drafting` line and its size and font overrides: dark draws it as
+ * `drafting-dark`. Another named theme, a `theme-color` line or a color override on the `theme`
+ * line keeps the file's colors on every page.
+ */
+export declare function forScheme(appearance: DiagramAppearance, dark: boolean): DiagramAppearance;
+/** `a` moved toward `b` by `t` (0–1), in sRGB. */
+export declare function mixColors(a: string, b: string, t: number): string;
 export declare function contrast(a: string, b: string): number;
 /** Contrast targets (WCAG ratios) every generated color meets. */
 export declare const CONTRAST: {
@@ -184,6 +199,8 @@ export interface ResolvedAppearance {
     radius: number;
     shadow: boolean;
     title: TypeProfile;
+    /** A node title's detail lines (after its first `\n`): a step smaller and lighter. */
+    detail: TypeProfile;
     groupTitle: TypeProfile;
     annotation: TypeProfile;
     /** Space above a group's content; the group title sits in it. */
@@ -204,6 +221,15 @@ export declare function resolveAppearance(appearance?: DiagramAppearance): Resol
  * default surface; the file parser reports them before they get here.
  */
 export declare function swatchFor(r: ResolvedAppearance, family: string | undefined, shade: Shade | undefined, kind?: 'node' | 'group'): Swatch;
+/**
+ * The quiet panel behind notes and a sequence diagram: slate 50 in light themes, and the theme's
+ * own group surface in dark ones, so the theme's text ink reads on it.
+ */
+export declare const panelSwatch: (r: ResolvedAppearance) => Swatch;
+/** Bands and dividers drawn over that panel. */
+export declare const bandSwatch: (r: ResolvedAppearance) => Swatch;
+/** Ink for a link in a note or footnote, held to 4.5:1 on `against`. */
+export declare const linkInk: (r: ResolvedAppearance, against: string) => string;
 /** Shades a family defines, in numeric order. */
 export declare const shadesOf: (r: ResolvedAppearance, family: string) => Shade[];
 export {};

package/dist/types/src/model/colors.d.ts

@@ -4,8 +4,11 @@
  *
  * - A container inside a container of the same family steps one shade toward emphasis per level
  *   (lighter frames underneath, smaller and stronger ones on top), instead of repeating the fill.
- * - A shape whose shade is within two steps of its container's, in the same family, moves three
- *   steps past the container, so a member never melts into its frame.
+ * - A member card: a shape in its container's family with no shade of its own draws as a pale
+ *   card on the frame's tint (`memberShadeFor`), so a group of members reads as calm cards
+ *   rather than a column of dark slabs. This holds while the frame is a quiet surface shade.
+ * - Any other shape whose shade is within two steps of its container's, in the same family, moves
+ *   three steps past the container, so a member never melts into its frame.
  *
  * The canvas, the CLI's SVG and exports all draw through `drawnSwatch`.
  */
@@ -20,3 +23,8 @@ export declare function drawnSwatch(doc: Diagram, look: ResolvedAppearance, id:
  * its top. Undefined for anything else, and for a participant with no color of its own.
  */
 export declare function participantAccent(doc: Diagram, look: ResolvedAppearance, id: string): string | undefined;
+/**
+ * Ink for a title's detail lines on a swatch: the theme's muted ink on the neutral surface, or the
+ * swatch's own ink moved toward its fill on a colored one, held to 4.5:1 on the fill.
+ */
+export declare function detailInk(look: ResolvedAppearance, swatch: Swatch): string;

package/dist/types/src/model/labels.d.ts

@@ -12,10 +12,25 @@ export interface TitleArea {
     maxHeight: number;
 }
 export declare function titleArea(shape: ShapeKind, w: number, h: number, r: ResolvedAppearance, icon?: boolean): TitleArea;
-/** Height a shape needs for `lines` title lines; never less than `base`. */
-export declare function titleHeight(shape: ShapeKind, lines: number, base: number, r: ResolvedAppearance): number;
-/** A shape's title in balanced lines no wider than `width` (see `wrapLines`). */
-export declare const wrapTitle: (text: string, width: number, r: ResolvedAppearance) => string[];
+/** Height a shape needs for a title block `text` px tall; never less than `base`. */
+export declare function titleHeight(shape: ShapeKind, text: number, base: number, r: ResolvedAppearance): number;
+/** One line of a shape's title: part of its name, or of its detail. */
+export interface TitleLine {
+    text: string;
+    /** A detail line, from the text after the title's first `\n`, drawn in `r.detail`. */
+    detail: boolean;
+}
+/**
+ * A shape's title in balanced lines no wider than `width` (see `wrapLines`). The text before the
+ * first `\n` is the name, in the title type; the rest is detail, in the smaller detail type.
+ */
+export declare function wrapTitle(text: string, width: number, r: ResolvedAppearance): TitleLine[];
+/** The type a title line is set in. */
+export declare const lineType: (l: TitleLine, r: ResolvedAppearance) => TypeProfile;
+/** Height of a block of title lines. */
+export declare const textHeight: (lines: TitleLine[], r: ResolvedAppearance) => number;
+/** Each line's centre, measured from the middle of the block. */
+export declare function lineOffsets(lines: TitleLine[], r: ResolvedAppearance): number[];
 /**
  * Line width for a diamond's title, `s` its side. A text block W wide and H tall fits inside a
  * square diamond when W + H <= s, so this takes the widest measure whose wrapped lines still fit:
@@ -37,9 +52,10 @@ export interface NodeLabel {
     y: number;
     width: number;
     height: number;
-    lines: string[];
+    lines: TitleLine[];
+    /** Each line's centre, relative to `y`. */
+    offsets: number[];
     mode: LabelMode;
-    lineHeight: number;
     leader: boolean;
 }
 /** Where a shape's title is drawn, relative to the shape. */

package/dist/types/src/runtime/anchors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The anchor layer both handles share: one stable target element per anchored item, above the
+ * drawing. `body:<id>` targets sit in world space in one transformed layer, so they scale and clip
+ * with the node; `overlay:<id>` targets sit in screen space at the item's on-screen box. A target
+ * keeps its identity while its item exists, across updates and camera moves. The layer itself is
+ * never detached while the handle lives.
+ */
+import type { Diagnostic } from './types';
+import { type Geometry } from './geometry';
+/** A slot name. IDs come from source text, so the type cannot check them; diagnostics do. */
+export type DraftSlot = `body:${string}` | `overlay:${string}`;
+export type AnchorKind = 'node' | 'group' | 'edge';
+export interface Anchor {
+    slot: DraftSlot;
+    id: string;
+    kind: AnchorKind;
+    /** The stable target. */
+    el: HTMLElement;
+}
+/** Below this zoom, bodies hide and titles show again (`detail: 'auto'`). */
+export declare const LOW_DETAIL_ZOOM = 0.4;
+export interface AnchorLayer {
+    readonly el: HTMLElement;
+    /** The slots the host wants. Returns true when the targets changed. */
+    setSlots(slots: readonly string[]): boolean;
+    /** Whether the host wants any slot. */
+    hasSlots(): boolean;
+    /** A new committed drawing. Returns true when the targets changed. */
+    setGeometry(geometry: Geometry | null): boolean;
+    /** The camera: screen = origin + world × zoom. Writes only; reads no layout. */
+    place(originX: number, originY: number, zoom: number): void;
+    anchors(): Anchor[];
+    /** IDs of nodes whose body is anchored, for hiding their titles. */
+    bodyIds(): string[];
+    /** Slot warnings: unknown IDs and content that overflows its box. */
+    warnings(): Diagnostic[];
+    /** A pointer press that began in the layer is still down: focus it moves is not a Tab. */
+    pressed(): boolean;
+    /** The target holding `node`, if any. */
+    idOf(node: Node): string | undefined;
+    destroy(): void;
+}
+export declare function createAnchorLayer(doc: Document, options?: {
+    detail?: 'auto' | 'full';
+    onOverflow?: () => void;
+}): AnchorLayer;

package/dist/types/src/runtime/camera.d.ts

@@ -0,0 +1,41 @@
+/**
+ * One camera for the viewer and the editor: the world point at the viewport's centre and a zoom.
+ * Both handles frame and reveal through these functions, so the same call moves both the same way.
+ */
+import type { Box } from '../graph-api/core';
+/** World units at the centre of the viewport. Independent of the viewport size. */
+export interface Camera {
+    centerX: number;
+    centerY: number;
+    zoom: number;
+}
+export type CameraReason = 'user' | 'api' | 'fit' | 'resize' | 'restore';
+/** `pending`: the viewport has no size yet; the latest call runs once it has one. */
+export type MoveResult = 'moved' | 'unchanged' | 'missing' | 'pending';
+export interface FrameOptions {
+    /** Screen pixels kept clear, for example under a host panel. Default 32. */
+    padding?: number | {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    minZoom?: number;
+    /** Default 1 for `fit`, so a small diagram is not blown up. */
+    maxZoom?: number;
+}
+export declare const ZOOM_MIN = 0.02;
+export declare const ZOOM_MAX = 8;
+type View = {
+    width: number;
+    height: number;
+};
+export declare const clampZoom: (zoom: number, min?: number, max?: number) => number;
+/** The union of boxes, or undefined for none. */
+export declare function unionBox(boxes: readonly Box[]): Box | undefined;
+/** The camera that shows `box`, centred in the padded viewport, at most `maxZoom` (default 1). */
+export declare function fitCamera(box: Box, view: View, options?: FrameOptions): Camera;
+/** The least move that brings `box` fully into the padded viewport; zooms out only if needed. */
+export declare function revealCamera(camera: Camera, box: Box, view: View, options?: FrameOptions): Camera;
+export declare const sameCamera: (a: Camera, b: Camera) => boolean;
+export {};

package/dist/types/src/runtime/color-scheme.d.ts

@@ -0,0 +1,15 @@
+/** Watches one host's scheme. `check` reads it again now; `stop` ends the watch. */
+export interface SchemeWatch {
+    check(): void;
+    stop(): void;
+}
+/**
+ * Calls `onChange(dark)` now and whenever the scheme in `host` changes: an element, or a shadow
+ * root, whose children inherit the element's scheme. A hidden probe in `host` has a `light-dark()`
+ * color, so a scheme change anywhere above it (a class flip on the page, a style) starts a
+ * transition there; the media query covers a change of system setting under `light dark`. A
+ * transition cannot run while the host has no box (a hidden tab, a closed `<details>`, a detached
+ * mount), so a resize observer on the host reads the scheme again when it gets one. Callers also
+ * call `check` after each commit.
+ */
+export declare function watchColorScheme(host: Element | ShadowRoot, onChange: (dark: boolean) => void): SchemeWatch;

package/dist/types/src/runtime/element-base.d.ts

@@ -0,0 +1,40 @@
+/** Helpers both custom elements share. No side effects. */
+import { type HostEvents } from './host';
+import type { Anchor } from './anchors';
+import type { UpdateResult } from './viewer';
+/** Structural equality for option values. Functions are read live, so any two are equal. */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/** Take a property a framework set before the element class was defined. */
+export declare function takeEarly<T>(el: HTMLElement, key: string): T | undefined;
+/** Warn once when another copy of the runtime already defined `name`. */
+export declare function warnOtherCopy(name: string): void;
+/** Re-dispatch a handle event on the element. Returns false when the host prevented it. */
+export declare function redispatch<K extends keyof HostEvents>(el: HTMLElement, type: K, detail: HostEvents[K]): boolean;
+/** The update result for an element whose handle could not start. */
+export declare function mountFailure(revision: number, error: unknown, fallback: string): Extract<UpdateResult, {
+    status: 'error';
+}>;
+/**
+ * One constructable stylesheet per element type and page, shared by every instance. It needs no
+ * nonce under a strict CSP. Undefined where the browser cannot adopt sheets.
+ */
+export declare function sharedSheet(doc: Document, key: string, css: string): CSSStyleSheet | undefined;
+/**
+ * Re-dispatch a handle event whose payload may carry `preventDefault()`: the DOM event is
+ * cancelable instead, and a host that cancels it cancels Draftably's default.
+ */
+export declare function relay<K extends keyof HostEvents>(el: HTMLElement, type: K, event: HostEvents[K] | (HostEvents[K] & {
+    preventDefault(): void;
+})): undefined;
+/**
+ * Manual slot assignment for an element's children. A child marked `data-draft-slot="body:api"`
+ * goes into the target for that slot; other children go to `fallback`. The element never writes
+ * to the host's DOM: it only calls `slot.assign()`.
+ */
+export declare function createSlotting(host: HTMLElement, fallback: HTMLSlotElement | null, onSlots: (names: string[]) => void): {
+    start(): void;
+    stop(): void;
+    /** The handle's targets changed: put each slot's children in its target. */
+    setAnchors(next: readonly Anchor[]): void;
+    names: () => string[];
+};

package/dist/types/src/runtime/geometry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Geometry as hosts see it: the graph API's shapes (`Box`, `PlacedBox`, `EdgeOut`) in world units,
+ * built from the boxes and routes a drawing uses. `renderSvg`, the viewer, the editor and the graph
+ * API all build it here, so their numbers agree.
+ */
+import type { Box, EdgeOut, PlacedBox } from '../graph-api/core';
+import type { Diagram, Point, Rect, Side } from '../model/types';
+export type { Box, EdgeOut, PlacedBox };
+/** The graph API's shapes, in world units, for the drawing now committed. */
+export interface Geometry {
+    revision: number;
+    /** Everything drawn: heading, legend, notes, footnotes. */
+    frame: Box;
+    /** Shapes, lines and labels only. */
+    bounds: Box;
+    nodes: Record<string, PlacedBox>;
+    groups: Record<string, PlacedBox>;
+    /** The routes as drawn. */
+    edges: Record<string, EdgeOut>;
+}
+/** The route fields geometry reads; `computeRoutes` returns more. */
+export interface DrawnRoute {
+    id: string;
+    from: string;
+    to: string;
+    fromSide: Side;
+    toSide: Side;
+    points: Point[];
+    path: string;
+    label?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    blocked?: boolean;
+}
+export declare function boundsOf(boxes: readonly Box[]): Box;
+/** An edge's box: its route's points and its label. */
+export declare const edgeBox: (e: EdgeOut) => Box;
+/**
+ * Every visible node, group and edge of a projected document, under the caller's IDs. `rects`
+ * holds the visible objects' boxes; `routes` the lines as drawn.
+ */
+export declare function placedItems(doc: Diagram, rects: ReadonlyMap<string, Rect>, routes: readonly DrawnRoute[], objectId?: (id: string) => string, edgeId?: (id: string) => string): {
+    nodes: {
+        [k: string]: PlacedBox;
+    };
+    groups: {
+        [k: string]: PlacedBox;
+    };
+    edges: {
+        [k: string]: {
+            source: string;
+            target: string;
+            sourceSide: Side;
+            targetSide: Side;
+            points: Point[];
+            path: string;
+            label: {
+                x: number;
+                y: number;
+                width: number;
+                height: number;
+            } | null;
+            blocked: boolean;
+        };
+    };
+    bounds: Box;
+};
+/** The box of any item in a geometry, or undefined. */
+export declare function itemBox(g: Geometry, id: string): Box | undefined;

package/dist/types/src/runtime/host.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The host contract both elements share: the events they dispatch, as plain data. Framework
+ * packages loop over `HOST_EVENTS`, so a new event adds no lines to any of them.
+ * This module has no side effects and no runtime imports.
+ */
+import type { RenderFailure } from './types';
+import type { UpdateResult, ViewerEvents } from './viewer';
+export type { Camera, CameraReason, FrameOptions, MoveResult } from './camera';
+export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry';
+export type { Anchor, DraftSlot } from './anchors';
+export interface HostEvents {
+    /** After each commit, after the marked children change, and with `[]` before destroy. */
+    anchors: ViewerEvents['anchors'];
+    /**
+     * Each update's result, from the first source on: committed, error or a cancellation. The
+     * editor's commit has no `value` or `diagnostics` (see `EditorUpdate`).
+     */
+    update: UpdateResult | EditorUpdate;
+    render: ViewerEvents['render'];
+    diagnostics: ViewerEvents['diagnostics'];
+    camera: ViewerEvents['camera'];
+    itemactivate: ViewerEvents['itemactivate'];
+    /** Cancelable: `preventDefault()` on the DOM event stops Draftably opening the link. */
+    link: Omit<ViewerEvents['link'], 'preventDefault'>;
+    /** Cancelable: `preventDefault()` on the DOM event stops the browser's menu. */
+    contextmenu: Omit<ViewerEvents['contextmenu'], 'preventDefault'>;
+    /** The editor only: the selection changed, by the user or through `select()`. */
+    select: {
+        ids: readonly string[];
+        reason: 'user' | 'api';
+    };
+    /** The editor only: the source after a kept edit, undo or redo. */
+    change: {
+        source: string;
+    };
+}
+/**
+ * `<draft-editor>`'s update. The editor draws in its own session, not as one SVG, so a commit
+ * has no `value` and no `diagnostics`: the `diagnostics` event has them. A source that does not
+ * parse is an `error` with a `DRAFT_PARSE` diagnostic; the editor keeps the text and shows it.
+ */
+export type EditorUpdate = {
+    status: 'committed';
+    revision: number;
+    value?: never;
+    diagnostics?: never;
+} | {
+    status: 'error';
+    revision: number;
+    error: RenderFailure;
+} | {
+    status: 'destroyed';
+    revision: number;
+};
+export type HostEventName = keyof HostEvents;
+/** Every event, in one list. Each element dispatches these as bubbling `draft-<name>` events. */
+export declare const HOST_EVENTS: readonly ["anchors", "update", "render", "diagnostics", "camera", "itemactivate", "link", "contextmenu", "select", "change"];
+/** Events a host can cancel with `preventDefault()`. */
+export type CancelableEventName = 'link' | 'contextmenu';
+export declare const CANCELABLE_EVENTS: readonly HostEventName[];
+/**
+ * What a framework event prop receives: the event's `detail`, and on a cancelable event a
+ * `preventDefault()` that cancels the DOM event, so `onLink={e => e.preventDefault()}` works.
+ */
+export type HostEventDetail<K extends HostEventName> = K extends CancelableEventName ? HostEvents[K] & {
+    preventDefault(): void;
+} : HostEvents[K];
+/** The value a framework event prop receives for a `draft-<name>` event. */
+export declare function hostDetail(event: Event): unknown;
+export type DraftEventMap = {
+    [K in HostEventName as `draft-${K}`]: CustomEvent<HostEvents[K]>;
+};
+/** The element's `status` attribute. */
+export type DraftStatus = 'loading' | 'ready' | 'error';
+declare global {
+    interface HTMLElementEventMap extends DraftEventMap {
+    }
+}

package/dist/types/src/runtime/page-shared.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What every viewer on a page shares: a small pool of render workers and one font registry. A
+ * page with 20 diagrams starts at most `POOL_SIZE` workers and loads each font face once.
+ */
+import type { RenderOptions, RenderResult } from './types';
+/** Names the worker and the usual fix, so "worker failed" is not a dead end. */
+export declare const WORKER_HELP = "The worker is the module next to @draftably/runtime's viewer. With Vite 5\u20137, add optimizeDeps: { exclude: ['@draftably/runtime', '@draftably/editor'] } to vite.config.";
+/**
+ * Render in the page's worker pool. Jobs queue on the main thread; an aborted job leaves the
+ * queue before a worker sees it. A job that runs past `timeoutMs` stops its worker only.
+ */
+export declare function renderInWorker(source: string, options: RenderOptions, { create, timeoutMs, signal, }: {
+    create?: () => Worker;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<RenderResult>;
+/** The page's registered face for `key`, if any. */
+export declare const sharedFace: (doc: Document, key: string) => FontFace | undefined;
+/** Take a reference to `face` under `key`, adding it to the page on first use. */
+export declare function retainFace(doc: Document, key: string, face: FontFace): undefined;
+/** Drop a reference; the last one removes the face from the page. */
+export declare function releaseFace(doc: Document, key: string): void;
+/** Tests only: stop every worker and forget every face, as a new page would. */
+export declare function resetPageShared(): void;

package/dist/types/src/runtime/policy.d.ts

@@ -0,0 +1,7 @@
+import type { Diagram } from '../model/types';
+import type { Diagnostic, RenderOptions } from './types';
+export declare function assertOptions(options: RenderOptions): void;
+/** A link in note or footnote text: kept only as a safe HTTP(S) URL under a safe policy. */
+export declare const textLink: (options: RenderOptions) => (href: string) => string | null;
+/** The host resolves first; final validation never trusts the callback or authored link-base. */
+export declare function applyLinks(doc: Diagram, options: RenderOptions): Diagnostic[];

package/dist/types/src/runtime/render.d.ts

@@ -0,0 +1,10 @@
+import { type Scene } from '../dsl/compile';
+import type { RenderOptions, RenderResult, ValidateOptions, ValidationResult } from './types';
+export interface InternalRender {
+    result: RenderResult;
+    scene?: Scene;
+}
+/** Internal bridge for repository callers that need the editable Scene alongside public output. */
+export declare function renderWithScene(source: string, options?: RenderOptions): Promise<InternalRender>;
+export declare function renderSvg(source: string, options?: RenderOptions): Promise<RenderResult>;
+export declare function validate(source: string, options?: ValidateOptions): Promise<ValidationResult>;

package/dist/types/src/runtime/schemes.d.ts

@@ -0,0 +1,2 @@
+/** Both drawings as one, or null when they differ in more than color. */
+export declare function mergeSchemes(light: string, dark: string): string | null;

package/dist/types/src/runtime/svg-renderer.d.ts

@@ -3,6 +3,7 @@
  * same appearance, shapes and title wrapping as the canvas and embeds the fonts it uses.
  */
 import { type ResolvedAppearance } from '../model/appearance';
+import { computeRoutes } from '../model/routes';
 import type { Diagram, Rect } from '../model/types';
 /** How an object's `href` is written into the file; as written unless the caller says. */
 export interface SvgOptions {
@@ -20,9 +21,20 @@ export interface SvgOptions {
     linkTarget?: '_self' | '_blank';
     metadata?: string;
     maxOutputBytes?: number;
+    /** Receives the boxes and routes of a one-panel drawing, as drawn (not for compare or states). */
+    onDrawn?: (drawn: {
+        rects: Map<string, Rect>;
+        routes: Route[];
+    }) => void;
+    /**
+     * The routes `onDrawn` gave for this document, so drawing it again in other colors routes
+     * nothing again (not for compare or states).
+     */
+    routes?: Route[];
 }
 export declare class SvgLimitError extends Error {
 }
+export type Route = ReturnType<typeof computeRoutes>['routes'][number];
 /**
  * A sequence diagram's panel, a light surface with a border that bounds the exchange, and a row
  * band for each phase with its label in a tab at the left edge. Drawn under everything else.