@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/index.d.ts

@@ -0,0 +1,46 @@
+export { parseOrbitMarkdown, SUPPORTED_SCHEMA_VERSION } from './parser-markdown.js';
+export { DIAGNOSTIC_CODES, OrbitParseError, formatDiagnostic } from './diagnostics.js';
+export type { OrbitDiagnostic, OrbitDiagnosticCode, OrbitDiagnosticSeverity } from './diagnostics.js';
+export type { ParseOptions } from './parser-markdown.js';
+export { parseOrbitYAML } from './parser-yaml.js';
+export type { ParseYamlOptions } from './parser-yaml.js';
+export { serializeOrbitMarkdown } from './serializer-markdown.js';
+export type { SerializeOptions } from './serializer-markdown.js';
+export { serializeOrbitYAML } from './serializer-yaml.js';
+export { documentToRendererOptions } from './document-options.js';
+export { OrbitSVGRenderer } from './svg-renderer.js';
+export { createOrbitMap } from './create.js';
+export { renderToSVGString } from './render-to-svg.js';
+export { PRINT_THEMES, printTheme, renderPrintLayout } from './print-layout.js';
+export type { OrbitPrintOptions } from './print-layout.js';
+export { exportWebPage } from './web-page/page.js';
+export type { OrbitWebPageOptions } from './web-page/page.js';
+export { createMapTools } from './map-tools/tools.js';
+export type { MapTools, MapToolsOptions, MapToolResult } from './map-tools/tools.js';
+export type { MapToolDefinition, MapToolFormats, MapToolName, MapToolProvider } from './map-tools/definitions.js';
+export type { MapToolProperty, MapToolSchema } from './map-tools/input.js';
+export type { RenderToSVGOptions } from './render-to-svg.js';
+export { detectImportFormat, importMap } from './other-apps/import.js';
+export { importOPML, exportOPML } from './other-apps/opml.js';
+export type { OrbitOPMLOptions } from './other-apps/opml.js';
+export { importFreeMind } from './other-apps/freemind.js';
+export { importXMind } from './other-apps/xmind.js';
+export { IMPORT_ERROR_CODES, IMPORT_WARNING_CODES, OrbitImportError } from './other-apps/ideas.js';
+export type { OrbitImportErrorCode, OrbitImportWarning, OrbitImportWarningCode } from './other-apps/ideas.js';
+export type { OrbitImport, OrbitImportedMap, OrbitImportFormat, OrbitImportOptions } from './other-apps/reading.js';
+export { renderNoteMarkdown } from './ui/note-markdown.js';
+export type { NoteRenderContext as OrbitNoteOptions } from './ui/note-markdown.js';
+export type { CreateOrbitMapOptions } from './create.js';
+export { defineOrbitMapElement, renderOrbitElement, renderOrbitMarkdownBlocks } from './auto-render.js';
+export type { AutoRenderOptions, OrbitMapElement, OrbitRenderErrorDetail } from './auto-render.js';
+export { findNodeById, getNodePath } from './utils.js';
+export { ORBIT_THEME_PRESETS, THEME_TOKENS, isOrbitThemePreset, isThemeName, registerTheme, themeNames, themeTokens } from './themes.js';
+export type { OrbitThemeName, OrbitThemeToken, OrbitThemeTokens } from './themes.js';
+export { MATERIAL_SEED, materialTheme } from './material.js';
+export type { MaterialThemeOptions } from './material.js';
+export { registerAction, registerNodeType, registerStatus, upgradeNodeTypes } from './extensions.js';
+export { languageTags, registerLanguage } from './languages.js';
+export type { OrbitPluralText, OrbitStrings } from './languages.js';
+export type { OrbitAction, OrbitNodeType, OrbitStatusStyle, OrbitStatusTone } from './extensions.js';
+export type { OrbitDocument, OrbitDocumentOptions, ParsedOrbitDocument, OrbitNode, OrbitActionEvent, OrbitActionDetail, OrbitContentAction, OrbitEdit, OrbitEditorEvent, OrbitEventMap, OrbitEventName, OrbitInsets, OrbitMediaEvent, OrbitMediaOptions, OrbitMediaState, OrbitNewNode, OrbitNodeContextEvent, OrbitNodeDragEvent, OrbitNodeInput, OrbitRendererTheme, OrbitSpinOptions, OrbitThemePreset, OrbitZoomOptions, RendererOptions, ViewMode, } from './types.js';
+export { parseOrbit } from './dispatch.js';

package/dist/core/input-controller.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Pointer gestures for the map: tap, long press, spin (focus mode), pan
+ * (overview), pinch, wheel, double tap, and dragging a node that a held
+ * press lifted. The controller only recognizes gestures; the renderer
+ * decides what they do.
+ *
+ * Two properties are load-bearing for touch: pointerdown is never
+ * preventDefault-ed (that would suppress the `click` every tap relies on),
+ * and native scrolling is managed with `touch-action` in the stylesheet.
+ * Pointer capture is taken only once a drag engages, so taps keep native
+ * targeting.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** What a one-finger drag starting at a point does. */
+export type DragGesture = 'spin' | 'pan' | 'none';
+export interface GestureCallbacks {
+    isInteractive(): boolean;
+    /** What dragging from this point (container coordinates) does. */
+    dragGesture(point: Point): DragGesture;
+    /** The orbit's center on screen. */
+    spinCenter(): Point;
+    /** True while the orbit coasts: the next press catches it. */
+    isCoasting(): boolean;
+    onCatch(): void;
+    onSpinStart(time: number, angle: number): void;
+    onSpinMove(time: number, angle: number): void;
+    /** `cancelled` when the browser took the pointer over (to scroll, say): no fling. */
+    onSpinEnd(time: number, cancelled: boolean): void;
+    onPanStart(time: number): void;
+    onPan(deltaX: number, deltaY: number, time: number): void;
+    onPanEnd(time: number, cancelled: boolean): void;
+    /** Zoom by `factor` around `center`, and pan by how far the center moved. */
+    onPinch(factor: number, center: Point, deltaX: number, deltaY: number): void;
+    onPinchEnd(): void;
+    onWheel(event: WheelEvent, point: Point): void;
+    onDoubleTap(point: Point, target: EventTarget | null): void;
+    /**
+     * A touch or pen held still on `target`. Returns whether the map took it:
+     * the press then neither taps nor spins.
+     */
+    onLongPress(point: Point, target: EventTarget | null): boolean;
+    /**
+     * A press held still on `target`: whether it lifted a node, which moving
+     * the press then drags (see `onNodeDrag`). Touches and pens get here after
+     * `onLongPress`; a mouse held still gets here alone, with no menu.
+     */
+    onHold(point: Point, target: EventTarget | null): boolean;
+    /**
+     * The lifted node follows the press: `move` as it moves, then `drop` where
+     * it's let go (moved or not), or `cancel` when the press is taken away.
+     */
+    onNodeDrag(point: Point, phase: 'move' | 'drop' | 'cancel'): void;
+    /** How long (ms) a still touch takes to become a long press. */
+    longPressDelay(): number;
+    onDraggingChange(dragging: boolean): void;
+}
+export declare class InputController {
+    private element;
+    private readonly container;
+    private readonly callbacks;
+    private readonly pointers;
+    private gesture;
+    private engaged;
+    private startPoint;
+    private lastPoint;
+    /**
+     * Where the map was on the page when the pointers now down first touched
+     * it. Asking again on every move would make the browser lay out the whole
+     * map each time, thousands of elements on a big one, and a pointer can
+     * move several times a frame.
+     */
+    private gestureRectangle;
+    private lastPinchDistance;
+    private lastPinchCenter;
+    private suppressNextClick;
+    private lastTap;
+    private longPress;
+    /** The press became a long press: lifting it is no tap. */
+    private pressTaken;
+    /** The held press lifted a node: moving it drags the node. */
+    private lifted;
+    constructor(container: HTMLElement, callbacks: GestureCallbacks);
+    attach(element: Element): void;
+    detach(): void;
+    private reset;
+    private localPoint;
+    private angleOf;
+    private pinchDistance;
+    private pinchCenter;
+    private readonly handleClickCapture;
+    private readonly handlePointerDown;
+    private startLongPress;
+    private cancelLongPress;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    private detectDoubleTap;
+    private readonly handleDoubleClick;
+    /**
+     * A lifted node is dragged, not the page: the browser mustn't scroll it
+     * from under the press, as it would where `touch-action` lets one finger
+     * scroll the page (Chromium doesn't apply `touch-action` to the shapes
+     * inside an SVG, so the canvas's own decides).
+     */
+    private readonly handleTouchMove;
+    private readonly handleWheel;
+}
+/**
+ * Zoom factor for a wheel event: the same zoom per scrolled pixel for mouse
+ * wheels and trackpads. Trackpad pinches arrive as wheel events with
+ * `ctrlKey` and small pixel deltas, so they get a stronger multiplier; a
+ * mouse wheel turned with Ctrl held sends large deltas and keeps the normal one.
+ */
+export declare const wheelZoomFactor: (event: Pick<WheelEvent, "deltaY" | "deltaMode" | "ctrlKey">, pageHeight: number) => number;

package/dist/core/languages.d.ts

@@ -0,0 +1,201 @@
+/**
+ * The words Orbit shows and says: the controls, the detail sheet, the
+ * outline and what it announces, what a screen reader hears about each
+ * idea, the media viewer and the empty map. English and Spanish are built
+ * in; `registerLanguage` adds others, or changes words of one Orbit has.
+ *
+ * A map speaks the language its `language` option names, or else the one
+ * its element is in: the closest `lang` attribute around it, through shadow
+ * roots, then the document's. A language Orbit doesn't have falls back to
+ * its base (es-MX reads es), then to English.
+ */
+/**
+ * Text that depends on a number: one form for each plural category the
+ * language uses (see `Intl.PluralRules`), `other` for any it leaves out.
+ * `{count}` is the number, written the language's way.
+ */
+export interface OrbitPluralText {
+    zero?: string;
+    one?: string;
+    two?: string;
+    few?: string;
+    many?: string;
+    other: string;
+}
+/**
+ * Everything Orbit says, in one language. `{name}`-style placeholders are
+ * filled in as described on each; keep them in a translation, in any order.
+ */
+export interface OrbitStrings {
+    /** The map's name for assistive technology, and an exported SVG's title, when it has no `ariaLabel` and its root no text. */
+    mindMap: string;
+    /** What assistive technology calls the map (`aria-roledescription`), in lower case. */
+    mindMapRole: string;
+    /** An idea with no text, wherever its name shows. */
+    untitled: string;
+    /** The root Orbit makes up for a map that's just a list, or has several top headings, and no title. */
+    untitledMap: string;
+    /** The message on a map with nothing in it. */
+    emptyMap: string;
+    /** The hint under it. */
+    emptyMapHint: string;
+    /** The title of the card shown where a map couldn't be drawn. */
+    mapNotDrawn: string;
+    /** The card's message when the problem came with none of its own. */
+    mapNotDrawnReason: string;
+    /** The card's message for a problem on a line of the map's source: `{line}` and `{message}`, which stays as Orbit wrote it. */
+    problemOnLine: string;
+    /** The breadcrumbs, for assistive technology. */
+    mapPath: string;
+    /** The back button, when the idea it goes back to has no name. */
+    back: string;
+    /** The back button's label: `{name}` is the idea it goes back to. */
+    backTo: string;
+    /** The back button's label when that idea has no text. */
+    backToParent: string;
+    /** The group of view buttons. */
+    view: string;
+    /** The button that shows the focused idea with the ideas around it. */
+    focus: string;
+    /** The button that shows the whole map at once. */
+    overview: string;
+    /** The button that shows the map as a list. */
+    showOutline: string;
+    /** The group of zoom buttons. */
+    zoom: string;
+    zoomIn: string;
+    zoomOut: string;
+    /** The button that zooms to fit the view. */
+    fitMap: string;
+    /** Shown when the wheel scrolls the page over a map: `{key}` is Ctrl, or ⌘ on Apple devices. */
+    scrollToZoom: string;
+    /** The map as a list, for assistive technology. */
+    outline: string;
+    /** Announced when the overview opens. */
+    overviewAnnouncement: string;
+    /** How many ideas an idea holds, as announced and in its description: `{count}`. */
+    ideaCount: OrbitPluralText;
+    /** Announced when an idea is added: `{name}`. */
+    added: string;
+    /** Announced when an idea is deleted: `{name}`. */
+    removed: string;
+    /** Announced when an idea moves: `{name}` into `{parent}`. */
+    moved: string;
+    /** Announced when an idea moves to a parent with no text: `{name}`. */
+    movedToTop: string;
+    /** `{name}` in those announcements when the idea has no text. */
+    anIdea: string;
+    /** Part of an idea's description: `{status}` is its status word. */
+    status: string;
+    /** The status in the tooltip: `{status}`. */
+    statusLabel: string;
+    /** Part of an idea's description: `{list}` lists what it has, from the words below. */
+    has: string;
+    hasDetails: string;
+    hasNote: string;
+    hasImage: string;
+    hasVideo: string;
+    hasEmbed: string;
+    hasLink: string;
+    /** The text field over an idea being renamed: `{name}`. */
+    textOf: string;
+    /** The text field for a new idea: `{name}` is the idea it goes into. */
+    newIdeaFor: string;
+    /** The empty text field's placeholder for a new idea. */
+    newIdea: string;
+    /** The + in an orbit: `{name}` is the idea it adds to. */
+    addIdeaTo: string;
+    /** Where an idea being moved would land: `{name}` is that idea. */
+    moveHere: string;
+    /** `{name}` in the text fields and the + when the idea has no text. */
+    thisIdea: string;
+    /** `{name}` in `moveHere` when the idea has no text. */
+    theIdea: string;
+    /** The buttons under an idea: `{name}`. */
+    ideaActions: string;
+    /** The buttons under an idea with no text. */
+    ideaActionsUntitled: string;
+    showDetails: string;
+    viewImage: string;
+    /** The picture in the detail sheet, which opens the viewer: `{description}` is its alternative text. */
+    viewImageOf: string;
+    playVideo: string;
+    openEmbed: string;
+    readNote: string;
+    openLink: string;
+    /** A link to another idea of the map: `{name}` is that idea, or `theIdea` when it has no text. */
+    goTo: string;
+    /** The same link printed, where it can't be followed: `{name}` is that idea. */
+    seeIdea: string;
+    /** The detail sheet's name when the idea has no text. */
+    details: string;
+    close: string;
+    previous: string;
+    next: string;
+    /** The button that presents a map shared as a web page, one idea at a time with its note as a caption. */
+    present: string;
+    /** The priority chip: `{priority}`. */
+    priority: string;
+    /** The button over a video in the detail sheet. */
+    expand: string;
+    /** That button, for assistive technology. */
+    expandVideo: string;
+    /** A picture's name in the viewer when it has no description or caption. */
+    picture: string;
+    /** A video's name in the viewer when it has no caption. */
+    video: string;
+    /** Where the viewer is among the map's pictures and videos: `{index}` of `{total}`. */
+    position: string;
+    /** The viewer's button that zooms the picture to fit. */
+    fitPicture: string;
+    pictureUnavailable: string;
+    videoUnavailable: string;
+    /** A video its site doesn't let other pages play. */
+    videoUnavailableHere: string;
+    openPictureInNewTab: string;
+    openVideoInNewTab: string;
+    /** A video's link to its site: `{provider}` is YouTube or Vimeo. */
+    watchOn: string;
+}
+type TextKey = {
+    [Key in keyof OrbitStrings]: OrbitStrings[Key] extends string ? Key : never;
+}[keyof OrbitStrings];
+type CountKey = {
+    [Key in keyof OrbitStrings]: OrbitStrings[Key] extends OrbitPluralText ? Key : never;
+}[keyof OrbitStrings];
+type Values = Record<string, string | number>;
+/**
+ * Adds a language for every map, by its BCP 47 tag (`fr`, `pt-BR`), or
+ * changes some words of one Orbit has. Words it leaves out come from the
+ * language it narrows (`pt` for `pt-BR`), then English. Returns a function
+ * that puts the language back as it was.
+ */
+export declare const registerLanguage: (language: string, strings: Partial<OrbitStrings>) => () => void;
+/** The tags of the languages every map can speak: the built-in ones and the registered ones. */
+export declare const languageTags: () => string[];
+/**
+ * The language an element is in: the closest `lang` attribute around it,
+ * through shadow roots, then the document's. Null when none says.
+ */
+export declare const languageOf: (element: Element | null | undefined) => string | null;
+/** The words of one map: its language's, with the `strings` it was given on top. */
+export declare class OrbitWords {
+    /** The tag of the language the words come from: `es` for a map asked for `es-MX`. */
+    readonly language: string;
+    /** The tag numbers, plurals and lists are written for: `es-MX` there. */
+    readonly locale: string;
+    private readonly table;
+    constructor(requested?: string | null, strings?: Partial<OrbitStrings>);
+    /** Whether these words are the same as `other`'s: the same language and the same table. */
+    sameAs(other: OrbitWords | null): boolean;
+    text(key: TextKey, values?: Values): string;
+    /** A text with a number in it, in the form the number takes in the language. */
+    count(key: CountKey, count: number, values?: Values): string;
+    /** Items as the language lists them: "a, b and c". */
+    list(items: string[]): string;
+    number(value: number): string;
+    private fill;
+}
+/** The words a map speaks when it's asked for `requested`, or for the language around `element`. */
+export declare const wordsFor: (requested: string | undefined, element: Element | null | undefined, strings?: Partial<OrbitStrings>) => OrbitWords;
+export {};

package/dist/core/layout.d.ts

@@ -0,0 +1,61 @@
+import type { OrbitNode } from './types.js';
+/** Where the layout puts the map and how much room it has. */
+export interface LayoutConfig {
+    cx: number;
+    cy: number;
+    containerWidth: number;
+    containerHeight: number;
+    /** Levels below the layout root to render; deeper nodes are omitted. */
+    maxDepth?: number;
+    /**
+     * Focus layouts: ring radii to keep where the orbit has as many rings,
+     * instead of making room for the moons again. A drag along the orbit keeps
+     * the rings it began with. Rings never come out smaller than the planets need.
+     */
+    keptRings?: number[];
+}
+/** A node with its place in the layout. */
+export interface PositionedNode extends OrbitNode {
+    x: number;
+    y: number;
+    radius: number;
+    /** Degrees: 0 is right, -90 is up. */
+    angle: number;
+    /** Distance from the parent. */
+    orbitRadius: number;
+}
+/** Moons drawn around a planet; more children show as "+N". */
+export declare const MOON_LIMIT = 6;
+/** Where a planet's moons go: `distance` from its center, at `offsets` degrees from the direction away from the sun. */
+export interface MoonPlacement {
+    distance: number;
+    radius: number;
+    offsets: number[];
+}
+/** The moons of a planet fan out on its outer side, 30° apart, 150° at most. */
+export declare const moonPlacement: (planetRadius: number, moonCount: number) => MoonPlacement;
+/**
+ * Calculate layout for focus mode (center sun + direct children).
+ * The orbit radius is never clamped below the collision-free radius. If the
+ * result is wider than the container, the renderer auto-fits the whole group.
+ */
+export declare const calculateFocusLayout: (focusedNode: OrbitNode, config: LayoutConfig) => {
+    sun: PositionedNode;
+    planets: PositionedNode[];
+    orbitRadius: number;
+    orbitRings: number[];
+};
+/**
+ * Calculate layout for all mode. Each node owns a measured subtree circle; a
+ * parent's child orbit is sized so sibling subtree circles cannot overlap.
+ */
+export declare const calculateAllLayout: (node: OrbitNode, config: LayoutConfig, parentAngle?: number) => PositionedNode[];
+/**
+ * The rings of the overview: one around each node with children, through them.
+ */
+export declare const getOrbitRings: (positionedNodes: PositionedNode[]) => {
+    centerId: string;
+    cx: number;
+    cy: number;
+    r: number;
+}[];

package/dist/core/map-tools/definitions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The map tools as a model sees them: names, descriptions and inputs, and
+ * the shapes each provider's API takes them in.
+ */
+import { type Fields, type MapToolSchema } from './input.js';
+export type MapToolName = 'read_map' | 'find_nodes' | 'read_node' | 'add_nodes' | 'update_node' | 'move_node' | 'reorder_children' | 'remove_node' | 'show_node';
+/** A tool as `MapTools.definitions` lists it: the shape MCP uses, and the data to build any other. */
+export type MapToolDefinition = {
+    name: MapToolName;
+    description: string;
+    /** The tool's input, as JSON Schema. */
+    inputSchema: MapToolSchema;
+    /** Hints for clients that ask before running some tools: whether it only reads, and whether it can remove or overwrite what's there. */
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+    };
+};
+/** The tools in the shape each provider's API takes them. */
+export type MapToolFormats = {
+    /** Anthropic's Messages API (`tools`). */
+    anthropic: {
+        name: string;
+        description: string;
+        input_schema: MapToolSchema;
+    }[];
+    /** OpenAI's Responses API (`tools`). */
+    openai: {
+        type: 'function';
+        name: string;
+        description: string;
+        parameters: MapToolSchema;
+        strict: false;
+    }[];
+    /** OpenAI's Chat Completions API (`tools`), which most other providers and local servers take too. */
+    'openai-chat': {
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: MapToolSchema;
+        };
+    }[];
+    /** Google's Gemini API (`config.tools` in `@google/genai`). */
+    gemini: {
+        functionDeclarations: {
+            name: string;
+            description: string;
+            parametersJsonSchema: MapToolSchema;
+        }[];
+    }[];
+};
+export type MapToolProvider = keyof MapToolFormats;
+/** A tool, before it's written as a definition. */
+export interface ToolSpec {
+    name: MapToolName;
+    description: string;
+    fields: Fields;
+    /** Other names models give its fields, lowercase. */
+    synonyms?: Record<string, string>;
+    readOnly: boolean;
+    destructive: boolean;
+}
+/** The attributes `update_node` sets and `clear` removes. */
+export declare const ATTRIBUTES: readonly ["note", "status", "priority", "tags", "icon", "color", "link", "image", "video", "embed", "collapsed"];
+export type ToolAttribute = (typeof ATTRIBUTES)[number];
+/** Every tool, in the order they're offered. `show_node` is only for a map on screen. */
+export declare const TOOL_SPECS: readonly ToolSpec[];
+export declare const definitionOf: (spec: ToolSpec) => MapToolDefinition;
+/** The definitions in the shape `provider`'s API takes. */
+export declare const formatDefinitions: <Provider extends MapToolProvider>(definitions: readonly MapToolDefinition[], provider: Provider) => MapToolFormats[Provider];

package/dist/core/map-tools/input.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What each map tool takes, written once: as the JSON Schema a model reads,
+ * and as the checks a call goes through before anything changes. The checks
+ * forgive what models often send (a number as text, a list as words
+ * separated by commas, null for a field they leave out, a field's usual
+ * other name) and explain the rest in words a model can act on.
+ */
+export type FieldType = 'string' | 'integer' | 'number' | 'boolean' | 'list' | 'record';
+export interface Field {
+    type: FieldType;
+    description: string;
+    required?: boolean;
+    /** The words a list takes. */
+    values?: readonly string[];
+    /** The smallest number it takes. */
+    minimum?: number;
+    /** A record's own fields. Text alone stands for the first one: a picture's address for `{ src }`. */
+    fields?: Fields;
+}
+export type Fields = Record<string, Field>;
+/** A property of a tool's input, as JSON Schema. */
+export type MapToolProperty = {
+    type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object';
+    description: string;
+    minimum?: number;
+    items?: {
+        type: 'string';
+        enum?: string[];
+    };
+    properties?: Record<string, MapToolProperty>;
+    required?: string[];
+};
+/** A tool's input, as JSON Schema: an object with the tool's fields. */
+export type MapToolSchema = {
+    type: 'object';
+    properties: Record<string, MapToolProperty>;
+    required?: string[];
+};
+/** The JSON Schema for an object with `fields`. */
+export declare const schemaOf: (fields: Fields) => MapToolSchema;
+/** A call's input, read: its values, and the fields it gave that the tool doesn't take, which were left out. */
+export interface ReadInput {
+    values: Record<string, unknown>;
+    ignored: string[];
+}
+/** Thrown with a message for the model when a call's input can't be used. */
+export declare class InputError extends Error {
+}
+/**
+ * Reads a call's input for `tool`: an object, or the JSON text of one, as
+ * OpenAI sends it. Null stands for a field left out. A field under another
+ * name it often goes by (`synonyms`) counts as that field; one that looks
+ * like a misspelled field is an error, so nothing changes by mistake; any
+ * other is left out, and reported.
+ */
+export declare const readInput: (tool: string, fields: Fields, input: unknown, synonyms?: Readonly<Record<string, string>>) => ReadInput;
+/** Whether `record` has `key` of its own, not one every object inherits, such as `constructor`. */
+export declare const owns: (record: object, key: string) => boolean;
+/** A value, as an error message names it. */
+export declare const describe: (value: unknown) => string;
+/** "a, b and c" */
+export declare const list: (words: readonly string[]) => string;

package/dist/core/map-tools/reading.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The map as the tools describe it to a model: an outline with each node's
+ * id, everything about one node, and search results. Plain text, short on
+ * tokens: a line a node, with what an edit needs to know.
+ */
+import type { OrbitNode } from '../types.js';
+/** A node as the tools name it in a sentence: its title and id. */
+export declare const nameOf: (node: OrbitNode) => string;
+/** A node's line in an outline: its title, its id, and its attributes. */
+export declare const outlineLine: (node: OrbitNode, depth: number) => string;
+/** A node and `levels` levels under it as outline lines; what's further down is counted. */
+export declare const outlineOf: (node: OrbitNode, depth?: number, levels?: number) => string[];
+/**
+ * The outline read_map gives: `start` and up to `levels` levels under it,
+ * as many whole levels as fit in `limit` nodes, so the shape of a big map
+ * shows, with what's left out counted. `complete` when nothing asked for
+ * was left out.
+ */
+export declare const readOutline: (start: OrbitNode, levels: number, limit: number) => {
+    lines: string[];
+    complete: boolean;
+};
+/** How many nodes are under a node, at any depth. */
+export declare const descendants: (node: OrbitNode) => number;
+/** "1 node", "3 nodes" */
+export declare const count: (amount: number, one: string, many?: string) => string;
+/** Everything about a node, for read_node. */
+export declare const nodeDetails: (root: OrbitNode, node: OrbitNode, path: OrbitNode[]) => string;
+/** The nodes whose link, or a link in whose note, points at `target`. */
+export declare const nodesLinkingTo: (root: OrbitNode, target: OrbitNode) => OrbitNode[];
+/** Text as search compares it: lowercase, without accents. */
+export declare const searchable: (text: string) => string;
+/** What find_nodes looks for. */
+export interface Search {
+    query?: string;
+    status?: string;
+    tag?: string;
+}
+/** The nodes that match, titles matching first, as find_nodes lists them. */
+export declare const findNodes: (root: OrbitNode, search: Search) => string;

package/dist/core/map-tools/tools.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Map tools: what a language model needs to read a map and change it, from
+ * any provider. The definitions come in each provider's shape, and `run`
+ * carries out a call on a map on screen, where each change animates into
+ * place and fires `edit` as anyone's would, or on a document without one,
+ * on a server. A call that can't be carried out changes nothing and says
+ * why, in words a model can act on: the id it meant, a move that can't be
+ * made, a value the map can't use.
+ */
+import type { OrbitDocument } from '../types.js';
+import type { OrbitSVGRenderer } from '../svg-renderer.js';
+import { type MapToolDefinition, type MapToolFormats, type MapToolProvider } from './definitions.js';
+export interface MapToolsOptions {
+    /** Offer only the tools that read the map, for an assistant that answers questions about it. Default false. */
+    readOnly?: boolean;
+    /** The most nodes `read_map` shows at once; a bigger map is cut short, whole levels first. Default 250. */
+    readLimit?: number;
+}
+/** What a tool call did, to send back to the model. */
+export interface MapToolResult {
+    /** False when the call couldn't be carried out: nothing changed, and `text` says why and what to send instead. */
+    ok: boolean;
+    /** What happened, for the model, with the ids to use next. */
+    text: string;
+    /** Whether the map changed. */
+    changed: boolean;
+}
+/** Map tools for one map (see `createMapTools`). */
+export interface MapTools {
+    /** The tools: name, description, input as JSON Schema, and hints. The shape MCP takes, and the data for any other. */
+    readonly definitions: MapToolDefinition[];
+    /** How to use the tools, to add to the model's system prompt. */
+    readonly instructions: string;
+    /** The tools in the shape a provider's API takes: `anthropic`, `openai` (Responses), `openai-chat` (Chat Completions, and most other providers) or `gemini`. */
+    for<Provider extends MapToolProvider>(provider: Provider): MapToolFormats[Provider];
+    /**
+     * Carries out a tool call: its name, and its input as an object or as
+     * the JSON text OpenAI sends. Never throws for a call a model gets wrong:
+     * the result says what went wrong instead.
+     */
+    run(name: string, input?: unknown): MapToolResult;
+    /** The map as it is now. Edits change it in place. */
+    readonly document: OrbitDocument | null;
+}
+/**
+ * Tools a language model calls to read and edit a map: on screen (an
+ * `OrbitSVGRenderer`, such as `createOrbitMap` returns or `<orbit-map>`'s
+ * `renderer`), where each change animates and fires `edit`, or a document
+ * (or its markdown or YAML), which they change in place.
+ */
+export declare const createMapTools: (map: OrbitSVGRenderer | OrbitDocument | string, options?: MapToolsOptions) => MapTools;