@restless-dreams/orbit 0.1.0 → 0.2.0

package/dist/{chunk-7n00wx0t.js → chunk-y748hzcr.js}

@@ -17,7 +17,7 @@ import {
   exportDisplay,
   escapeXml,
   MapExtensions
-} from "./chunk-mtrnm0yc.js";
+} from "./chunk-fkdfgtx9.js";
 
 // src/core/render-to-svg.ts
 var MAX_SVG_EXPORT_SIZE = 1e6;
@@ -79,4 +79,4 @@ var emptyMap = (title, message, viewport, tokens, responsive) => {
 export { renderToSVGString2 };
 
 //# debugId=FAD148488126235164756E2164756E21
-//# sourceMappingURL=chunk-7n00wx0t.js.map
+//# sourceMappingURL=chunk-y748hzcr.js.map

package/dist/{chunk-0gwh723s.js → chunk-zze4tc9n.js}

@@ -9,7 +9,7 @@ import {
   parseOrbit2,
   wordsFor,
   OrbitSVGRenderer2
-} from "./chunk-mtrnm0yc.js";
+} from "./chunk-fkdfgtx9.js";
 
 // src/core/auto-render.ts
 var DEFAULT_SELECTOR = ".orbit-mind-map[data-orbit], pre > code.language-orbit, pre.orbit-rendered[data-orbit-source], orbit-map";
@@ -405,4 +405,4 @@ var applyClassNames = (element, className) => {
 export { renderOrbitElement2, renderOrbitMarkdownBlocks2, defineOrbitMapElement2 };
 
 //# debugId=46D6FAE5FFE8EFBC64756E2164756E21
-//# sourceMappingURL=chunk-0gwh723s.js.map
+//# sourceMappingURL=chunk-zze4tc9n.js.map

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/document-source.d.ts

@@ -43,7 +43,7 @@ export type NodeShape = {
     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' | 'priority' | 'collapsed' | 'type' | 'typeVersion' | 'note' | 'noteFormat' | 'image' | 'video' | 'embed' | 'attrs'>;
+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. */

package/dist/core/editing.d.ts

@@ -2,9 +2,12 @@
  * 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.
+ * `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. */
@@ -33,7 +36,7 @@ export declare const insertChild: (parent: OrbitNode, node: OrbitNode, parentLev
 /** 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) => {
+export declare const addToTree: (root: OrbitNode, parentId: string, input: OrbitNewNode, index?: number, colors?: BranchColorRules) => {
     node: OrbitNode;
     parent: OrbitNode;
 } | null;
@@ -42,12 +45,12 @@ export declare const addToTree: (root: OrbitNode, parentId: string, input: Orbit
  * 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) => {
+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) => {
+export declare const removeFromTree: (root: OrbitNode, id: string, colors?: BranchColorRules) => {
     node: OrbitNode;
     parent: OrbitNode;
 } | null;
@@ -56,7 +59,7 @@ export declare const removeFromTree: (root: OrbitNode, id: string) => {
  * 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) => {
+export declare const moveInTree: (root: OrbitNode, id: string, parentId: string, index?: number, colors?: BranchColorRules) => {
     node: OrbitNode;
     from: OrbitNode;
     to: OrbitNode;

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

@@ -129,10 +129,11 @@ export declare const CROWDED_ORBIT = 48;
 export declare const fitScene: (scene: Scene, viewport: Viewport, insets?: Insets, below?: number) => Camera;
 /**
  * One color per node, the same in every view. The root uses the first
- * palette entry; each top-level branch takes the next; deeper nodes use
- * their branch's color, mixed toward the theme's `shade-light` or
- * `shade-dark` by position so siblings stay distinguishable. A node's own
- * color always wins: its `color`, or its type's (see `ownColor`).
+ * palette entry; top-level branches take the others in turn (see
+ * `branchNumbers`); deeper nodes use their branch's color, mixed toward the
+ * theme's `shade-light` or `shade-dark` by position so siblings stay
+ * distinguishable. A node's own color always wins: its `color`, or its
+ * type's (see `ownColor`); then its `paletteColor`.
  */
 export declare const assignNodeColors: (tree: OrbitNode, palette: string[], ownColor?: (node: OrbitNode) => string | undefined) => Map<string, string>;
 /** How much of the branch color each sibling keeps, and what the rest is mixed with. */

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

@@ -80,14 +80,20 @@ export declare const createDefinitions: (ids: ViewIds) => SVGDefsElement;
 export declare const turnShading: (defs: SVGDefsElement, ids: ViewIds, turn: number) => void;
 /** Labels and the assistive name of a node, in the map's language (English without one). */
 export declare const describeNode: (node: OrbitNode, hiddenChildren: number, visibleChildren: number, extensions?: MapExtensions, words?: OrbitWords) => string;
-/** The on-screen radius (px) below which flat bodies are specks, at `pixelRatio` device pixels per px. */
-export declare const speckRadius: (pixelRatio: number) => number;
+/**
+ * The on-screen radius (px) below which flat bodies are specks, at
+ * `pixelRatio` device pixels per px: bigger for a `plainCrowded` planet, one
+ * of a crowded orbit without badges (a status, a note's marker, a play button).
+ */
+export declare const speckRadius: (pixelRatio: number, plainCrowded?: boolean) => number;
 /** What every node is drawn with this frame, besides its own place (see `NodeView.update`). */
 export interface NodeDrawing {
     /** In an orbit turned as one, the degrees it's turned (see `OrbitTurn`). */
     turn?: number;
     /** The on-screen radius (px) below which flat bodies are specks (see `speckRadius`). */
     speckRadius: number;
+    /** The same for a crowded orbit's planets without badges. */
+    crowdedSpeckRadius: number;
     /**
      * How many more nodes may become specks, or stop being them, this frame.
      * The rest wait for the next: a zoom across the size where a whole orbit
@@ -119,6 +125,8 @@ export declare class NodeView {
     readonly typeName: string | undefined;
     /** Shows a picture (an image, or a video's thumbnail) rather than a plain color. */
     hasImage: boolean;
+    /** Shows a status, a note's marker or a play button: a crowded orbit's planet with one stays a body down to the usual size (see `speckRadius`). */
+    private readonly hasBadges;
     private readonly body;
     private readonly disc;
     private readonly shade;

package/dist/core/index.d.ts

@@ -11,6 +11,8 @@ 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';
@@ -18,6 +20,14 @@ export type { MapTools, MapToolsOptions, MapToolResult } from './map-tools/tools
 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';

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

@@ -66,6 +66,13 @@ export declare class InputController {
     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;

package/dist/core/languages.d.ts

@@ -125,6 +125,8 @@ export interface OrbitStrings {
     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;

package/dist/core/node-attributes.d.ts

@@ -15,7 +15,7 @@ export declare const readImage: (value: unknown) => ImageMedia | undefined;
 export declare const readVideo: (value: unknown) => VideoMedia | undefined;
 export declare const readEmbed: (value: unknown) => EmbedMedia | undefined;
 /** The attributes every node takes, in `<!-- orbit … -->` blocks and in YAML. */
-export declare const NODE_ATTRIBUTE_KEYS: readonly ["color", "icon", "status", "priority", "tags", "collapsed", "link", "note", "noteFormat", "image", "video", "embed", "caption", "id", "type"];
+export declare const NODE_ATTRIBUTE_KEYS: readonly ["color", "paletteColor", "icon", "status", "priority", "tags", "collapsed", "link", "note", "noteFormat", "image", "video", "embed", "caption", "id", "type"];
 /** Keys a flavor accepts besides the node attributes, and the words that stand in for them. */
 export interface AttributeVocabulary {
     keys: readonly string[];

package/dist/core/other-apps/freemind.d.ts

@@ -0,0 +1,8 @@
+/**
+ * FreeMind and Freeplane maps (`.mm`): nodes with their text (plain, or
+ * HTML), notes and Freeplane's details, links and arrow links, folds, icons,
+ * background colors, attributes and pictures.
+ */
+import { type OrbitImport, type OrbitImportOptions } from './reading.js';
+/** A FreeMind or Freeplane map, from its file's bytes or text. */
+export declare const importFreeMind: (data: Uint8Array | string, options?: OrbitImportOptions) => OrbitImport;

package/dist/core/other-apps/icons.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Other apps' icons and markers, as Orbit says the same thing: an emoji for
+ * the idea's icon, a priority, or a status. An icon with no meaning here
+ * returns null, and the reader warns that it was left out.
+ */
+export type IconMeaning = {
+    icon: string;
+} | {
+    priority: number;
+} | {
+    status: string;
+};
+/** A FreeMind or Freeplane icon's meaning: `full-3` is priority 3, `100%` done, `emoji-1F680` 🚀. */
+export declare const freeMindIcon: (name: string) => IconMeaning | null;
+/** An XMind marker's meaning: `priority-2` is priority 2, `task-done` done, `flag-red` 🚩. */
+export declare const xmindMarker: (markerId: string) => IconMeaning | null;

package/dist/core/other-apps/ideas.d.ts

@@ -0,0 +1,76 @@
+/**
+ * What every reader of another app's file builds: a tree of ideas with what
+ * Orbit can show of each, the warnings for what it can't, and the step that
+ * turns the tree into an Orbit document, with ids the parsers would give it
+ * and links between ideas pointing at those ids.
+ */
+import type { OrbitDocument } from '../types.js';
+import { type ImportedNote } from './notes.js';
+/** Every kind of warning reading another app's map gives. */
+export declare const IMPORT_WARNING_CODES: readonly ["floating-ideas-moved", "summaries-moved", "callouts-moved", "boundaries-in-notes", "links-in-notes", "missing-link-targets", "icons-not-kept", "pictures-not-kept", "attachments-not-kept", "local-links-not-kept", "encrypted-branches-not-read", "formatting-not-kept"];
+export type OrbitImportWarningCode = (typeof IMPORT_WARNING_CODES)[number];
+/** Something the other app's map had that Orbit keeps another way, or can't keep. */
+export interface OrbitImportWarning {
+    code: OrbitImportWarningCode;
+    message: string;
+    /** How many places in the map it's about. */
+    count: number;
+}
+/** Every reason a file can't be read as a map. */
+export declare const IMPORT_ERROR_CODES: readonly ["unknown-format", "unreadable", "empty", "password-protected", "too-large"];
+export type OrbitImportErrorCode = (typeof IMPORT_ERROR_CODES)[number];
+/** A file that can't be read as a map at all. */
+export declare class OrbitImportError extends Error {
+    readonly code: OrbitImportErrorCode;
+    constructor(code: OrbitImportErrorCode, message: string);
+}
+/** The most ideas a map read from another app may have. */
+export declare const MAX_IMPORTED_IDEAS = 100000;
+/** The deepest a map read from another app may go. */
+export declare const MAX_IMPORTED_DEPTH = 500;
+/** A link from one idea to another, by the other app's id for it. */
+export interface IdeaLink {
+    target: string;
+    /** What the other app calls the link, if anything. */
+    label?: string;
+}
+/** An idea as a reader finds it, before it becomes a node. */
+export interface ImportedIdea {
+    text: string;
+    /** The other app's id for it, which links between ideas point at. */
+    sourceId?: string;
+    /** Its note, in parts: they're joined in order. */
+    notes: ImportedNote[];
+    /** A web or mail address. */
+    link?: string;
+    /** Links to other ideas: the first one becomes the idea's link when it has none, the others go in its note. */
+    ideaLinks: IdeaLink[];
+    collapsed?: boolean;
+    status?: string;
+    priority?: number;
+    tags: string[];
+    /** Emoji for its icons, in order: Orbit shows the first. */
+    icons: string[];
+    color?: string;
+    /** Its picture: a web address, or a file in the map's `media`. */
+    image?: string;
+    children: ImportedIdea[];
+}
+export declare const newIdea: (text: string) => ImportedIdea;
+/** The warnings for one map, each kind counted once with a few examples. */
+export declare class ImportReport {
+    private readonly found;
+    add(code: OrbitImportWarningCode, example?: string): void;
+    /** The warnings in the order of `IMPORT_WARNING_CODES`. */
+    get warnings(): OrbitImportWarning[];
+}
+/** A title on one line, as Orbit keeps titles: line breaks, tabs and runs of spaces become one space; other spaces stay as they are. */
+export declare const oneLine: (text: string) => string;
+/** A link in a note to the idea with this id in the other app: it points at the idea's Orbit id once the map is built. */
+export declare const sourceLink: (sourceId: string) => string;
+/**
+ * The tree as an Orbit document: titles on one line, an emoji at the start
+ * of a title as the idea's icon (as Orbit's markdown reads it), ids from the
+ * titles as the parsers give them, and links between ideas pointing at them.
+ */
+export declare const buildDocument: (rootIdea: ImportedIdea, report: ImportReport) => OrbitDocument;

package/dist/core/other-apps/import.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Maps from other apps: OPML from outliners and most mind map apps,
+ * FreeMind and Freeplane's `.mm`, and XMind's `.xmind`. `importMap` tells
+ * the format from the file's name or what it holds and reads it into Orbit
+ * maps, with the pictures inside the file and warnings for what Orbit keeps
+ * another way or couldn't keep.
+ */
+import type { OrbitImport, OrbitImportFormat, OrbitImportOptions } from './reading.js';
+/**
+ * The format of another app's map, from what the file holds, then from its
+ * name; null when it's none Orbit reads. Orbit's own markdown and YAML, and
+ * its zips, are null too: read those with `parseOrbit`.
+ */
+export declare const detectImportFormat: (data: Uint8Array | string, name?: string) => OrbitImportFormat | null;
+/**
+ * Another app's map as Orbit maps: OPML, FreeMind and Freeplane, or XMind.
+ * Pass the file's bytes (its text works for OPML and `.mm`) and its name.
+ * Throws an `OrbitImportError` for a file it can't read: one in no format it
+ * knows (`unknown-format`), a damaged one (`unreadable`), one with no ideas
+ * (`empty`), an XMind workbook with a password (`password-protected`), or one
+ * past its limits (`too-large`).
+ *
+ * ```ts
+ * const { maps } = importMap(bytes, { name: 'Trip.xmind' });
+ * const markdown = serializeOrbitMarkdown(maps[0].document);
+ * ```
+ */
+export declare const importMap: (data: Uint8Array | string, options?: OrbitImportOptions) => OrbitImport;

package/dist/core/other-apps/inflate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Inflate (RFC 1951), the compression inside zip files, read synchronously
+ * and without `DecompressionStream`: the oldest browsers Orbit draws in
+ * can't decompress raw deflate data, and a command line has no need to wait.
+ * Codes are decoded the canonical way, a bit at a time, which is plenty fast
+ * for the few megabytes a map holds.
+ */
+/** Data that isn't valid deflate data, or holds more than it said it would. */
+export declare class InflateError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raw deflate data, inflated. `expected` sizes the output when it's known
+ * (a zip entry says so); the output never grows past `limit`, so a small
+ * file can't unpack into an enormous one.
+ */
+export declare const inflate: (data: Uint8Array, options?: {
+    expected?: number;
+    limit?: number;
+}) => Uint8Array;
+/** The CRC-32 zip files check their entries with. */
+export declare const crc32: (bytes: Uint8Array) => number;

package/dist/core/other-apps/markup.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A small XML reader for other apps' map files, and a forgiving reader for
+ * the HTML in their notes. Neither loads anything a file points to: XML
+ * reads its five entities and numeric references only, HTML adds a fixed
+ * table of common named ones, a DOCTYPE is skipped without reading what it
+ * declares, and the size of the input and the depth of nesting are capped.
+ */
+export interface MarkupElement {
+    /** The element's name as written, with its prefix: `xhtml:p`. */
+    name: string;
+    /** The name without a prefix, lowercased in HTML: `p`. */
+    localName: string;
+    /** Attributes by name as written, values decoded. */
+    attributes: Record<string, string>;
+    children: MarkupNode[];
+}
+/** An element, or text. */
+export type MarkupNode = MarkupElement | string;
+/** A file that isn't well-formed XML, or too big or too deep to read. */
+export declare class MarkupError extends Error {
+    /** The 1-based line of the problem. */
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+/** The most characters a file may have: far beyond any map, short of exhausting memory. */
+export declare const MAX_MARKUP_LENGTH: number;
+/** The deepest nesting read: deeper files are refused rather than risking the stack. */
+export declare const MAX_MARKUP_DEPTH = 1000;
+/**
+ * An XML file's bytes as text, in the encoding its byte order mark or its
+ * declaration names (UTF-8 when neither does). Old OPML files are often
+ * ISO-8859-1. A file that isn't valid UTF-8 and names no encoding is read as
+ * Windows-1252, which every byte is.
+ */
+export declare const decodeMarkup: (bytes: Uint8Array) => string;
+/**
+ * The document element of an XML file. Throws a `MarkupError` for a file
+ * that isn't well-formed, so a damaged map is refused rather than read in part.
+ */
+export declare const parseXml: (text: string) => MarkupElement;
+/** A piece of HTML, as the children of an element named `#fragment`. Never throws for markup it can read some way. */
+export declare const parseHtml: (text: string) => MarkupElement;
+export declare const isElement: (node: MarkupNode) => node is MarkupElement;
+/** The element's child elements, all of them or those with one local name. */
+export declare const childElements: (element: MarkupElement, localName?: string) => MarkupElement[];
+/** The element's first child element with this local name. */
+export declare const childElement: (element: MarkupElement, localName: string) => MarkupElement | undefined;
+/** An attribute by its name without a prefix: `href` finds `xlink:href`. */
+export declare const attributeOf: (element: MarkupElement, localName: string) => string | undefined;
+/** All the text inside an element, as written. */
+export declare const textContent: (node: MarkupNode) => string;

package/dist/core/other-apps/notes.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Notes and titles from other apps. HTML notes become markdown (paragraphs,
+ * headings, lists, quotes, code, bold, italic, strikethrough, links and
+ * pictures), never HTML. When markdown would show the note's text any other
+ * way (a `*` or `_` in it, a line that starts like a list), the note is kept
+ * as plain text instead, exactly as written: formatting can be lost, words
+ * never are.
+ */
+import { type MarkupElement, type MarkupNode } from './markup.js';
+/** A note as Orbit keeps it. */
+export interface ImportedNote {
+    text: string;
+    format: 'markdown' | 'plain';
+}
+/** Inline content, as the note's reader shows it. */
+export type NoteInline = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'break';
+} | {
+    kind: 'strong' | 'emphasis' | 'strike';
+    children: NoteInline[];
+} | {
+    kind: 'code';
+    text: string;
+} | {
+    kind: 'link';
+    href: string;
+    children: NoteInline[];
+} | {
+    kind: 'image';
+    src: string;
+    alt: string;
+};
+/** A block of a note. */
+export type NoteBlock = {
+    kind: 'paragraph';
+    inline: NoteInline[];
+} | {
+    kind: 'heading';
+    level: number;
+    inline: NoteInline[];
+} | {
+    kind: 'list';
+    ordered: boolean;
+    items: NoteBlock[][];
+} | {
+    kind: 'quote';
+    blocks: NoteBlock[];
+} | {
+    kind: 'code';
+    text: string;
+};
+/** How addresses in a note are kept. */
+export interface NoteAddresses {
+    /** The address a link keeps, or null for its text alone. Default: web and mail addresses, and `#` links. */
+    link?: (href: string) => string | null;
+    /** The address a picture keeps, or null for its description alone. Default: web addresses. */
+    picture?: (src: string) => string | null;
+}
+/** Web and mail addresses, and links within the map. */
+export declare const isKeptLink: (href: string) => boolean;
+/** An address as a link keeps it: `www.example.com` is a web address; a file or anything else is null. */
+export declare const keptAddress: (href: string) => string | null;
+/** An HTML note (an element, or HTML as text) as an Orbit note; undefined when it holds no text. */
+export declare const noteFromHtml: (html: MarkupElement | string, addresses?: NoteAddresses) => ImportedNote | undefined;
+/** A plain text note: markdown when it reads the same as markdown, otherwise plain, as written. */
+export declare const noteFromPlainText: (text: string | undefined) => ImportedNote | undefined;
+/** Blocks as a note: markdown when every word reads back as written, otherwise plain text. */
+export declare const noteFromBlocks: (blocks: NoteBlock[], addresses?: NoteAddresses) => ImportedNote | undefined;
+/** Two or more notes as one: markdown if all are, otherwise plain text, separated by blank lines. */
+export declare const joinNotes: (notes: (ImportedNote | undefined)[]) => ImportedNote | undefined;
+/** A title from HTML: what a reader sees, on one line, and the address of its first link. */
+export declare const titleFromHtml: (html: MarkupElement | string) => {
+    text: string;
+    link?: string;
+};
+/** The note's blocks, from HTML nodes. */
+export declare const readBlocks: (nodes: MarkupNode[], addresses: NoteAddresses) => NoteBlock[];

package/dist/core/other-apps/opml.d.ts

@@ -0,0 +1,26 @@
+/**
+ * OPML, the outline format outliners and most mind map apps read and write.
+ * Reading keeps each outline's text, its note (`_note`, the convention
+ * OmniOutliner started and Workflowy, Dynalist and MindNode follow), its
+ * done or todo state (`_status`, `_complete`, `complete`), its link
+ * (`type="link"`'s `url`, a feed's `htmlUrl` or `xmlUrl`) and its categories
+ * as tags. Writing gives the same back, so a map Orbit writes reads back the
+ * same, and other apps read its text, notes, links and checkboxes.
+ */
+import type { OrbitDocument } from '../types.js';
+import { type OrbitImport, type OrbitImportOptions } from './reading.js';
+/** An OPML file, from its bytes or text. */
+export declare const importOPML: (data: Uint8Array | string, options?: OrbitImportOptions) => OrbitImport;
+export interface OrbitOPMLOptions {
+    /** The outline's title, in its head. Default: the map's `title`, or its root's text. */
+    title?: string;
+}
+/**
+ * A map as OPML: the root is the one top outline, each node an outline
+ * with its icon and text, its note in `_note`, its link as `type="link"`
+ * with a `url`, its status in `_status` (`checked`, `unchecked` and
+ * `indeterminate` for done, todo and active; any other word as it is) and
+ * `_complete`, and its tags as `category`. Pictures, videos, colors and
+ * priorities have no place in OPML: a zip or the map's own file keeps them.
+ */
+export declare const exportOPML: (input: string | OrbitDocument, options?: OrbitOPMLOptions) => string;

package/dist/core/other-apps/reading.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What reading another app's map gives back, and the first steps every
+ * reader shares: a file's bytes as text, and its XML read, with problems
+ * reported as `OrbitImportError`s.
+ */
+import type { OrbitDocument } from '../types.js';
+import { type OrbitImportWarning } from './ideas.js';
+import { type MarkupElement } from './markup.js';
+/** The other apps' formats Orbit reads. */
+export type OrbitImportFormat = 'opml' | 'freemind' | 'xmind';
+export interface OrbitImportOptions {
+    /** The file's name: its extension tells the format, and a map with no single center is named after it. */
+    name?: string;
+    /** The file's format, when you know it. Default: from the name, then from what the file holds. */
+    format?: OrbitImportFormat;
+    /** The name of the center Orbit adds to a map with several top ideas and nothing to name it after. Default "Untitled map". */
+    untitled?: string;
+}
+/** One map read from another app's file. */
+export interface OrbitImportedMap {
+    document: OrbitDocument;
+    /** Pictures from inside the file, by the address the map gives them: `media/sunrise.png`. Save them next to the map. */
+    media: Record<string, Uint8Array>;
+    /** What the other app had that Orbit keeps another way, or couldn't keep. */
+    warnings: OrbitImportWarning[];
+}
+/** What reading another app's file gives. */
+export interface OrbitImport {
+    format: OrbitImportFormat;
+    /** The file's maps: one, or one for each sheet of an XMind workbook. */
+    maps: OrbitImportedMap[];
+}
+/** An XML file's top element, which must be `rootName`; `what` names the file in errors ("an OPML file"). */
+export declare const readXmlFile: (data: Uint8Array | string, rootName: string, what: string) => MarkupElement;
+/** A file's name without its folder or a map's extension: `notes/Trip.opml` is `Trip`. */
+export declare const baseName: (name: string | undefined) => string;

package/dist/core/other-apps/xmind.d.ts

@@ -0,0 +1,14 @@
+/**
+ * XMind workbooks (`.xmind`): zip archives holding `content.json` (XMind
+ * 2020 and later, and XMind Zen) or `content.xml` (XMind 8 and earlier),
+ * with their pictures. Each sheet becomes a map: its topics with their notes,
+ * labels, markers, links, folds, fill colors and pictures, floating topics,
+ * summaries and callouts under the topics they belong with, and
+ * relationships as links.
+ */
+import type { OrbitImport, OrbitImportOptions } from './reading.js';
+/**
+ * An XMind workbook, from its bytes; or its `content.json` or `content.xml`
+ * as text, which reads without pictures.
+ */
+export declare const importXMind: (data: Uint8Array | string, options?: OrbitImportOptions) => OrbitImport;