@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/auto-render.d.ts

@@ -0,0 +1,85 @@
+import { OrbitSVGRenderer } from './svg-renderer.js';
+import type { OrbitMediaOptions, RendererOptions } from './types.js';
+import { type OrbitDiagnostic } from './diagnostics.js';
+export interface AutoRenderOptions extends RendererOptions {
+    selector?: string;
+    height?: number;
+    strict?: boolean;
+    className?: string;
+}
+/** Detail of the `orbit-error` event dispatched on an element whose map couldn't be drawn. */
+export interface OrbitRenderErrorDetail {
+    message: string;
+    line?: number;
+    error: Error | null;
+    diagnostics: OrbitDiagnostic[];
+}
+/**
+ * The `<orbit-map>` element's API, for code that holds a reference to one.
+ * It also dispatches the map's events (`orbit-focus-change`,
+ * `orbit-view-mode-change`, `orbit-node-click`, `orbit-action`,
+ * `orbit-spin-settle`, `orbit-media-open`, `orbit-media-close`,
+ * `orbit-media-state` and the rest) and `orbit-error`.
+ */
+export interface OrbitMapElement extends HTMLElement {
+    /** The markdown or YAML the map is drawn from. Setting it updates the `source` attribute. */
+    source: string;
+    /** The renderer drawing the map, or null before the first render or after an error. */
+    readonly renderer: OrbitSVGRenderer | null;
+    /** Re-reads the source and redraws the map, keeping the reader's place when it can. */
+    refresh(): void;
+    /** Flies to a node by id, in focus mode. Returns false when the map has no such node. */
+    flyTo(nodeId: string): boolean;
+    /** Flies out to the overview of the whole map. */
+    overview(): void;
+    /** Shows a node's picture or video in the media viewer (see `OrbitSVGRenderer.openMedia`). Returns false when there's nothing to show. */
+    openMedia(nodeId: string, options?: OrbitMediaOptions): boolean;
+    /** Closes the media viewer. */
+    closeMedia(): void;
+    /** Plays the video in the media viewer. Returns false when it shows none it can play. */
+    playMedia(): boolean;
+    /** Pauses the video in the media viewer. Returns false when it shows none it can pause. */
+    pauseMedia(): boolean;
+    /** Moves the video in the media viewer to `seconds` from its start. Returns false when it shows none it can move. */
+    seekMedia(seconds: number): boolean;
+    /** Turns on the sound of the video in the media viewer, from a press. Returns false when it shows none it can drive. */
+    unmuteMedia(): boolean;
+}
+/**
+ * Renders an orbit map into the given element. Problems in the document never
+ * throw: parse warnings go to the console, and a map that can't be drawn is
+ * replaced by an error card and an `orbit-error` event on the element.
+ *
+ * Callers who later detach the element should invoke
+ * `OrbitSVGRenderer.unmount(element)` to release RAF loops and the
+ * ResizeObserver. The `<orbit-map>` web component does this automatically.
+ */
+export declare const renderOrbitElement: (element: Element, options?: AutoRenderOptions) => OrbitSVGRenderer | null;
+/**
+ * Renders every orbit block under `root` (default: the whole document). Each
+ * block is independent: one that fails shows its error card and the rest
+ * still render.
+ */
+export declare const renderOrbitMarkdownBlocks: (root?: ParentNode, options?: AutoRenderOptions) => OrbitSVGRenderer[];
+/**
+ * Registers the `<orbit-map>` element. Write the map as the element's
+ * content (indent it however you like, `<!-- orbit … -->` comments included),
+ * inside a `<script type="text/orbit">` child, or in a `source` attribute.
+ * The map renders in a shadow root, so the raw markdown is never displayed,
+ * and it redraws when the content or an attribute changes.
+ *
+ * @example
+ * ```html
+ * <script type="module">
+ *   import { defineOrbitMapElement } from '@restless-dreams/orbit';
+ *   defineOrbitMapElement();
+ * </script>
+ *
+ * <orbit-map height="420" theme="night">
+ *   # Launch
+ *   ## Research <!-- orbit status: active -->
+ *   ## Build
+ * </orbit-map>
+ * ```
+ */
+export declare const defineOrbitMapElement: (tagName?: string) => void;

package/dist/core/branch-colors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Which of the palette's colors each top-level node takes, and how edits
+ * keep them. The root takes the palette's first color, and top-level nodes
+ * take the others in turn, cycling. A node with a `paletteColor` takes that
+ * one instead and gives up its turn, so the nodes after it keep theirs.
+ * Edits write a `paletteColor` where a node's turn would change, so adding,
+ * moving or removing a node never gives the others new colors.
+ */
+import type { OrbitNode } from './types.js';
+/** A node's own color, or its type's: what it shows instead of the palette's. */
+export type OwnColor = (node: OrbitNode) => string | undefined;
+/** What an edit needs to keep top-level nodes' colors. */
+export interface BranchColorRules {
+    /** How many colors top-level nodes take turns with: the palette's, after the root's (see `branchPalette`). */
+    count: number;
+    /** A node's own color or its type's, which it shows instead of the palette's. Default: its `color`. */
+    ownColor?: OwnColor;
+}
+/** Each top-level node's palette number before an edit, from `branchColorsBefore`. */
+export type BranchColors = Map<OrbitNode, number>;
+/** The node an edit was about, for `keepBranchColors`. */
+export interface EditedBranch {
+    node: OrbitNode;
+    /** Whether the node keeps the color it had (a move), rather than taking one no other top-level node has (a new node). */
+    keepsColor: boolean;
+}
+/** The colors top-level nodes take turns with: every palette color after the root's, or the only one. */
+export declare const branchPalette: (palette: readonly string[]) => string[];
+/** Whether a value is a palette number: a whole number from 1. */
+export declare const isPaletteNumber: (value: unknown) => value is number;
+/** The color a palette number names among `colors` (from `branchPalette`), cycling. */
+export declare const paletteColorOf: (colors: readonly string[], paletteNumber: number) => string;
+/**
+ * The palette number each of `branches` takes its color from: its
+ * `paletteColor`, or else the next number in turn that none of them has as
+ * its `paletteColor`. Nodes with a color or type of their own take a turn
+ * too, so the nodes after them have the colors they'd have without one.
+ */
+export declare const branchNumbers: (branches: readonly OrbitNode[], count: number) => Map<OrbitNode, number>;
+/** Each top-level node's palette number, to keep through an edit with `keepBranchColors`. */
+export declare const branchColorsBefore: (root: OrbitNode, rules: BranchColorRules) => BranchColors;
+/**
+ * After an edit, gives every top-level node that was there before the color
+ * it had, writing its palette number as its `paletteColor` where its turn
+ * changed. The node the edit was about keeps its color when it moved within
+ * the top level, takes one no other top-level node has when it's new there
+ * (while there is one), and drops its `paletteColor` when it left the top
+ * level, to take its new branch's color. Nodes showing a color or type of
+ * their own are left as they are, and a `paletteColor` is written only where
+ * a color would change otherwise.
+ *
+ * An edit that would write more numbers than the palette has colors writes
+ * none: that happens only where the top level has more nodes than colors,
+ * which repeat there anyway, and a big orbit's every node would get one.
+ * Returns the nodes it changed.
+ */
+export declare const keepBranchColors: (root: OrbitNode, before: BranchColors, rules: BranchColorRules, edited?: EditedBranch) => OrbitNode[];

package/dist/core/browser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What the browser draws with, checked once. A few effects need newer CSS:
+ * older browsers, such as the WebViews of phones that don't update theirs,
+ * get plainer versions of them instead of broken ones. Outside a browser (on
+ * a server, or tests without a DOM) everything counts as there.
+ */
+export declare const browser: {
+    /** CSS `color-mix()` (Chromium 111, Safari 16.2, Firefox 113). Without it, siblings keep their branch's own color. */
+    mixesColors: boolean;
+    /** The `translate` property (Chromium 104, Safari 14.1, Firefox 72). Without it, overlays are centered through their transform. */
+    translates: boolean;
+};
+/**
+ * Whether `element`'s page is used with a finger (`pointer: coarse`), where
+ * the stylesheet makes buttons bigger. The query is made once per window.
+ */
+export declare const pointsCoarsely: (element: Element) => boolean;
+/**
+ * The transform that puts an overlay at `x`, `y`. `centering` is the
+ * stylesheet's `translate` for it, as `translate()` takes it: where the
+ * browser lacks that property, the transform moves the overlay instead.
+ */
+export declare const overlayTransform: (x: number, y: number, centering: string) => string;

package/dist/core/create.d.ts

@@ -0,0 +1,23 @@
+import { OrbitSVGRenderer } from './svg-renderer.js';
+import type { OrbitDocument, OrbitNode, RendererOptions } from './types.js';
+export interface CreateOrbitMapOptions extends RendererOptions {
+    /** Throw on the first problem in the source instead of working around it. */
+    strict?: boolean;
+}
+/**
+ * Draws a map into `target` in one call: markdown or YAML source, a parsed
+ * document or a node tree. Returns the renderer, to listen for events
+ * (`renderer.on('focus-change', …)`), draw new versions (`renderer.render(source)`)
+ * and clean up (`renderer.destroy()`).
+ *
+ * The map fills `target`, so give it a height.
+ *
+ * @example
+ * ```ts
+ * import { createOrbitMap } from '@restless-dreams/orbit';
+ *
+ * const map = createOrbitMap(document.querySelector('#map')!, '# Launch\n## Research\n## Build', { theme: 'auto' });
+ * map.on('focus-change', ({ node }) => console.log(node.text));
+ * ```
+ */
+export declare const createOrbitMap: (target: HTMLElement, source: string | OrbitDocument | OrbitNode, options?: CreateOrbitMapOptions) => OrbitSVGRenderer;

package/dist/core/diagnostics.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parse diagnostics. Parsers are forgiving by default: a problem they can
+ * recover from is recorded as a diagnostic and parsing continues. In strict
+ * mode (`{ strict: true }`, used by `orbit validate`) the first such
+ * problem throws an `OrbitParseError` instead.
+ */
+import type { OrbitDocument } from './types.js';
+/** Every kind of problem the parsers report. */
+export declare const DIAGNOSTIC_CODES: readonly ["empty-document", "no-structure", "synthetic-root", "invalid-frontmatter", "unknown-frontmatter-key", "unsupported-schema-version", "format-upgraded", "invalid-attributes", "unknown-attribute", "invalid-option-value", "media-missing-source", "unknown-content-type", "caption-without-media", "unknown-link-target", "invalid-yaml", "unknown-yaml-key", "ignored-node-entry", "misnamed-node-key", "comment-without-orbit", "attributes-after-list"];
+export type OrbitDiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+export type OrbitDiagnosticSeverity = 'error' | 'warning';
+export interface OrbitDiagnostic {
+    code: OrbitDiagnosticCode;
+    message: string;
+    /** 1-based line in the source passed to the parser, when known. */
+    line?: number;
+    severity: OrbitDiagnosticSeverity;
+}
+export declare class OrbitParseError extends Error {
+    readonly code: OrbitDiagnosticCode;
+    readonly line: number;
+    constructor(message: string, line: number, code?: OrbitDiagnosticCode);
+}
+export declare const formatDiagnostic: (diagnostic: OrbitDiagnostic) => string;
+/**
+ * Reports a parsed document's problems to the console, the same signal from
+ * every entry point: each error as an error, then the other problems as one
+ * warning. A document without diagnostics reports its warnings alone.
+ */
+export declare const reportParseDiagnostics: (doc: OrbitDocument) => void;
+export declare class DiagnosticCollector {
+    readonly diagnostics: OrbitDiagnostic[];
+    private readonly strict;
+    constructor(strict: boolean);
+    /** A problem the parser works around: thrown in strict mode, recorded otherwise. */
+    recover(code: OrbitDiagnosticCode, message: string, line?: number, severity?: OrbitDiagnosticSeverity): void;
+    /** Worth knowing but never fatal, even in strict mode. */
+    note(code: OrbitDiagnosticCode, message: string, line?: number): void;
+    get warnings(): string[];
+}

package/dist/core/dispatch.d.ts

@@ -0,0 +1,23 @@
+import type { ParsedOrbitDocument } from './types.js';
+import type { ParseOptions } from './parser-markdown.js';
+/**
+ * Parses an orbit document in either flavor. Markdown is the default; a
+ * document is read as YAML when its first line is a top-level YAML key
+ * (`nodes:`, `title:`, `view:`, …), it has a top-level `nodes:` list, or its
+ * frontmatter says `flavor: yaml`. A fenced ```orbit block is unwrapped first.
+ *
+ * Problems the parser can work around are listed in `diagnostics` (each with
+ * a `code`, `line`, `severity` and a message that says how to fix it); pass
+ * `{ strict: true }` to throw an `OrbitParseError` on the first one instead.
+ *
+ * @example
+ * ```ts
+ * import { parseOrbit } from '@restless-dreams/orbit';
+ *
+ * const { root, diagnostics } = parseOrbit('# Launch\n## Research <!-- orbit status: active -->');
+ * for (const problem of diagnostics ?? []) console.warn(`line ${problem.line}: ${problem.message}`);
+ * ```
+ */
+export declare const parseOrbit: (input: string, options?: ParseOptions) => ParsedOrbitDocument;
+/** The flavor `parseOrbit` reads a document as: `markdown` or `yaml`. */
+export declare const orbitFlavor: (input: string) => "markdown" | "yaml";

package/dist/core/document-options.d.ts

@@ -0,0 +1,18 @@
+import type { OrbitDocumentOptions, RendererOptions } from './types.js';
+/** Document-level options accepted in markdown frontmatter and as YAML top-level keys. */
+export declare const DOCUMENT_OPTION_KEYS: Set<string>;
+/** Words people (and agents) reach for instead of a theme's name. */
+export declare const THEME_SYNONYMS: Record<string, string>;
+/** The message for a key that isn't a document option, with the option it probably means. */
+export declare const unknownOptionMessage: (key: string, place: "frontmatter" | "top-level") => string;
+/**
+ * Sets one document option from its frontmatter (or YAML top-level) value.
+ * A value that can't be used is left out and described to `report`.
+ */
+export declare const applyDocumentOption: (options: OrbitDocumentOptions, key: string, value: unknown, report?: (message: string) => void) => void;
+/**
+ * The renderer options a document asks for in its frontmatter (or YAML
+ * top-level keys). `title` becomes the map's accessible label. Container
+ * concerns (`height`, `className`) are left to the caller.
+ */
+export declare const documentToRendererOptions: (options: OrbitDocumentOptions) => RendererOptions;

package/dist/core/document-source.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Where a markdown document came from: its text, and which lines each node
+ * owns. Saving uses it to write back only what an edit changed, so a map
+ * written by hand (or by another app) keeps its own formatting, and
+ * everything Orbit doesn't read, through edits.
+ */
+import type { OrbitDocument, OrbitDocumentOptions, OrbitNode } from './types.js';
+/** What a line is to the node that owns it. */
+export type LineRole = 
+/** The frontmatter block, and blank lines before it. */
+'frontmatter'
+/** A heading or list item line (a setext heading's underline too), or the paragraph that names a generated root. */
+ | 'title'
+/** An `<!-- orbit … -->` block. */
+ | 'attributes'
+/** A picture or video line, and the comment after it that sets its caption or content type. */
+ | 'media'
+/** Text of the node's note: paragraphs, quotes, code, or headings under a list item. */
+ | 'note'
+/**
+ * The end of the document, which stays at its end: link and footnote
+ * definitions there (the root's note), and the blank lines around them.
+ */
+ | 'end'
+/** Text Orbit keeps without reading: other HTML comments, rules, attribute blocks it couldn't read. */
+ | 'foreign' | 'blank';
+/** How a node was written. */
+export type NodeShape = {
+    kind: 'heading';
+    level: number;
+    setext: boolean;
+}
+/** `indent` is the marker's column, `content` the column its text starts at. */
+ | {
+    kind: 'item';
+    indent: number;
+    marker: string;
+    content: number;
+}
+/** A root Orbit made up: named after the title or a lead paragraph (`lead`), or "Untitled map". */
+ | {
+    kind: 'generated';
+    lead: boolean;
+};
+/** A node's own fields, as they were read: to tell which ones an edit changed. */
+export type NodeFields = Pick<OrbitNode, 'id' | 'text' | 'icon' | 'link' | 'status' | 'tags' | 'color' | 'paletteColor' | 'priority' | 'collapsed' | 'type' | 'typeVersion' | 'note' | 'noteFormat' | 'image' | 'video' | 'embed' | 'attrs'>;
+export interface NodeRecord {
+    shape: NodeShape;
+    /** The title line, 0-based; null for a generated root without a lead paragraph. */
+    titleLine: number | null;
+    /** The lines the node and everything under it span, 0-based, end exclusive. */
+    start: number;
+    end: number;
+    /** Whether every line in the span is the node's or under it, so the span can be written back as one piece. */
+    contiguous: boolean;
+    /** Its children, in their order in the source. */
+    children: OrbitNode[];
+    fields: NodeFields;
+    /** Whether the node's id was written as an attribute (or would have to be). */
+    explicitId: boolean;
+}
+export interface DocumentSource {
+    /** The lines as the parser read them: line endings as `\n`, without a byte-order mark or shared indentation. */
+    lines: string[];
+    /** For each line, the node it belongs to (null for the frontmatter) and what it is there. */
+    owners: (OrbitNode | null)[];
+    roles: LineRole[];
+    records: WeakMap<OrbitNode, NodeRecord>;
+    root: OrbitNode;
+    /** The options as read, to tell which ones changed. */
+    options: OrbitDocumentOptions;
+    /** The frontmatter keys Orbit doesn't read, as read, to tell which ones changed. */
+    extra: Record<string, unknown>;
+    /** The frontmatter's fences, 0-based, when the document has frontmatter. */
+    frontmatter: {
+        open: number;
+        close: number;
+    } | null;
+    /** How the file was written, so it's written back the same way. */
+    encoding: SourceEncoding;
+}
+export interface SourceEncoding {
+    lineEnding: '\n' | '\r\n';
+    byteOrderMark: boolean;
+    /** Indentation every line shared (a map indented inside HTML or a template), put back on save. */
+    indentation: string;
+    /** Lines around the map that the parser unwrapped: a ```` ```orbit ```` fence. */
+    before: string[];
+    after: string[];
+}
+/** How a text is written: its line endings and byte-order mark. Indentation and wrapping are set where they're found. */
+export declare const encodingOf: (text: string) => SourceEncoding;
+/**
+ * The source a document's tree was read from, when it was read from
+ * markdown. Kept by the tree's root, off the document itself, so documents
+ * stay plain data that JSON leaves out, and a copy of a document with other
+ * options (or a map holding the tree) still saves from its source.
+ */
+export declare const documentSource: (document: Pick<OrbitDocument, "root">) => DocumentSource | undefined;
+/** Remembers where a document's tree came from (see `documentSource`). */
+export declare const setDocumentSource: (document: Pick<OrbitDocument, "root">, source: DocumentSource) => void;
+/** A copy of a node's own fields, deep enough that edits to the node don't reach it. */
+export declare const nodeFields: (node: OrbitNode) => NodeFields;
+/**
+ * Collects, while a document is parsed, which node owns each line and what
+ * the line is, then works out each node's span.
+ */
+export declare class SourceRecorder {
+    readonly owners: (OrbitNode | null)[];
+    readonly roles: (LineRole | undefined)[];
+    private readonly lines;
+    private readonly shapes;
+    constructor(lines: string[]);
+    /** Lines `first` to `last` (1-based, inclusive) belong to `node` as `role`. */
+    mark(first: number, last: number, node: OrbitNode | null, role: LineRole): void;
+    /** A line's text (1-based), as read. */
+    line(line: number): string;
+    /** How `node` was written, and its title line (1-based), if it has one. */
+    shape(node: OrbitNode, shape: NodeShape, titleLine: number | null): void;
+    /**
+     * The finished source. Blank lines nothing claimed go with the text they
+     * lead up to (an idea moved takes the blank line before it, and the
+     * paragraph after a list keeps the blank line that keeps it out of the
+     * list); at the end of the document, with the line above. Every line has
+     * an owner, so spans cover the whole document.
+     */
+    finish(root: OrbitNode, options: OrbitDocumentOptions, extra: Record<string, unknown>, frontmatter: DocumentSource['frontmatter'], explicitIds: ReadonlySet<OrbitNode>): DocumentSource;
+}

package/dist/core/editing.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Changes to a map's tree, behind the renderer's `addNode`, `updateNode`,
+ * `removeNode` and `moveNode`, and the map tools, which make them on a map
+ * that isn't drawn too. Ids follow the parsers' rules, so a map saved with
+ * `toMarkdown()` reads back with the same ids. Given the palette's rules,
+ * each change keeps the colors of the top-level nodes it doesn't change
+ * (see `keepBranchColors`).
+ */
+import type { OrbitNewNode, OrbitNode, OrbitNodeInput } from './types.js';
+import { type BranchColorRules } from './branch-colors.js';
+/** Every id in the tree. */
+export declare const nodeIds: (root: OrbitNode) => Set<string>;
+/** `base` when no node has it, otherwise `base-2`, `base-3`…, the way the parsers number repeated titles. */
+export declare const uniqueId: (base: string, taken: ReadonlySet<string>) => string;
+/**
+ * A new node with `input`'s text, attributes and children, each with an id
+ * from its text that no node in `taken` has, numbered in reading order as
+ * the parsers number repeated titles.
+ */
+export declare const createNode: (input: OrbitNewNode, taken: ReadonlySet<string>) => OrbitNode;
+/** What `createNode` takes to add a copy of `node`: its text, attributes and children, without its id or its place in a source. */
+export declare const newNodeFrom: (node: OrbitNode) => OrbitNewNode;
+/** Sets the text and attributes `changes` names. An attribute set to `undefined` is removed. */
+export declare const assignAttributes: (node: OrbitNode, changes: OrbitNodeInput) => void;
+/**
+ * Whether the node's id was made from its text, as the parsers make ids,
+ * rather than set with an `id` attribute: `research`, or `research-2` for
+ * a second "Research". Suffixes start at 2 (the parsers never make `-1`),
+ * so a hand-set `foo-1` is explicit.
+ */
+export declare const hasTextId: (node: OrbitNode) => boolean;
+/** Whether a link in the map, a node's link or one in a note, points at `node`. */
+export declare const isLinkedTo: (root: OrbitNode, node: OrbitNode) => boolean;
+/** Puts `node` among `parent`'s children at `index` (clamped; default last), with its levels and parent links. */
+export declare const insertChild: (parent: OrbitNode, node: OrbitNode, parentLevel: number, index?: number) => void;
+/** Takes `node` out of `parent`'s children. */
+export declare const detachChild: (parent: OrbitNode, node: OrbitNode) => void;
+/** Adds `input`, with its children, under `parentId` at `index` among its children (default: last). Null when there's no such parent. */
+export declare const addToTree: (root: OrbitNode, parentId: string, input: OrbitNewNode, index?: number, colors?: BranchColorRules) => {
+    node: OrbitNode;
+    parent: OrbitNode;
+} | null;
+/**
+ * Sets the text and attributes `changes` names on `id`. New text gives the
+ * node a new id when its id came from its text and no link points at it,
+ * so the saved map needs no id attribute. Null when there's no such node.
+ */
+export declare const updateInTree: (root: OrbitNode, id: string, changes: OrbitNodeInput, colors?: BranchColorRules) => {
+    node: OrbitNode;
+    previousId: string;
+} | null;
+/** Takes `id` and everything under it out of the tree. Null when there's no such node, or for the root. */
+export declare const removeFromTree: (root: OrbitNode, id: string, colors?: BranchColorRules) => {
+    node: OrbitNode;
+    parent: OrbitNode;
+} | null;
+/**
+ * Moves `id`, with everything under it, under `parentId` at `index` among
+ * its children (default: last). Null when either node is missing, the node
+ * is the root, or `parentId` is inside it.
+ */
+export declare const moveInTree: (root: OrbitNode, id: string, parentId: string, index?: number, colors?: BranchColorRules) => {
+    node: OrbitNode;
+    from: OrbitNode;
+    to: OrbitNode;
+} | null;

package/dist/core/engine/animation-clock.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One animation loop per map. Tasks (camera flights, spin, transitions,
+ * glides) advance with real elapsed time, then the map paints once per
+ * frame. The loop sleeps as soon as nothing is moving.
+ */
+/**
+ * Advances one animation. Returns `true` while it still has work to do,
+ * `false` once it's done, or `'hold'` to keep running without anything to
+ * paint this frame (a motion too slow to show on every frame). A task that
+ * throws is reported and dropped, so the loop carries on.
+ */
+export type FrameTask = (now: number, elapsed: number) => boolean | 'hold';
+type Scheduler = (callback: (now: number) => void) => number;
+type Canceller = (handle: number) => void;
+export declare class AnimationClock {
+    private readonly paint;
+    private readonly schedule;
+    private readonly cancel;
+    private readonly tasks;
+    private frameHandle;
+    private previousTime;
+    private paintRequested;
+    constructor(paint: () => void, schedule?: Scheduler, cancel?: Canceller);
+    /** Runs `task` every frame until it returns false. Returns a function that removes it. */
+    add(task: FrameTask): () => void;
+    /** Paints once on the next frame, without adding a task. */
+    requestPaint(): void;
+    get isRunning(): boolean;
+    stop(): void;
+    private wake;
+    private readonly tick;
+}
+/** Ease-in-out cubic, for camera flights and node morphs. */
+export declare const easeInOutCubic: (progress: number) => number;
+/** Ease-out cubic, for entrances and small settles. */
+export declare const easeOutCubic: (progress: number) => number;
+/** Maps `progress` from the window [start, end] to [0, 1], clamped. */
+export declare const within: (progress: number, start: number, end: number) => number;
+export declare const interpolate: (from: number, to: number, progress: number) => number;
+export {};

package/dist/core/engine/camera.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Camera math. A camera is the world point shown at the viewport's center
+ * and a zoom factor. Everything is plain geometry so it can be unit-tested
+ * without a DOM.
+ */
+export interface Camera {
+    x: number;
+    y: number;
+    scale: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/** Maps world points onto the screen: `p ↦ (p − center) × scale + viewport center`. */
+export declare const worldToScreen: (camera: Camera, viewport: Viewport, point: Point) => Point;
+export declare const screenToWorld: (camera: Camera, viewport: Viewport, point: Point) => Point;
+/** SVG `transform` for the world group. */
+export declare const cameraTransform: (camera: Camera, viewport: Viewport) => string;
+/** Zooms by `factor` keeping the world point under `anchor` (screen coordinates) in place. */
+export declare const zoomAround: (camera: Camera, viewport: Viewport, factor: number, anchor: Point) => Camera;
+/** Moves the camera so the content shifts by a screen-space delta. */
+export declare const panBy: (camera: Camera, deltaX: number, deltaY: number) => Camera;
+/**
+ * A camera that keeps `center` at the middle of the viewport and fits
+ * content reaching `extent` away from it on each axis, inside `padding`.
+ */
+/** Room the page's own controls take at the viewport's edges, in px. */
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export declare const NO_INSETS: Insets;
+/**
+ * The camera that shows `extent` around `center`, `padding` px from the
+ * edges of what `insets` leave of the viewport, and centered there.
+ */
+export declare const fitAround: (center: Point, extent: Point, viewport: Viewport, padding: number, maximumScale: number, insets?: Insets) => Camera;
+/** A similarity transform `p ↦ p × scale + (x, y)`, used to place one scene inside another. */
+export interface Similarity {
+    scale: number;
+    x: number;
+    y: number;
+}
+export declare const IDENTITY: Similarity;
+export declare const applySimilarity: (transform: Similarity, point: Point) => Point;
+export declare const invertSimilarity: (transform: Similarity) => Similarity;
+/** `outer ∘ inner`: apply `inner` first, then `outer`. */
+export declare const composeSimilarity: (outer: Similarity, inner: Similarity) => Similarity;
+/** The same view expressed in coordinates transformed by `transform`. */
+export declare const transformCamera: (transform: Similarity, camera: Camera) => Camera;
+export interface CameraPath {
+    /** The camera at `progress` ∈ [0, 1]. */
+    at(progress: number): Camera;
+    /** Path length in the paper's units; flights take time proportional to it. */
+    length: number;
+}
+/**
+ * Van Wijk & Nuij, "Smooth and efficient zooming and panning" (2003): the
+ * path that zooms out a little, travels, then zooms in, so the start and the
+ * destination stay in view for as long as possible. It is the same path
+ * d3's `interpolateZoom` follows.
+ */
+export declare const smoothZoomPath: (from: Camera, to: Camera, viewport: Viewport) => CameraPath;

package/dist/core/engine/colors.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Small color helpers: parse the formats browsers report for computed
+ * colors, mix in OKLab like CSS `color-mix(in oklab, …)`, measure WCAG
+ * contrast to choose label colors, and resolve the map's theme tokens into
+ * plain hex colors for exports that leave the page.
+ */
+/** sRGB channels and alpha, each 0–1. */
+export interface Rgb {
+    red: number;
+    green: number;
+    blue: number;
+    alpha: number;
+}
+export declare const parseColor: (input: string) => Rgb | null;
+export declare const toHex: (color: Rgb) => string;
+/** A color's OKLCH coordinates: lightness (0–1), chroma and hue in degrees. */
+export interface Oklch {
+    lightness: number;
+    chroma: number;
+    hue: number;
+}
+export declare const toOklch: (color: Rgb) => Oklch;
+/**
+ * A color of `hue` (OKLCH degrees) at a Material tone: as much of `chroma` as
+ * sRGB can show at that luminance, so every hue at one tone has the same
+ * contrast with every other tone.
+ */
+export declare const toneColor: (hue: number, chroma: number, tone: number) => Rgb;
+/** `color-mix(in oklab, first amount, second)` with `amount` from 0 to 1. */
+export declare const mixOklab: (first: Rgb, second: Rgb, amount: number) => Rgb;
+/** WCAG relative luminance (0–1) of a color's sRGB channels, ignoring alpha. */
+export declare const relativeLuminance: (color: Rgb) => number;
+/** WCAG contrast ratio (1–21) between two opaque colors. */
+export declare const contrastRatio: (first: Rgb, second: Rgb) => number;
+/**
+ * Whether `lightText` reads better than `darkText` on `fill`: the one with
+ * more contrast wins, a tie going to the light text. When the text colors
+ * can't be parsed, light text goes on fills darker than mid-gray.
+ */
+export declare const prefersLightText: (fill: string, lightText: string, darkText: string) => boolean;
+/** A color as an opaque hex value and an opacity, for SVG attributes that design tools read. */
+export declare const splitAlpha: (color: string) => {
+    color: string;
+    opacity: number;
+};
+/**
+ * Resolves `var(--_orbit-token)` references and `color-mix(in oklab, …)`
+ * into a hex color using concrete token values. Returns the input unchanged
+ * when part of it can't be resolved.
+ */
+export declare const resolveColor: (value: string, tokens: Record<string, string>) => string;