@restless-dreams/orbit 0.0.0-stage → 0.2.0

package/dist/core/markdown-writing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * How Orbit writes a map as markdown: its own form, the way people write
+ * maps. `serializeOrbitMarkdown` writes a whole map this way, and saving an
+ * edited map writes its changed ideas this way (see source-patch.ts).
+ */
+import type { OrbitDocument, OrbitNode } from './types.js';
+/** A whole map in Orbit's own form. */
+export declare const writeMarkdown: (doc: OrbitDocument) => string;
+export declare const collectFrontmatter: (doc: Pick<OrbitDocument, "options" | "extra">) => Record<string, unknown>;
+/**
+ * The root and its children are headings; everything under them is a
+ * list, the way people write maps. Below two levels, headings would only
+ * make a map harder to read.
+ */
+export declare const HEADING_LEVELS = 2;
+/** The statuses a list item writes as a checkbox. */
+export declare const CHECKBOXES: Record<string, string>;
+/** What writing a node needs besides the node: which ids to write. */
+export interface Writing {
+    /** The nodes whose ids the parsers wouldn't make from their text, so they are written. */
+    explicitIds: ReadonlySet<OrbitNode>;
+}
+export declare const emitHeading: (node: OrbitNode, level: number, writing: Writing) => string;
+export declare const emitList: (children: OrbitNode[], indent: string, writing: Writing) => string;
+/**
+ * A node as written: its line after the heading's `#`s or the item's
+ * marker (title, then the attributes that fit on it), and what follows the
+ * line, indented by `indent`.
+ */
+export declare const nodeParts: (node: OrbitNode, listItem: boolean, writing: Writing, indent: string) => {
+    line: string;
+    title: string;
+    inline: string;
+    body: string;
+};
+/** The pieces of a node as written, each ending with a line break (or empty): see `nodeParts`. */
+export interface NodePieces {
+    title: string;
+    /** The attributes on the title line, with the space before them; empty when they don't fit there. */
+    inline: string;
+    /** The attributes that didn't fit on the line, as a block of their own. */
+    attributes: string;
+    media: string;
+    note: string;
+}
+export declare const nodePieces: (node: OrbitNode, listItem: boolean, writing: Writing, indent: string) => NodePieces;
+export declare const titleLine: (node: OrbitNode, listItem: boolean, writing: Writing) => {
+    title: string;
+    attributes: Record<string, unknown>;
+};
+/**
+ * Attributes on the node's own line, `<!-- orbit status: done, priority: 2 -->`,
+ * when they are short, plain values: up to three of them, or more while the
+ * comment stays short, as a goal's numbers are (`type: goal, target: 5,
+ * current: 2, unit: apples`). Keys that wouldn't survive the comma-separated
+ * form (with a quote, a comma, a colon or a space of their own) go to the
+ * block form instead.
+ */
+export declare const inlineAttributes: (attributes: Record<string, unknown>) => string;
+export declare const inlineValue: (value: unknown) => string | null;
+/** What follows a node's line, indented under a list item: attributes that didn't fit on the line, media, then the note. */
+export declare const body: (node: OrbitNode, blockAttributes: Record<string, unknown>, indent: string) => string;
+/** Attributes as a `<!-- orbit … -->` block of their own, indented by `indent`; nothing when there are none. */
+export declare const attributeBlock: (attributes: Record<string, unknown>, indent: string) => string;
+/** A node's note as written under it, indented by `indent`. */
+export declare const noteLines: (node: OrbitNode, indent: string) => string;
+/**
+ * A note as paragraphs when they read back as the same note, otherwise
+ * quoted: quoted lines never turn into nodes, so a note can hold lines that
+ * look like headings, lists or media.
+ */
+export declare const noteText: (note: string, listItem: boolean) => string;
+export declare const indentLines: (text: string, indent: string) => string;
+/**
+ * A node's text as a heading or list item title: as is when it reads back
+ * unchanged, otherwise with its markup characters escaped.
+ */
+export declare const escapeTitle: (text: string) => string;
+export declare const renderMedia: (node: OrbitNode) => string;
+/**
+ * YAML to write inside an HTML comment. A "-->" in a value would end the
+ * comment early, so its ">" is written as an escape; strings holding one are
+ * always double-quoted, where the escape reads back as ">".
+ */
+export declare const commentYaml: (value: Record<string, unknown>) => string;
+/** Attributes carried in `<!-- orbit ... -->` comments: the ones a node's title and lines don't show. */
+export declare const collectAttrs: (node: OrbitNode, explicitIds: ReadonlySet<OrbitNode>) => Record<string, unknown>;

package/dist/core/material.d.ts

@@ -0,0 +1,25 @@
+import type { OrbitRendererTheme } from './types.js';
+/**
+ * Material 3 themes from one color, the way Material You colors an app from
+ * its wallpaper: tonal palettes in the color's hue, surfaces and containers
+ * picked by tone, and branches in hues spread evenly around the color wheel
+ * from it. Picking colors by tone is what keeps text readable: two tones 50
+ * apart always have at least 4.5:1 contrast.
+ */
+/** Material's baseline color: the `material` and `material-night` themes are built from it. */
+export declare const MATERIAL_SEED = "#6750A4";
+export interface MaterialThemeOptions {
+    /** Dark surfaces with light text, like `material-night`, instead of light ones. */
+    dark?: boolean;
+}
+/** The tokens a Material theme takes from its color: everything else comes from `material` or `material-night`. */
+export declare const MATERIAL_COLOR_TOKENS: readonly ["surface", "text", "muted-text", "root-text", "node-text", "node-text-inverse", "color-root", "color-1", "color-2", "color-3", "color-4", "color-5", "color-6", "color-7", "shade-light", "shade-dark", "node-stroke", "badge-stroke", "sun-halo", "ring-stroke", "link-stroke", "focus-ring", "note-indicator", "control-background", "control-text", "control-muted-text", "control-active-background", "control-active-text", "tooltip-background", "tooltip-text", "action-background", "action-text", "sheet-background", "sheet-text", "sheet-muted-text", "sheet-border", "chip-background", "chip-text", "link-text", "status-active", "status-done", "status-blocked", "status-todo", "status-neutral", "error-background", "error-border", "error-text"];
+export type MaterialColorToken = (typeof MATERIAL_COLOR_TOKENS)[number];
+/**
+ * A Material 3 theme built from `seed`, any CSS color Orbit reads (hex,
+ * `rgb()`, `oklch()`…). Use it as the `theme` option, or name it for every
+ * map: `registerTheme('brand', materialTheme('#0B57D0'))`.
+ */
+export declare const materialTheme: (seed: string, options?: MaterialThemeOptions) => OrbitRendererTheme;
+/** Every color token of a Material theme built from `seed`. */
+export declare const materialColors: (seed: string, dark: boolean) => Record<MaterialColorToken, string>;

package/dist/core/media.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Video provider helpers shared by the parser (provider detection), the
+ * renderer (thumbnail derivation), and the detail sheet and media viewer
+ * (embed URL conversion, and links to a video's page on its site).
+ *
+ * YouTube and Vimeo forbid framing their watch pages (X-Frame-Options /
+ * frame-ancestors); only the dedicated embed endpoints may be iframed, so
+ * anything that puts a video URL into an <iframe> must go through
+ * `toVideoEmbedUrl` first.
+ */
+export type VideoProvider = 'youtube' | 'vimeo' | 'native';
+/** Which player a video URL needs, by the site it is on; null when it isn't a video. */
+export declare const detectVideoProvider: (url: string) => VideoProvider | null;
+export declare const isNativeVideoUrl: (url: string) => boolean;
+/** The video id in any of YouTube's URL shapes: watch pages, youtu.be, embeds, Shorts and lives. */
+export declare const youtubeVideoId: (url: string) => string | null;
+/**
+ * A Vimeo video's id, and the hash an unlisted video needs, from its page
+ * (`vimeo.com/123`, `/123/abc`, channels, groups, showcases) or its player.
+ */
+export declare const vimeoVideo: (url: string) => {
+    id: string;
+    hash?: string;
+} | null;
+/** The numeric id of a Vimeo video. */
+export declare const vimeoVideoId: (url: string) => string | null;
+/**
+ * Convert a video URL to a frameable embed URL. Returns null when no
+ * conversion is known (callers fall back to the original URL).
+ */
+export declare const toVideoEmbedUrl: (url: string, provider?: string) => string | null;
+/** Whether a YouTube URL is a Short, a video that plays upright. */
+export declare const isYouTubeShort: (url: string) => boolean;
+/** Where a video is watched on its site: its YouTube or Vimeo page, or the URL itself. */
+export declare const videoPageUrl: (url: string, provider?: string) => string;
+export declare const youtubeThumbnailUrl: (url: string) => string | null;
+/** True when an image, video or embed value has a usable `src`. */
+export declare const hasMediaSource: (media: {
+    src?: unknown;
+} | undefined | null) => media is {
+    src: string;
+};

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

@@ -0,0 +1,31 @@
+import type { DiagnosticCollector } from './diagnostics.js';
+import type { OrbitNode } from './types.js';
+type ImageMedia = NonNullable<OrbitNode['image']>;
+type VideoMedia = NonNullable<OrbitNode['video']>;
+type EmbedMedia = NonNullable<OrbitNode['embed']>;
+/**
+ * The fields a picture, video or embed was written with that Orbit doesn't
+ * read (a `width`, a provider it doesn't know): kept so saving writes them
+ * back, for a newer version or another app that reads them.
+ */
+export declare const mediaExtras: (media: object | undefined) => Record<string, unknown> | undefined;
+/** A copy of a picture, video or embed, with the fields Orbit doesn't read. */
+export declare const copyMedia: <Media extends object>(media: Media) => Media;
+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", "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[];
+    synonyms?: Readonly<Record<string, string>>;
+}
+/**
+ * Applies one typed attribute (from a `<!-- orbit ... -->` block or a YAML
+ * node map) to a node. Unknown keys are kept in `node.attrs`, with a note
+ * when they look like a misspelled attribute. Values Orbit can't read are
+ * reported and kept in `node.attrs` too, so they're written back.
+ */
+export declare const assignNodeAttribute: (node: OrbitNode, key: string, value: unknown, diagnostics: DiagnosticCollector, line?: number, vocabulary?: AttributeVocabulary) => void;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Links between nodes. A node's link, or a link in its note, written as
+ * `#id` points at another node of the same map, the way `#heading` links
+ * point at a heading in a markdown page.
+ */
+import type { OrbitNode } from './types.js';
+import type { DiagnosticCollector } from './diagnostics.js';
+/** Whether a link points at a node of the same map: `#research`. */
+export declare const isNodeLink: (href: string | undefined) => href is string;
+/**
+ * The node a `#id` link points at: the node with that id, or the one whose
+ * id the fragment's text would get, so `#Research` and GitHub-style
+ * `#-research` anchors find `research` too.
+ */
+export declare const findLinkedNode: (root: OrbitNode, href: string) => OrbitNode | null;
+/** `findLinkedNode` with the map's nodes indexed by `indexNodes`, for checking many links at once. */
+export declare const findIndexedLinkedNode: (nodes: Map<string, OrbitNode>, href: string) => OrbitNode | null;
+/** The map's nodes by id; when ids repeat, the first in the tree, as `findNodeById` finds it. */
+export declare const indexNodes: (root: OrbitNode) => Map<string, OrbitNode>;
+/** The `#id` links a node has: its link, then the ones in its note. */
+export declare const nodeLinksOf: (node: OrbitNode) => string[];
+/** Where a parser saw a node's link (`inNote` false) or a link in its note: the line it's on, when it knows. */
+export type LinkLine = (node: OrbitNode, href: string, inNote: boolean) => number | undefined;
+/** Reports each `#id` link, in a node's link or note, that points at no node of the map, on its own line where `lineOf` knows it. */
+export declare const checkNodeLinks: (root: OrbitNode, diagnostics: DiagnosticCollector, lineOf?: LinkLine) => void;

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;

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

@@ -0,0 +1,37 @@
+/**
+ * Reads files out of a zip archive, such as an XMind map: its directory,
+ * then each entry on request, stored or deflated, checked against its
+ * CRC-32. Archives that span disks, need ZIP64 or are encrypted are refused,
+ * and so is an entry that would unpack past the archive's limits.
+ */
+/** An archive that can't be read, or an entry that can't be unpacked. */
+export declare class ZipError extends Error {
+    constructor(message: string);
+}
+export interface ZipLimits {
+    /** The most entries an archive may list. */
+    entries: number;
+    /** The most bytes one entry may unpack to. */
+    entrySize: number;
+    /** The most bytes all the entries read may unpack to, together. */
+    totalSize: number;
+}
+export declare const DEFAULT_ZIP_LIMITS: ZipLimits;
+/** Whether bytes start the way every zip archive does. */
+export declare const isZip: (bytes: Uint8Array) => boolean;
+export declare class ZipArchive {
+    private readonly bytes;
+    private readonly view;
+    private readonly limits;
+    private readonly entries;
+    private unpacked;
+    constructor(bytes: Uint8Array, limits?: Partial<ZipLimits>);
+    /** The names of the files in the archive, folders left out. */
+    get names(): string[];
+    has(name: string): boolean;
+    /** An entry's bytes, or null when the archive has no such file. */
+    read(name: string): Uint8Array | null;
+    /** An entry as UTF-8 text, or null when the archive has no such file. */
+    text(name: string): string | null;
+    private readDirectory;
+}