@draftably/runtime 0.3.0 → 0.4.0

package/dist/types/src/dsl/cells.d.ts

@@ -15,6 +15,7 @@ export interface CellInput {
     size?: {
         width: number;
         height?: number;
+        minHeight?: number;
     };
 }
 export interface CellBox {

package/dist/types/src/dsl/compile.d.ts

@@ -99,11 +99,12 @@ export declare function layoutFor(m: Model, scope: string): ModelLayout;
 /**
  * Size of a node: its requested size, or the default width with a height that fits the title in
  * the theme's type and padding. A requested size is kept exactly; `overflow` reports a title that
- * no longer fits in it.
+ * no longer fits in it. With `height=auto`, `min-height` is a floor under the title's height.
  */
 export declare function leafSize(o: ModelObject, size: {
     width: number;
     height?: number;
+    minHeight?: number;
 } | undefined, look: ResolvedAppearance): {
     w: number;
     h: number;

package/dist/types/src/dsl/legend-notes.d.ts

@@ -1,3 +1,17 @@
+/**
+ * `check` advice on the key and the prose round a drawing: a key that leaves a color or a line
+ * style unexplained, a `legend` swatch drawn in a shade that no node of its family uses, and
+ * heading prose that the drawing should say instead.
+ */
+import { type Shade } from '../model/appearance.js';
 import type { Diagnostic } from './compile.js';
 import type { Model } from './syntax.js';
 export declare function legendNotes(m: Model): Diagnostic[];
+/**
+ * The shade a `legend family` swatch draws when its line sets none: what the family's nodes draw.
+ * When no node names the family and its nodes are all member cards (they inherit it from a group
+ * on a quiet surface shade), that is the member card's shade; otherwise it is a colored node's.
+ */
+export declare function legendShade(m: Model, family: string): Shade;
+/** Give each `legend family` line with no `shade=` the shade its family's nodes draw. */
+export declare function settleLegendShades(m: Model): void;

package/dist/types/src/dsl/syntax.d.ts

@@ -210,11 +210,13 @@ export type Hint = {
     line: number;
 }
 /** `height` is unset for `height=auto`: the title's height at that width, as without a size. */
+/** `minHeight` is a floor under `height=auto`, for a host that draws more than the title. */
  | {
     type: 'size';
     id: string;
     width: number;
     height?: number;
+    minHeight?: number;
     line: number;
 };
 export type Strength = 'prefer' | 'required';

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

@@ -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,8 @@ interface Preset {
     hues?: Partial<Record<string, [number, number]>>;
 }
 export declare const PRESETS: Record<ThemeId, Preset>;
+/** `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 +192,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 +214,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.js';
+import { type Geometry } from './geometry.js';
+/** 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.js';
+/** 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/element-base.d.ts

@@ -0,0 +1,40 @@
+/** Helpers both custom elements share. No side effects. */
+import { type HostEvents } from './host.js';
+import type { Anchor } from './anchors.js';
+import type { UpdateResult } from './viewer.js';
+/** 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/element.d.ts

@@ -1,8 +1,15 @@
 import type { UpdateResult, ViewerHandle, ViewerOptions } from './viewer.js';
+export type { DraftEventMap, DraftStatus, HostEventName, HostEvents } from './host.js';
+export { HOST_EVENTS } from './host.js';
 export interface DraftDiagramElement extends HTMLElement {
     source: string;
     /** Reflects the `outline` attribute. */
     outline: 'visible' | 'hidden' | undefined;
+    /**
+     * Every `mountViewer` option. `label`, `outline`, `toolbar` and `render` (except `fonts`) apply
+     * live; `execution` and `render.fonts` mount a new viewer. A new object with the same values
+     * does nothing.
+     */
     options: ViewerOptions;
     readonly viewer?: ViewerHandle;
     readonly updateComplete: Promise<UpdateResult | undefined>;

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.js';
+import type { Diagram, Point, Rect, Side } from '../model/types.js';
+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,46 @@
+/**
+ * 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 { UpdateResult, ViewerEvents } from './viewer.js';
+export type { Camera, CameraReason, FrameOptions, MoveResult } from './camera.js';
+export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry.js';
+export type { Anchor, DraftSlot } from './anchors.js';
+export interface HostEvents {
+    /** After each commit, after the marked children change, and with `[]` before destroy. */
+    anchors: ViewerEvents['anchors'];
+    /** Each update's result: committed, error or a cancellation. */
+    update: UpdateResult;
+    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;
+    };
+}
+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 declare const CANCELABLE_EVENTS: readonly HostEventName[];
+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/index.d.ts

@@ -2,4 +2,5 @@ import type { RenderOptions, RenderResult, ValidateOptions, ValidationResult } f
 export declare const renderSvg: (source: string, options?: RenderOptions) => Promise<RenderResult>;
 export declare const validate: (source: string, options?: ValidateOptions) => Promise<ValidationResult>;
 export { runtimeVersion, fontMetricsVersion } from './version.js';
+export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry.js';
 export type { CompileLimits, CommonRenderOptions, Diagnostic, DiagramSummary, ItemSummary, LinkPolicy, RenderFailure, RenderLimits, RenderOptions, RenderResult, RenderedDiagram, Severity, SourceLocation, ValidateOptions, ValidationResult, } from './types.js';

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.js';
+/** 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, 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/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.js';
+import { computeRoutes } from '../model/routes.js';
 import type { Diagram, Rect } from '../model/types.js';
 /** How an object's `href` is written into the file; as written unless the caller says. */
 export interface SvgOptions {
@@ -20,9 +21,15 @@ 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;
 }
 export declare class SvgLimitError extends Error {
 }
+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.
@@ -36,3 +43,4 @@ export declare const PHASE_TAB = 8;
 /** A thin stripe across the top of a box, inside its rounded corners. */
 export declare function accentPath(r: Rect, radius: number): string;
 export declare function renderSvg(doc: Diagram, opts?: SvgOptions): string;
+export {};

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

@@ -1,3 +1,4 @@
+import type { Geometry } from './geometry.js';
 export type Severity = 'error' | 'warning' | 'info';
 export interface SourceLocation {
     sourceId?: string;
@@ -86,6 +87,11 @@ export interface DiagramSummary {
 }
 export interface RenderedDiagram extends DiagramSummary {
     svg: string;
+    /**
+     * Where each node, group and edge is drawn, in the SVG's own units (its `viewBox`), in the graph
+     * API's shapes. `null` for `compare` and `states` drawings, which repeat items across panels.
+     */
+    geometry: Geometry | null;
     provenance: {
         runtimeVersion: string;
         dslVersion: 1;

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

@@ -1,11 +1,13 @@
+import { type Camera, type CameraReason, type FrameOptions, type MoveResult } from './camera.js';
+import { type Anchor, type DraftSlot } from './anchors.js';
+import { type Geometry } from './geometry.js';
 import { fontMetricsVersion, runtimeVersion } from './version.js';
 import type { CommonRenderOptions, Diagnostic, LinkPolicy, RenderFailure, RenderResult } from './types.js';
 export { fontMetricsVersion, runtimeVersion };
-export interface Camera {
-    centerX: number;
-    centerY: number;
-    zoom: number;
-}
+export type { Camera, CameraReason, FrameOptions, MoveResult } from './camera.js';
+export type { Box, EdgeOut, Geometry, PlacedBox } from './geometry.js';
+export type { Anchor, DraftSlot } from './anchors.js';
+export { ZOOM_MAX, ZOOM_MIN } from './camera.js';
 export type ViewerExecution = {
     mode: 'worker';
     createWorker?: () => Worker;
@@ -25,6 +27,8 @@ export interface ViewerOptions {
      */
     outline?: 'visible' | 'hidden';
     execution?: ViewerExecution;
+    /** `auto` (default) hides slot bodies and shows titles again below a zoom of 0.4. */
+    detail?: 'auto' | 'full';
     render?: ViewerRenderOptions;
 }
 export interface UpdateOptions {
@@ -48,20 +52,27 @@ export type UpdateResult = {
     revision: number;
 };
 export interface ViewerEvents {
+    /** After each commit, after `anchor()`, and with `[]` before `destroy` detaches the targets. */
+    anchors: {
+        anchors: readonly Anchor[];
+    };
+    /** After each commit: the drawing, and where each item is (`null` for compare and states). */
     render: {
         revision: number;
         value: Extract<RenderResult, {
             ok: true;
         }>['value'];
+        geometry: Geometry | null;
     };
     diagnostics: {
         revision: number;
         diagnostics: readonly Diagnostic[];
         stale: boolean;
     };
+    /** At most once per animation frame, with the latest reason. */
     camera: {
         camera: Camera;
-        reason: 'user' | 'resize' | 'fit' | 'api';
+        reason: CameraReason;
     };
     itemactivate: {
         id: string;
@@ -69,20 +80,43 @@ export interface ViewerEvents {
         input: 'pointer' | 'keyboard';
         revision: number;
     };
+    /** `preventDefault()` stops the viewer opening the link. */
     link: {
         itemId: string;
         href: string;
         target: '_self' | '_blank';
         preventDefault(): void;
     };
+    /** A right-click or the menu key; `id` is null on the background. `preventDefault()` stops the browser's menu. */
+    contextmenu: {
+        id: string | null;
+        kind?: ItemKind;
+        clientX: number;
+        clientY: number;
+        preventDefault(): void;
+    };
 }
+export type ItemKind = 'node' | 'group' | 'edge';
 export interface ViewerHandle {
+    /** Resolves after the first commit or failure; then after each later one. */
+    readonly ready: Promise<UpdateResult>;
     update(source: string, options?: UpdateOptions): Promise<UpdateResult>;
+    /** Where each item is drawn, in world units. `null` before the first commit, and for compare and states. The same object for one revision. */
+    geometry(): Geometry | null;
     on<K extends keyof ViewerEvents>(type: K, listener: (event: ViewerEvents[K]) => void): () => void;
     getCamera(): Camera;
+    /** Zoom is clamped to `ZOOM_MIN`–`ZOOM_MAX`. */
     setCamera(camera: Camera): void;
-    fit(): void;
+    /** Frame these items, or the whole drawing without ids. At most actual size by default. */
+    fit(ids?: readonly string[], options?: FrameOptions): MoveResult;
+    /** The least move that shows the item; zooms out only if it does not fit. */
+    reveal(id: string, options?: FrameOptions): MoveResult;
     focusItem(id: string): boolean;
+    /**
+     * Plain-DOM hosts only: keep a target for each slot (`body:<id>`, `overlay:<id>`). Targets come
+     * in the `anchors` event; put content in them. The elements set this from their marked children.
+     */
+    anchor(slots: readonly DraftSlot[]): void;
     destroy(): void;
 }
 export declare function mountViewer(host: HTMLElement, options?: ViewerOptions): ViewerHandle;

package/dist/version-CKs2Vl8m.js

@@ -0,0 +1,4 @@
+const n = "0.4.0", o = n;
+export {
+  o as r
+};