@tarhnama/core 0.1.0

package/dist/features.js

@@ -0,0 +1,128 @@
+/**
+ * What a host turns on.
+ *
+ * This editor is embedded in projects that want very different subsets of it: a note pane
+ * that needs no cross-document links, a review surface that needs no formatting, a viewer
+ * that needs no editing at all. Every one of those is a supported configuration rather
+ * than a fork.
+ *
+ * ── The rule that shapes this whole file ───────────────────────────────────────
+ *
+ * **Features gate BEHAVIOUR, never the schema.**
+ *
+ * It is tempting to make `links: false` remove the link mark from the document schema —
+ * it would be smaller, and it would tree-shake. It is also data loss: ProseMirror strips
+ * any mark its schema does not know, so a host with links disabled that opens a document
+ * containing links **destroys them on load**, silently, and writes the damaged version
+ * back on the next save. A document must round-trip through every configuration
+ * unchanged.
+ *
+ * So the schema is always complete, and a disabled feature removes its input rules, its
+ * keymap entries, its commands, its decorations and its UI. Bundle size is addressed the
+ * honest way instead — subpath exports, so a host that never imports the link picker
+ * never ships it.
+ */
+/**
+ * The default: everything.
+ *
+ * A host that has not thought about features yet should get the whole editor, not an empty
+ * shell to debug. "Off unless named" reads as safer and is worse — the failure it produces
+ * is a missing feature with no error, which is the hardest kind to diagnose.
+ */
+export const ALL_FEATURES = {
+    links: true,
+    formatting: true,
+    collapse: true,
+    lock: true,
+    history: true,
+    tables: true,
+    images: true,
+    clipboard: true,
+};
+/** Nothing but text. Useful as a base to switch individual features back on. */
+export const NO_FEATURES = {
+    links: false,
+    formatting: false,
+    collapse: false,
+    lock: false,
+    history: false,
+    tables: false,
+    images: false,
+    clipboard: false,
+};
+const NAMES = Object.keys(ALL_FEATURES);
+/**
+ * Normalize whatever the host passed into a complete record.
+ *
+ * Three input shapes, because hosts reach for different ones and all three are reasonable:
+ *
+ *   undefined                     → everything (the default)
+ *   { links: false }              → everything except links (a partial override)
+ *   ['collapse', 'formatting']    → ONLY those two (an allowlist)
+ *
+ * The array form flips the default deliberately: writing a list reads as "these are the
+ * features I want", and having it mean "these, plus the six I did not mention" would be a
+ * trap. The object form keeps the opposite reading, which is why both exist.
+ *
+ * An unknown name in the array throws rather than being ignored — a typo'd feature that
+ * silently does nothing is the exact failure this API exists to prevent.
+ */
+export function resolveFeatures(input) {
+    if (input === undefined)
+        return ALL_FEATURES;
+    if (Array.isArray(input)) {
+        const wanted = new Set(input);
+        for (const name of wanted) {
+            if (!NAMES.includes(name)) {
+                throw new Error(`Unknown outline feature ${JSON.stringify(name)}. Known: ${NAMES.join(', ')}.`);
+            }
+        }
+        const out = { ...NO_FEATURES };
+        for (const name of wanted)
+            out[name] = true;
+        return out;
+    }
+    return { ...ALL_FEATURES, ...input };
+}
+/**
+ * The features a mode can actually support.
+ *
+ * Read mode keeps `collapse` and `links`, and that distinction is the point: **a lock stops
+ * editing, never reading.** A reader who cannot fold a section or follow a reference has
+ * been given a screenshot, not a document. Everything that mutates content is off, and no
+ * host flag can turn it back on — an editing command reachable in read mode is a bug, not
+ * a configuration.
+ */
+export function featuresForMode(features, mode) {
+    if (mode === 'edit')
+        return features;
+    return {
+        ...features,
+        formatting: false,
+        history: false,
+        tables: false,
+        images: false,
+        lock: false,
+    };
+}
+/**
+ * A stable string for a resolved feature set.
+ *
+ * Exists because of how React memoization actually gets used. The natural way for a host to
+ * configure this editor is an inline literal:
+ *
+ *     <OutlineEditor features={{ links: hasLinks }} />
+ *
+ * That object has a new identity on every render. Memoizing the extension list on it
+ * rebuilds the Tiptap editor on every render — the document is torn down and recreated
+ * between keystrokes, and the symptom is not an error but an editor that never settles:
+ * the spine's handles move continuously and a click can never land.
+ *
+ * An API that is only correct when the caller remembers to `useMemo` is a bad API, so the
+ * comparison is by CONTENT here rather than by reference. The key is ordered by
+ * `ALL_FEATURES` so two equal sets always produce the same string.
+ */
+export function featureKey(features) {
+    return NAMES.filter((name) => features[name]).join(',');
+}
+//# sourceMappingURL=features.js.map

package/dist/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.js","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8BH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoB;IAC3C,KAAK,EAAE,IAAI;IACX,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,IAAI;IACd,IAAI,EAAE,IAAI;IACV,OAAO,EAAE,IAAI;IACb,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,IAAI;IACZ,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAoB;IAC1C,KAAK,EAAE,KAAK;IACZ,UAAU,EAAE,KAAK;IACjB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,KAAK;IACd,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,KAAK;CACjB,CAAC;AAEF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAkC,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,KAA4E;IAE5E,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAE7C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAsC,CAAC,CAAC;QAC/D,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC/E,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,GAAG,GAAG,EAAE,GAAG,WAAW,EAAyC,CAAC;QACtE,KAAK,MAAM,IAAI,IAAI,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC5C,OAAO,GAAsB,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,GAAG,YAAY,EAAE,GAAI,KAAkC,EAAE,CAAC;AACrE,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,QAAyB,EAAE,IAAiB;IAC1E,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,QAAQ,CAAC;IACrC,OAAO;QACL,GAAG,QAAQ;QACX,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,KAAK;QACb,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,KAAK;KACZ,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,UAAU,CAAC,QAAyB;IAClD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from './types.js';
+export * from './tree.js';
+export * from './ops.js';
+export { clearDirectFormat, effectiveFormat, effectiveRunStyle, redefineStyle, styleChain, styleOutlineLevel, styleUsage, } from './styles.js';
+export type { StyleUsage } from './styles.js';
+export { collapseSiblings, currentOpenLevel, deepestParentLevel, isHidden, isolateSubtree, openToFit, openToLevel, subtreeSize, } from './spine.js';
+export { ALL_FEATURES, NO_FEATURES, featureKey, featuresForMode, resolveFeatures, } from './features.js';
+export type { OutlineFeatureName, OutlineFeatures, OutlineMode } from './features.js';
+export { DEFAULT_SHORTCUTS, formatShortcut, resolveShortcuts, shortcutsFor, } from './shortcuts.js';
+export type { ShortcutBinding, ShortcutCommand, ShortcutGroup, ShortcutOptions, ShortcutPlatform, } from './shortcuts.js';
+export { skippedLevelAt } from './ops.js';
+export { contextMenuFor } from './context-menu.js';
+export type { ContextCommand, ContextMenuItem, ContextTarget } from './context-menu.js';
+export { blocksToNested, nestedToBlocks } from './nested.js';
+export type { NestedNode, NestedOptions, NestedToBlocksResult } from './nested.js';
+export { codeSegments, tokenizeCode } from './code-tokens.js';
+export type { CodeSegment, CodeToken, CodeTokenKind, CodeTokenizer } from './code-tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AAEzB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,SAAS,EACT,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEtF,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,eAAe,EACf,eAAe,EACf,aAAa,EACb,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAExF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './tree.js';
+export * from './ops.js';
+export { clearDirectFormat, effectiveFormat, effectiveRunStyle, redefineStyle, styleChain, styleOutlineLevel, styleUsage, } from './styles.js';
+export { collapseSiblings, currentOpenLevel, deepestParentLevel, isHidden, isolateSubtree, openToFit, openToLevel, subtreeSize, } from './spine.js';
+export { ALL_FEATURES, NO_FEATURES, featureKey, featuresForMode, resolveFeatures, } from './features.js';
+export { DEFAULT_SHORTCUTS, formatShortcut, resolveShortcuts, shortcutsFor, } from './shortcuts.js';
+export { skippedLevelAt } from './ops.js';
+export { contextMenuFor } from './context-menu.js';
+export { blocksToNested, nestedToBlocks } from './nested.js';
+export { codeSegments, tokenizeCode } from './code-tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AAEzB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,cAAc,EACd,SAAS,EACT,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AASxB,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/nested.d.ts

@@ -0,0 +1,66 @@
+import { type Blocks } from './types.js';
+/**
+ * Nested tree <-> flat blocks.
+ *
+ * Almost every system that stores a tree stores it as ADJACENCY: one row per node with a
+ * `parentId` and an ordinal. This editor's model is deliberately the opposite — a flat list
+ * where each block carries an explicit level, which is what lets it import the Word and
+ * Markdown documents that skip levels constantly (CLAUDE.md §1).
+ *
+ * Binding the two is the entire cost of embedding this editor in a host that already has a
+ * tree, and every host has to do it. Doing it here once, with tests, beats each of them
+ * writing the awkward parts again — the awkward parts being ordering, depth beyond what a
+ * level can express, cycles, orphans, and the fields a tree carries that an outline cannot.
+ */
+/** A host's nested node. The shape is the common denominator, not any one product's schema. */
+export interface NestedNode<T = unknown> {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly title: string;
+    /** Order among siblings. Absent sorts last, stably. */
+    readonly ordinal?: number;
+    /** Prose under the heading. */
+    readonly body?: string;
+    /**
+     * Anything the host keeps that the outline cannot represent — evidence, a source, a
+     * foreign key. Carried through untouched so a round trip never costs the host a field.
+     */
+    readonly data?: T;
+}
+export interface NestedToBlocksResult<C> {
+    readonly blocks: Blocks<C>;
+    /**
+     * What could not be represented faithfully.
+     *
+     * Returned rather than thrown, and never silent: a 12-deep branch that quietly flattens
+     * to 9 loses three levels of someone's tree with nothing reporting a problem, and they
+     * find out when they save.
+     */
+    readonly warnings: readonly string[];
+}
+/** How a title and a body become block content. Defaults to a single plain run. */
+export interface NestedOptions<C> {
+    readonly toContent?: (text: string) => C;
+    readonly fromContent?: (content: C | undefined) => string;
+}
+/**
+ * Flatten a nested tree into blocks.
+ *
+ * Depth becomes level. Where depth exceeds `MAX_LEVEL` the level CLAMPS — a block with
+ * level 12 is not representable and would be rejected downstream — but the real depth and
+ * the real parent ride along in `attrs`, so `blocksToNested` restores the exact tree. The
+ * clamp is a display limit, never a data loss, and it is reported either way.
+ */
+export declare function nestedToBlocks<C = unknown, T = unknown>(nodes: readonly NestedNode<T>[], options?: NestedOptions<C>): NestedToBlocksResult<C>;
+/**
+ * Rebuild the nested tree from blocks.
+ *
+ * The inverse of `nestedToBlocks`, and the direction that has to be right on save: a host
+ * writes what this returns back into their database, so anything it gets wrong is data loss
+ * rather than a rendering bug.
+ *
+ * Ordinals are RENUMBERED from document order. That is the point of editing an outline —
+ * the user reordered it — and preserving the incoming ordinals would throw their edit away.
+ */
+export declare function blocksToNested<C = unknown, T = unknown>(blocks: Blocks<C>, options?: NestedOptions<C>): readonly NestedNode<T>[];
+//# sourceMappingURL=nested.d.ts.map

package/dist/nested.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested.d.ts","sourceRoot":"","sources":["../src/nested.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,MAAM,EAAqB,MAAM,YAAY,CAAC;AAE7E;;;;;;;;;;;;GAYG;AAEH,+FAA+F;AAC/F,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,MAAM,CAAC;CAC3D;AAgBD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACrD,KAAK,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAC/B,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,oBAAoB,CAAC,CAAC,CAAC,CA8GzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACrD,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GACzB,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAqD1B"}

package/dist/nested.js

@@ -0,0 +1,194 @@
+import { buildIndex, subtreeRange } from './tree.js';
+import { BODY, MAX_LEVEL } from './types.js';
+const defaultToContent = (text) => [{ text }];
+const defaultFromContent = (content) => {
+    if (!Array.isArray(content))
+        return '';
+    return content.map((run) => run.text ?? '').join('');
+};
+/** Where the true depth is stashed when a level cannot hold it. See `nestedToBlocks`. */
+const DEPTH_ATTR = 'nestedDepth';
+/** Where the host's own payload rides. */
+const DATA_ATTR = 'data';
+/** The parent, recorded so the reverse mapping never has to guess at a clamped level. */
+const PARENT_ATTR = 'nestedParentId';
+/**
+ * Flatten a nested tree into blocks.
+ *
+ * Depth becomes level. Where depth exceeds `MAX_LEVEL` the level CLAMPS — a block with
+ * level 12 is not representable and would be rejected downstream — but the real depth and
+ * the real parent ride along in `attrs`, so `blocksToNested` restores the exact tree. The
+ * clamp is a display limit, never a data loss, and it is reported either way.
+ */
+export function nestedToBlocks(nodes, options) {
+    const toContent = (options?.toContent ?? defaultToContent);
+    const warnings = [];
+    const byId = new Map();
+    for (const node of nodes)
+        byId.set(node.id, node);
+    // Children by parent, in sibling order. Built once: doing it per node is the quadratic
+    // version of this function and a knowledge tree can be large.
+    const children = new Map();
+    for (const node of nodes) {
+        /*
+         * A parent that is not in the set makes this node a ROOT rather than dropping it.
+         * Dropping deletes the user's content on the way in; promoting keeps it where they can
+         * see it and fix it.
+         */
+        const missing = node.parentId !== null && !byId.has(node.parentId);
+        if (missing) {
+            warnings.push(`Node ${JSON.stringify(node.id)} has parent ${JSON.stringify(node.parentId)}, which is not in the tree — treated as a root.`);
+        }
+        const key = missing ? null : node.parentId;
+        const bucket = children.get(key);
+        if (bucket)
+            bucket.push(node);
+        else
+            children.set(key, [node]);
+    }
+    for (const bucket of children.values()) {
+        bucket.sort((a, b) => {
+            // Absent ordinals sort last and keep their relative order, so a host that never set
+            // them gets its array order back rather than an arbitrary shuffle.
+            const left = a.ordinal ?? Number.MAX_SAFE_INTEGER;
+            const right = b.ordinal ?? Number.MAX_SAFE_INTEGER;
+            return left - right;
+        });
+    }
+    const blocks = [];
+    const seen = new Set();
+    /* Iterative, not recursive: a knowledge tree deep enough to blow the stack is a crash
+       with no message, and this runs on data the library did not create. */
+    const stack = [];
+    for (const root of [...(children.get(null) ?? [])].reverse()) {
+        stack.push({ node: root, depth: 1 });
+    }
+    while (stack.length > 0) {
+        const { node, depth } = stack.pop();
+        if (seen.has(node.id))
+            continue;
+        seen.add(node.id);
+        const level = Math.min(depth, MAX_LEVEL);
+        if (depth > MAX_LEVEL) {
+            warnings.push(`Node ${JSON.stringify(node.id)} is ${depth} deep; levels stop at ${MAX_LEVEL}, so it renders at ${MAX_LEVEL}. Its real depth is preserved.`);
+        }
+        const attrs = {};
+        if (node.data !== undefined)
+            attrs[DATA_ATTR] = node.data;
+        // Only recorded when the level cannot express the truth on its own.
+        if (depth > MAX_LEVEL) {
+            attrs[DEPTH_ATTR] = depth;
+            attrs[PARENT_ATTR] = node.parentId;
+        }
+        blocks.push({
+            id: node.id,
+            level,
+            type: 'heading',
+            dir: 'auto',
+            collapsed: false,
+            content: toContent(node.title),
+            ...(Object.keys(attrs).length > 0 ? { attrs } : {}),
+        });
+        if (node.body !== undefined && node.body !== '') {
+            blocks.push({
+                // Body text is not a node of its own, so it gets no node id to collide with.
+                id: '',
+                level: BODY,
+                type: 'paragraph',
+                dir: 'auto',
+                collapsed: false,
+                content: toContent(node.body),
+            });
+        }
+        for (const child of [...(children.get(node.id) ?? [])].reverse()) {
+            stack.push({ node: child, depth: depth + 1 });
+        }
+    }
+    /*
+     * Anything never reached is in a cycle, or hangs off one. Reported rather than emitted:
+     * a cycle has no depth, so there is no level to give it, and inventing one would put the
+     * nodes somewhere arbitrary in the user's document.
+     */
+    const unreachable = nodes.filter((node) => !seen.has(node.id));
+    if (unreachable.length > 0) {
+        warnings.push(`${unreachable.length} node(s) are unreachable from any root — a parent cycle: ${unreachable
+            .map((n) => JSON.stringify(n.id))
+            .join(', ')}.`);
+    }
+    return { blocks: blocks, warnings };
+}
+/**
+ * Rebuild the nested tree from blocks.
+ *
+ * The inverse of `nestedToBlocks`, and the direction that has to be right on save: a host
+ * writes what this returns back into their database, so anything it gets wrong is data loss
+ * rather than a rendering bug.
+ *
+ * Ordinals are RENUMBERED from document order. That is the point of editing an outline —
+ * the user reordered it — and preserving the incoming ordinals would throw their edit away.
+ */
+export function blocksToNested(blocks, options) {
+    const fromContent = (options?.fromContent ?? defaultFromContent);
+    const index = buildIndex(blocks);
+    const out = [];
+    const ordinals = new Map();
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        if (!block || block.level === BODY)
+            continue;
+        /*
+         * The parent is the nearest ancestor HEADING. Taken from the tree index rather than
+         * recomputed, so this agrees with collapse, indent and every other consumer of the
+         * hierarchy — a second implementation of "who is my parent" is a second answer.
+         */
+        const attrs = block.attrs;
+        const clampedParent = attrs?.[PARENT_ATTR];
+        let parentId;
+        if (typeof clampedParent === 'string' || clampedParent === null) {
+            // Beyond MAX_LEVEL the level cannot express the parent, so the recorded one wins.
+            parentId = clampedParent;
+        }
+        else {
+            const parent = parentOf(blocks, index, i);
+            parentId = parent === -1 ? null : (blocks[parent]?.id ?? null);
+        }
+        const ordinal = ordinals.get(parentId) ?? 0;
+        ordinals.set(parentId, ordinal + 1);
+        // Body text belonging to this heading: the level-0 blocks that immediately follow it.
+        const bodyParts = [];
+        for (let j = i + 1; j < blocks.length; j++) {
+            const next = blocks[j];
+            if (!next || next.level !== BODY)
+                break;
+            bodyParts.push(fromContent(next.content));
+        }
+        const data = attrs?.[DATA_ATTR];
+        out.push({
+            id: block.id,
+            parentId,
+            title: fromContent(block.content),
+            ordinal,
+            ...(bodyParts.length > 0 ? { body: bodyParts.join('\n\n') } : {}),
+            ...(data !== undefined ? { data: data } : {}),
+        });
+    }
+    return out;
+}
+/** Nearest preceding block at a shallower level — the parent heading, or -1. */
+function parentOf(blocks, index, i) {
+    const level = blocks[i]?.level;
+    if (level === undefined || level <= 1)
+        return -1;
+    for (let j = i - 1; j >= 0; j--) {
+        const other = blocks[j]?.level;
+        if (other === undefined || other === BODY)
+            continue;
+        if (other < level) {
+            // Confirm containment against the shared index rather than trusting the scan alone.
+            const [, end] = subtreeRange(index, j);
+            return i < end ? j : -1;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=nested.js.map

package/dist/nested.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested.js","sourceRoot":"","sources":["../src/nested.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAkC,MAAM,YAAY,CAAC;AAkD7E,MAAM,gBAAgB,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,OAAgB,EAAU,EAAE;IACtD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAE,GAAyB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9E,CAAC,CAAC;AAEF,yFAAyF;AACzF,MAAM,UAAU,GAAG,aAAa,CAAC;AACjC,0CAA0C;AAC1C,MAAM,SAAS,GAAG,MAAM,CAAC;AACzB,yFAAyF;AACzF,MAAM,WAAW,GAAG,gBAAgB,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,KAA+B,EAC/B,OAA0B;IAE1B,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,SAAS,IAAI,gBAAgB,CAAwB,CAAC;IAClF,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAElD,uFAAuF;IACvF,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB;;;;WAIG;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnE,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,CAAC,IAAI,CACX,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,eAAe,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,iDAAiD,CAC7H,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YACzB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACnB,oFAAoF;YACpF,mEAAmE;YACnE,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,gBAAgB,CAAC;YAClD,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,IAAI,MAAM,CAAC,gBAAgB,CAAC;YACnD,OAAO,IAAI,GAAG,KAAK,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAc,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B;4EACwE;IACxE,MAAM,KAAK,GAA6C,EAAE,CAAC;IAC3D,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,SAAS;QAChC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAElB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAiB,CAAC;QACzD,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CACX,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,KAAK,yBAAyB,SAAS,sBAAsB,SAAS,gCAAgC,CAC7I,CAAC;QACJ,CAAC;QAED,MAAM,KAAK,GAA4B,EAAE,CAAC;QAC1C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QAC1D,oEAAoE;QACpE,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YACtB,KAAK,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;YAC1B,KAAK,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QACrC,CAAC;QAED,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,KAAK;YACL,IAAI,EAAE,SAAS;YACf,GAAG,EAAE,MAAM;YACX,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;YAC9B,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,IAAI,CAAC;gBACV,6EAA6E;gBAC7E,EAAE,EAAE,EAAE;gBACN,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,WAAW;gBACjB,GAAG,EAAE,MAAM;gBACX,SAAS,EAAE,KAAK;gBAChB,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;aAC9B,CAAC,CAAC;QACL,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACjE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/D,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,QAAQ,CAAC,IAAI,CACX,GAAG,WAAW,CAAC,MAAM,4DAA4D,WAAW;aACzF,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;aAChC,IAAI,CAAC,IAAI,CAAC,GAAG,CACjB,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAmB,EAAE,QAAQ,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAiB,EACjB,OAA0B;IAE1B,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,WAAW,IAAI,kBAAkB,CAEpD,CAAC;IAEZ,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACjC,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;IAElD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;YAAE,SAAS;QAE7C;;;;WAIG;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,MAAM,aAAa,GAAG,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,QAAuB,CAAC;QAC5B,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAChE,kFAAkF;YAClF,QAAQ,GAAG,aAAa,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YAC1C,QAAQ,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5C,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;QAEpC,sFAAsF;QACtF,MAAM,SAAS,GAAa,EAAE,CAAC;QAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;gBAAE,MAAM;YACxC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,IAAI,GAAG,KAAK,EAAE,CAAC,SAAS,CAAC,CAAC;QAEhC,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,QAAQ;YACR,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC;YACjC,OAAO;YACP,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnD,CAAC,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gFAAgF;AAChF,SAAS,QAAQ,CAAC,MAAc,EAAE,KAAoC,EAAE,CAAS;IAC/E,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IACjD,KAAK,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;YAClB,oFAAoF;YACpF,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACvC,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC"}

package/dist/ops.d.ts

@@ -0,0 +1,120 @@
+import { type Block, type Blocks, type OutlineLevel } from './types.js';
+/**
+ * Structural operations. All are pure: they take a flat list and return a new one,
+ * sharing unchanged blocks by reference so downstream memoization works.
+ *
+ * The defining rule of this module: an operation on a heading applies to its whole
+ * SUBTREE. Indenting a heading and leaving its children behind — the bug in the
+ * earlier Tiptap scaffold — produces an orphaned document.
+ */
+/**
+ * Can `i` be indented?
+ *
+ * The rule prevents skipped levels: a heading may go one deeper than the nearest
+ * preceding heading, never more. Without this you can indent from level 1 straight
+ * to level 3 and create a block with no representable parent.
+ *
+ * Body text has no level, so indenting it is meaningless — use `setLevel` to promote
+ * body text into a heading instead.
+ */
+export declare function canIndent(blocks: Blocks, i: number): boolean;
+export declare function indent<C>(blocks: Blocks<C>, i: number): Blocks<C>;
+/** Level 1 cannot outdent — there is nothing above it. Body text has no level. */
+export declare function canOutdent(blocks: Blocks, i: number): boolean;
+/**
+ * Outdent a heading and its subtree.
+ *
+ * Pleasant property of the flat model: the following siblings that were at the
+ * outdented block's old level automatically become its children, which is exactly
+ * what Workflowy and Word's outline view do — no extra code needed.
+ */
+export declare function outdent<C>(blocks: Blocks<C>, i: number): Blocks<C>;
+/** Set a block's level directly — used to promote body text to a heading and back. */
+export declare function canSetLevel(blocks: Blocks, i: number): boolean;
+export declare function setLevel<C>(blocks: Blocks<C>, i: number, level: OutlineLevel): Blocks<C>;
+export declare function toggleCollapse<C>(blocks: Blocks<C>, i: number): Blocks<C>;
+/**
+ * Expand every collapsed ancestor of a block, so it can actually be reached.
+ *
+ * Needed wherever the app navigates to a block the user did not click: a search result, a
+ * cross-document link, a backlink. A collapsed subtree is ABSENT from the DOM, not hidden,
+ * so scrolling to it finds nothing and the jump silently does nothing at all — which reads
+ * as a broken feature rather than as "that match is folded away".
+ *
+ * Only ancestors are touched. The block's own collapse state is left alone: revealing a
+ * heading should not also unfold everything beneath it.
+ *
+ * Returns the SAME list when nothing was collapsed.
+ */
+export declare function expandAncestors<C>(blocks: Blocks<C>, blockId: string): Blocks<C>;
+export declare function setDirection<C>(blocks: Blocks<C>, i: number, dir: Block['dir']): Blocks<C>;
+/**
+ * Move the subtree rooted at `from` so it begins at document position `to`.
+ *
+ * `to` is interpreted against the ORIGINAL list. Moving a subtree into itself is a
+ * no-op rather than an error, because drag-and-drop will attempt it constantly.
+ */
+/**
+ * Can the subtree at `from` be moved to `to`?
+ *
+ * Both ends matter: a locked subtree cannot be dragged away, and nothing may be dropped
+ * INTO a locked one. Checking only the source is the easy mistake — it lets a reader
+ * append into a chapter they are not allowed to change.
+ */
+export declare function canMoveSubtree(blocks: Blocks, from: number, to: number): boolean;
+export declare function moveSubtree<C>(blocks: Blocks<C>, from: number, to: number): Blocks<C>;
+/**
+ * Repair skipped levels — the import path for real Word documents, which jump from
+ * H1 to H3 constantly.
+ *
+ * Each heading is clamped to at most one deeper than the preceding heading, and the
+ * first heading is clamped to 1. Body text is untouched.
+ */
+export declare function normalizeLevels<C>(blocks: Blocks<C>): Blocks<C>;
+/** True when no heading is more than one level deeper than the one before it. */
+export declare function isNormalized(blocks: Blocks): boolean;
+/**
+ * Lock or unlock a block. Locking a heading makes its whole subtree read-only by
+ * derivation — only the heading itself carries the flag.
+ */
+export declare function setLocked<C>(blocks: Blocks<C>, i: number, locked: boolean): Blocks<C>;
+/**
+ * Move a node before its previous sibling, subtree and all.
+ *
+ * "Up" is **a sibling**, not a row. A heading with forty blocks under it must jump the
+ * whole of its neighbour's subtree; swapping single rows would tear both apart, and the
+ * design's درخت menu calls this "move node" for that reason.
+ *
+ * A first sibling does not move. The tempting alternative — promote it above its parent —
+ * changes the node's LEVEL as a side effect of a move, and a command that quietly does two
+ * things is one users stop trusting. Indent and outdent are how a level changes.
+ */
+export declare function moveBlockUp<C>(blocks: Blocks<C>, blockId: string): Blocks<C>;
+/**
+ * Move a node after its next sibling, subtree and all.
+ *
+ * The target is the END of the sibling's subtree, in ORIGINAL indices — `moveSubtree`
+ * interprets `to` against the list it was given and does the shift arithmetic itself.
+ * Pre-adjusting by the moved subtree's size (the obvious defensive move) lands the target
+ * back inside the node being moved, where `moveSubtree`'s "dropping inside itself" guard
+ * correctly refuses it and the command silently does nothing.
+ */
+export declare function moveBlockDown<C>(blocks: Blocks<C>, blockId: string): Blocks<C>;
+/**
+ * The level this heading skipped over, or `null`.
+ *
+ * `isNormalized` answers "does this document skip anywhere", which is enough to enable a
+ * repair command and useless for showing the reader WHERE. Frame 1a puts an amber
+ * «سطح ۳ جا افتاده» chip on the offending heading, so the question has to be asked of a
+ * single block.
+ *
+ * Returns the FIRST missing level, not the deepest. When 2 → 4 skips only 3 that is the
+ * same answer either way, but 1 → 4 skips both 2 and 3, and 2 is the one to add first —
+ * naming 3 would send someone to fix the wrong end of the gap.
+ *
+ * Body text is never an answer and never breaks the chain: level 0 is not a hierarchy
+ * level, it belongs to the nearest preceding heading, and a paragraph between two headings
+ * does not make the second one a skip.
+ */
+export declare function skippedLevelAt(blocks: Blocks, i: number): OutlineLevel | null;
+//# sourceMappingURL=ops.d.ts.map

package/dist/ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ops.d.ts","sourceRoot":"","sources":["../src/ops.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,KAAK,EACV,KAAK,MAAM,EACX,KAAK,YAAY,EAGlB,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAmB5D;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAGjE;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAGlE;AAcD,sFAAsF;AACtF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,CAOxF;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAMzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAWhF;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAMX;AAED;;;;;GAKG;AACH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAahF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAUrF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAmB/D;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQpD;AAGD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAQrF;AA6BD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAM5E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAiB9E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAW7E"}