@tarhnama/core 0.1.0

package/dist/spine.d.ts

@@ -0,0 +1,92 @@
+import { type Blocks, type OutlineLevel, type TreeIndex } from './types.js';
+/**
+ * Operations behind the collapse spine.
+ *
+ * Collapse is the most-used interaction in the product and the mechanism the whole
+ * performance strategy rests on (a collapsed subtree is *unmounted*, never hidden), so its
+ * operations live together rather than scattered through `ops.ts`.
+ *
+ * All of them are pure and return the SAME list when nothing changed, like every other
+ * structural operation here — downstream memoization depends on it.
+ */
+/**
+ * How many blocks a heading would fold away.
+ *
+ * This is what the spine's scope line is a picture of, and what the count pill states. It
+ * excludes the heading itself: the question a reader is asking is "how much disappears if
+ * I click this", and the heading does not.
+ */
+export declare function subtreeSize(blocks: Blocks, blockId: string, index?: TreeIndex): number;
+/**
+ * Collapse or expand every sibling at one heading's level, within its parent.
+ *
+ * Bound to ⌥click. "Siblings" means blocks with the same parent AND the same level — not
+ * every block at that level in the document, which would fold unrelated branches the user
+ * cannot see and did not ask about.
+ *
+ * The clicked heading decides the direction for all of them: if it is open, they all
+ * close. Deriving each one independently would produce a checkerboard.
+ */
+export declare function collapseSiblings<C>(blocks: Blocks<C>, blockId: string, collapsed?: boolean): Blocks<C>;
+/**
+ * Open the tree down to `level`, closing everything deeper.
+ *
+ * Bound to ⌘⌥1…6 and to the ladder control. `level` 0 means "close everything" — every
+ * heading that governs a subtree folds; a level above the deepest heading means "open
+ * everything".
+ *
+ * Headings with no children are left alone: a collapsed flag on a leaf is invisible, and
+ * setting it would make the ladder's state depend on blocks the reader cannot see.
+ */
+export declare function openToLevel<C>(blocks: Blocks<C>, level: number): Blocks<C>;
+/**
+ * Open a document as deep as a mounted-block budget allows.
+ *
+ * For a large import. A real 20,407-block book opened fully mounts every block — the cost the
+ * whole scale strategy exists to avoid (CLAUDE.md §2) — so it opens to the deepest level whose
+ * mounted window fits, and the ladder takes the reader further. Returns the SAME list when it
+ * already fits, stored collapse state included: an author's own folds are not overridden.
+ *
+ * Never shallower than level 1. Folding the top level away too would leave nothing on screen
+ * but the chapters' absence; one row per chapter is the floor, over budget or not.
+ */
+export declare function openToFit<C>(blocks: Blocks<C>, budget: number): Blocks<C>;
+/**
+ * The deepest level in the document that governs a subtree.
+ *
+ * The ladder offers rungs only for levels that exist: a document of H1s and H2s should not
+ * show six of them, because four of the buttons would do nothing.
+ */
+export declare function deepestParentLevel(blocks: Blocks): OutlineLevel;
+/**
+ * Which level the tree is currently open to, or null when the state is mixed.
+ *
+ * The ladder highlights a rung only when the document actually matches it. Reporting a
+ * best guess would leave the control lit while the tree says otherwise, and the user would
+ * stop trusting it.
+ */
+export declare function currentOpenLevel(blocks: Blocks): number | null;
+/**
+ * Whether a block is inside a collapsed ancestor, and therefore not rendered.
+ *
+ * Needed by anything that wants to reveal a block: a scroll target that is currently
+ * unmounted has no geometry, so callers must open the way to it first.
+ */
+export declare function isHidden(blocks: Blocks, blockId: string): boolean;
+/**
+ * Close everything except the path to one subtree, and the subtree itself.
+ *
+ * Frame 3a's node menu calls this «فقط این زیردرخت باز بماند». It is the one command that
+ * makes a 50,000-block document usable for a single afternoon's work: every other branch
+ * unmounts, so what is left on screen is exactly the part being written.
+ *
+ * The heading's ANCESTORS have to stay open too, or the isolated subtree would itself be
+ * inside a fold and the command would blank the document — the most obvious way to write
+ * this, and wrong.
+ *
+ * Other branches fold at EVERY depth, not just at their topmost heading. Stopping at the
+ * first fold leaves the old open state buried inside it, so re-opening that branch later
+ * spills exactly what the user had just asked to put away.
+ */
+export declare function isolateSubtree<C>(blocks: Blocks<C>, blockId: string): Blocks<C>;
+//# sourceMappingURL=spine.d.ts.map

package/dist/spine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.d.ts","sourceRoot":"","sources":["../src/spine.ts"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAElF;;;;;;;;;GASG;AAEH;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,MAAM,CAKtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,OAAO,GAClB,MAAM,CAAC,CAAC,CAAC,CA0BX;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAmB1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAQ/D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB9D;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAoB/E"}

package/dist/spine.js

@@ -0,0 +1,213 @@
+import { ancestors, buildIndex, hasChildren, subtreeRange, visibleIndices } from './tree.js';
+import { BODY } from './types.js';
+/**
+ * Operations behind the collapse spine.
+ *
+ * Collapse is the most-used interaction in the product and the mechanism the whole
+ * performance strategy rests on (a collapsed subtree is *unmounted*, never hidden), so its
+ * operations live together rather than scattered through `ops.ts`.
+ *
+ * All of them are pure and return the SAME list when nothing changed, like every other
+ * structural operation here — downstream memoization depends on it.
+ */
+/**
+ * How many blocks a heading would fold away.
+ *
+ * This is what the spine's scope line is a picture of, and what the count pill states. It
+ * excludes the heading itself: the question a reader is asking is "how much disappears if
+ * I click this", and the heading does not.
+ */
+export function subtreeSize(blocks, blockId, index) {
+    const at = blocks.findIndex((block) => block.id === blockId);
+    if (at === -1)
+        return 0;
+    const [start, end] = subtreeRange(index ?? buildIndex(blocks), at);
+    return Math.max(0, end - start - 1);
+}
+/**
+ * Collapse or expand every sibling at one heading's level, within its parent.
+ *
+ * Bound to ⌥click. "Siblings" means blocks with the same parent AND the same level — not
+ * every block at that level in the document, which would fold unrelated branches the user
+ * cannot see and did not ask about.
+ *
+ * The clicked heading decides the direction for all of them: if it is open, they all
+ * close. Deriving each one independently would produce a checkerboard.
+ */
+export function collapseSiblings(blocks, blockId, collapsed) {
+    const index = buildIndex(blocks);
+    const at = blocks.findIndex((block) => block.id === blockId);
+    if (at === -1)
+        return blocks;
+    const level = blocks[at]?.level ?? BODY;
+    if (level === BODY)
+        return blocks;
+    const parent = index.parent[at] ?? -1;
+    const target = collapsed ?? !(blocks[at]?.collapsed ?? false);
+    const wanted = new Set();
+    for (let i = 0; i < blocks.length; i++) {
+        if ((blocks[i]?.level ?? BODY) !== level)
+            continue;
+        if ((index.parent[i] ?? -1) !== parent)
+            continue;
+        // A heading with nothing under it has no collapsed state worth setting.
+        if (!hasChildren(index, i))
+            continue;
+        wanted.add(i);
+    }
+    let changed = false;
+    const next = blocks.map((block, i) => {
+        if (!wanted.has(i) || (block.collapsed ?? false) === target)
+            return block;
+        changed = true;
+        return { ...block, collapsed: target };
+    });
+    return changed ? next : blocks;
+}
+/**
+ * Open the tree down to `level`, closing everything deeper.
+ *
+ * Bound to ⌘⌥1…6 and to the ladder control. `level` 0 means "close everything" — every
+ * heading that governs a subtree folds; a level above the deepest heading means "open
+ * everything".
+ *
+ * Headings with no children are left alone: a collapsed flag on a leaf is invisible, and
+ * setting it would make the ladder's state depend on blocks the reader cannot see.
+ */
+export function openToLevel(blocks, level) {
+    const index = buildIndex(blocks);
+    let changed = false;
+    const next = blocks.map((block, i) => {
+        const blockLevel = block.level ?? BODY;
+        if (blockLevel === BODY || !hasChildren(index, i))
+            return block;
+        /*
+         * A heading AT the target level COLLAPSES: "open to level 2" means level-2 headings
+         * are the deepest thing visible, so their own children are folded away. The heading
+         * itself is still on screen — it is its subtree that closes.
+         */
+        const shouldCollapse = blockLevel >= level;
+        if ((block.collapsed ?? false) === shouldCollapse)
+            return block;
+        changed = true;
+        return { ...block, collapsed: shouldCollapse };
+    });
+    return changed ? next : blocks;
+}
+/**
+ * Open a document as deep as a mounted-block budget allows.
+ *
+ * For a large import. A real 20,407-block book opened fully mounts every block — the cost the
+ * whole scale strategy exists to avoid (CLAUDE.md §2) — so it opens to the deepest level whose
+ * mounted window fits, and the ladder takes the reader further. Returns the SAME list when it
+ * already fits, stored collapse state included: an author's own folds are not overridden.
+ *
+ * Never shallower than level 1. Folding the top level away too would leave nothing on screen
+ * but the chapters' absence; one row per chapter is the floor, over budget or not.
+ */
+export function openToFit(blocks, budget) {
+    const mounted = (candidate) => visibleIndices(candidate, buildIndex(candidate)).length;
+    if (mounted(blocks) <= budget)
+        return blocks;
+    for (let level = deepestParentLevel(blocks); level > 1; level--) {
+        const candidate = openToLevel(blocks, level);
+        if (mounted(candidate) <= budget)
+            return candidate;
+    }
+    return openToLevel(blocks, 1);
+}
+/**
+ * The deepest level in the document that governs a subtree.
+ *
+ * The ladder offers rungs only for levels that exist: a document of H1s and H2s should not
+ * show six of them, because four of the buttons would do nothing.
+ */
+export function deepestParentLevel(blocks) {
+    const index = buildIndex(blocks);
+    let deepest = 0;
+    for (let i = 0; i < blocks.length; i++) {
+        const level = blocks[i]?.level ?? BODY;
+        if (level !== BODY && hasChildren(index, i) && level > deepest)
+            deepest = level;
+    }
+    return deepest;
+}
+/**
+ * Which level the tree is currently open to, or null when the state is mixed.
+ *
+ * The ladder highlights a rung only when the document actually matches it. Reporting a
+ * best guess would leave the control lit while the tree says otherwise, and the user would
+ * stop trusting it.
+ */
+export function currentOpenLevel(blocks) {
+    const index = buildIndex(blocks);
+    let deepestOpen = 0;
+    let shallowestCollapsed = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < blocks.length; i++) {
+        const block = blocks[i];
+        const level = block?.level ?? BODY;
+        if (level === BODY || !hasChildren(index, i))
+            continue;
+        if (block?.collapsed)
+            shallowestCollapsed = Math.min(shallowestCollapsed, level);
+        else
+            deepestOpen = Math.max(deepestOpen, level);
+    }
+    if (shallowestCollapsed === Number.POSITIVE_INFINITY)
+        return deepestOpen + 1;
+    if (deepestOpen === 0)
+        return 0;
+    // Consistent only when every open heading is shallower than every collapsed one.
+    return deepestOpen < shallowestCollapsed ? shallowestCollapsed : null;
+}
+/**
+ * Whether a block is inside a collapsed ancestor, and therefore not rendered.
+ *
+ * Needed by anything that wants to reveal a block: a scroll target that is currently
+ * unmounted has no geometry, so callers must open the way to it first.
+ */
+export function isHidden(blocks, blockId) {
+    const at = blocks.findIndex((block) => block.id === blockId);
+    if (at === -1)
+        return false;
+    const index = buildIndex(blocks);
+    return ancestors(index, at).some((i) => blocks[i]?.collapsed === true);
+}
+/**
+ * Close everything except the path to one subtree, and the subtree itself.
+ *
+ * Frame 3a's node menu calls this «فقط این زیردرخت باز بماند». It is the one command that
+ * makes a 50,000-block document usable for a single afternoon's work: every other branch
+ * unmounts, so what is left on screen is exactly the part being written.
+ *
+ * The heading's ANCESTORS have to stay open too, or the isolated subtree would itself be
+ * inside a fold and the command would blank the document — the most obvious way to write
+ * this, and wrong.
+ *
+ * Other branches fold at EVERY depth, not just at their topmost heading. Stopping at the
+ * first fold leaves the old open state buried inside it, so re-opening that branch later
+ * spills exactly what the user had just asked to put away.
+ */
+export function isolateSubtree(blocks, blockId) {
+    const at = blocks.findIndex((block) => block.id === blockId);
+    if (at === -1)
+        return blocks;
+    const index = buildIndex(blocks);
+    const [, end] = subtreeRange(index, at);
+    const open = new Set(ancestors(index, at));
+    for (let i = at; i < end; i++)
+        open.add(i);
+    let changed = false;
+    const next = blocks.map((block, i) => {
+        // A leaf's collapsed flag is invisible, so leave it exactly as it was.
+        if (!hasChildren(index, i))
+            return block;
+        const collapsed = !open.has(i);
+        if ((block.collapsed === true) === collapsed)
+            return block;
+        changed = true;
+        return { ...block, collapsed };
+    });
+    return changed ? next : blocks;
+}
+//# sourceMappingURL=spine.js.map

package/dist/spine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spine.js","sourceRoot":"","sources":["../src/spine.ts"],"names":[],"mappings":"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"}

package/dist/styles.d.ts

@@ -0,0 +1,63 @@
+import type { Block, Blocks, BlockFormat, NamedStyle, OutlineLevel } from './types.js';
+/**
+ * The chain from `styleId` to its root, nearest first.
+ *
+ * Cycles are broken rather than trusted not to exist: `w:basedOn` pointing back into its
+ * own ancestry is a documented corruption in files produced by older converters, and a
+ * naive walk hangs on it.
+ */
+export declare function styleChain(styleId: string | undefined, styles: readonly NamedStyle[] | undefined): NamedStyle[];
+/**
+ * A block's effective paragraph formatting: the style chain, then direct overrides.
+ *
+ * Merged field by field rather than by object spread of the whole chain, because a style
+ * that sets only `spaceAfterTwips` must not blank out an ancestor's `align`.
+ */
+export declare function effectiveFormat(block: Block<unknown>, styles: readonly NamedStyle[] | undefined): BlockFormat;
+/** Run-level defaults a style contributes, resolved down its chain. */
+export declare function effectiveRunStyle(styleId: string | undefined, styles: readonly NamedStyle[] | undefined): {
+    font?: string;
+    sizeHalfPt?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+};
+/**
+ * The outline level a style implies, from the nearest ancestor that states one.
+ *
+ * Returns `undefined` rather than 0 when nothing in the chain says: 0 is body text, a
+ * real answer, and defaulting to it would silently demote every heading whose style table
+ * failed to load.
+ */
+export declare function styleOutlineLevel(styleId: string | undefined, styles: readonly NamedStyle[] | undefined): OutlineLevel | undefined;
+export interface StyleUsage {
+    readonly style: NamedStyle;
+    /** Blocks referencing this style directly. */
+    readonly count: number;
+    /** Of those, how many also carry direct formatting that overrides it. */
+    readonly overridden: number;
+}
+/**
+ * How many blocks each style governs.
+ *
+ * The number is what makes "redefine this style across the document" a decision rather
+ * than a gamble — "this changes 412 paragraphs" and "this changes 2" are different
+ * actions, and the UI cannot tell them apart without counting.
+ */
+export declare function styleUsage(blocks: Blocks<unknown>, styles: readonly NamedStyle[] | undefined): StyleUsage[];
+/**
+ * Redefine a style, and report what it touched.
+ *
+ * Returns the SAME document reference when nothing changed, as every structural op in
+ * this project does, so downstream memoization holds.
+ */
+export declare function redefineStyle(styles: readonly NamedStyle[] | undefined, styleId: string, patch: Partial<Omit<NamedStyle, 'id'>>): readonly NamedStyle[] | undefined;
+/**
+ * Drop direct formatting from every block using a style, so the style governs again.
+ *
+ * This is what "reset to the style" means in Word, and it is the other half of redefining
+ * one: a redefinition has no visible effect on paragraphs whose direct formatting already
+ * overrides the field being changed.
+ */
+export declare function clearDirectFormat<C>(blocks: Blocks<C>, styleId: string): Blocks<C>;
+//# sourceMappingURL=styles.d.ts.map

package/dist/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAevF;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACxC,UAAU,EAAE,CAad;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EACrB,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACxC,WAAW,CAQb;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACxC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAiB1F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACxC,YAAY,GAAG,SAAS,CAK1B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,EACvB,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GACxC,UAAU,EAAE,CAqBd;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,EACzC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,GACrC,SAAS,UAAU,EAAE,GAAG,SAAS,CAanC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CASlF"}

package/dist/styles.js

@@ -0,0 +1,169 @@
+/**
+ * Named-style resolution.
+ *
+ * Word's model, reproduced exactly: a paragraph's effective formatting is its style's
+ * formatting, merged with the style that style is based on, and so on to the root, with
+ * the paragraph's own direct formatting winning over all of it. Getting the precedence
+ * backwards is invisible on most documents and catastrophic on the one where an author
+ * overrode a heading's spacing.
+ */
+/** Depth limit for `basedOn` walking. Real Word documents contain cycles. */
+const MAX_CHAIN = 32;
+/**
+ * The chain from `styleId` to its root, nearest first.
+ *
+ * Cycles are broken rather than trusted not to exist: `w:basedOn` pointing back into its
+ * own ancestry is a documented corruption in files produced by older converters, and a
+ * naive walk hangs on it.
+ */
+export function styleChain(styleId, styles) {
+    if (!styleId || !styles || styles.length === 0)
+        return [];
+    const byId = new Map(styles.map((style) => [style.id, style]));
+    const chain = [];
+    const seen = new Set();
+    let current = byId.get(styleId);
+    while (current && !seen.has(current.id) && chain.length < MAX_CHAIN) {
+        seen.add(current.id);
+        chain.push(current);
+        current = current.basedOn ? byId.get(current.basedOn) : undefined;
+    }
+    return chain;
+}
+/**
+ * A block's effective paragraph formatting: the style chain, then direct overrides.
+ *
+ * Merged field by field rather than by object spread of the whole chain, because a style
+ * that sets only `spaceAfterTwips` must not blank out an ancestor's `align`.
+ */
+export function effectiveFormat(block, styles) {
+    const chain = styleChain(block.styleId, styles);
+    let out = {};
+    // Root first, so a nearer style overrides a more distant one.
+    for (let i = chain.length - 1; i >= 0; i--) {
+        out = { ...out, ...definedOnly(chain[i].format) };
+    }
+    return { ...out, ...definedOnly(block.format) };
+}
+/** Run-level defaults a style contributes, resolved down its chain. */
+export function effectiveRunStyle(styleId, styles) {
+    const chain = styleChain(styleId, styles);
+    let out = {};
+    for (let i = chain.length - 1; i >= 0; i--) {
+        const style = chain[i];
+        out = {
+            ...out,
+            ...definedOnly({
+                font: style.font,
+                sizeHalfPt: style.sizeHalfPt,
+                bold: style.bold,
+                italic: style.italic,
+                color: style.color,
+            }),
+        };
+    }
+    return out;
+}
+/**
+ * The outline level a style implies, from the nearest ancestor that states one.
+ *
+ * Returns `undefined` rather than 0 when nothing in the chain says: 0 is body text, a
+ * real answer, and defaulting to it would silently demote every heading whose style table
+ * failed to load.
+ */
+export function styleOutlineLevel(styleId, styles) {
+    for (const style of styleChain(styleId, styles)) {
+        if (style.outlineLevel !== undefined)
+            return style.outlineLevel;
+    }
+    return undefined;
+}
+/**
+ * How many blocks each style governs.
+ *
+ * The number is what makes "redefine this style across the document" a decision rather
+ * than a gamble — "this changes 412 paragraphs" and "this changes 2" are different
+ * actions, and the UI cannot tell them apart without counting.
+ */
+export function styleUsage(blocks, styles) {
+    if (!styles || styles.length === 0)
+        return [];
+    const counts = new Map();
+    for (const block of blocks) {
+        if (!block.styleId)
+            continue;
+        const entry = counts.get(block.styleId) ?? { count: 0, overridden: 0 };
+        entry.count += 1;
+        if (block.format && Object.keys(definedOnly(block.format)).length > 0)
+            entry.overridden += 1;
+        counts.set(block.styleId, entry);
+    }
+    return styles
+        .map((style) => ({
+        style,
+        count: counts.get(style.id)?.count ?? 0,
+        overridden: counts.get(style.id)?.overridden ?? 0,
+    }))
+        // Used styles first, then alphabetically — an unused style is still worth listing,
+        // because it is what an author reaches for next.
+        .sort((a, b) => b.count - a.count || a.style.name.localeCompare(b.style.name));
+}
+/**
+ * Redefine a style, and report what it touched.
+ *
+ * Returns the SAME document reference when nothing changed, as every structural op in
+ * this project does, so downstream memoization holds.
+ */
+export function redefineStyle(styles, styleId, patch) {
+    if (!styles)
+        return styles;
+    let changed = false;
+    const next = styles.map((style) => {
+        if (style.id !== styleId)
+            return style;
+        const merged = { ...style, ...definedOnly(patch), format: { ...style.format, ...definedOnly(patch.format) } };
+        if (shallowEqual(merged, style) && shallowEqual(merged.format ?? {}, style.format ?? {})) {
+            return style;
+        }
+        changed = true;
+        return merged;
+    });
+    return changed ? next : styles;
+}
+/**
+ * Drop direct formatting from every block using a style, so the style governs again.
+ *
+ * This is what "reset to the style" means in Word, and it is the other half of redefining
+ * one: a redefinition has no visible effect on paragraphs whose direct formatting already
+ * overrides the field being changed.
+ */
+export function clearDirectFormat(blocks, styleId) {
+    let changed = false;
+    const next = blocks.map((block) => {
+        if (block.styleId !== styleId || !block.format)
+            return block;
+        changed = true;
+        const { format: _dropped, ...rest } = block;
+        return rest;
+    });
+    return changed ? next : blocks;
+}
+/** Strip `undefined` values so a spread does not blank out an inherited field. */
+function definedOnly(value) {
+    if (!value)
+        return {};
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry !== undefined)
+            out[key] = entry;
+    }
+    return out;
+}
+function shallowEqual(a, b) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((key) => a[key] === b[key]);
+}
+//# sourceMappingURL=styles.js.map

package/dist/styles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"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"}

package/dist/tree.d.ts

@@ -0,0 +1,70 @@
+import { type Block, type Blocks, type TreeIndex } from './types.js';
+/**
+ * Build the derived tree in a single O(n) pass.
+ *
+ * The rule that makes body text work: a level-0 block attaches to the nearest open
+ * heading but NEVER terminates a subtree. Only a heading whose level is <= an open
+ * heading's level closes it. This mirrors Word's outline semantics, where body text
+ * under "1.2" stays under "1.2" no matter how much of it there is.
+ *
+ * (The legacy `Document.getDirectChildren` had a bug here: it broke on `level <= own`
+ * without excluding body text, so a heading's direct children were truncated at the
+ * first paragraph of body text. That bug is not reproduced — see the regression test.)
+ */
+export declare function buildIndex(blocks: Blocks): TreeIndex;
+/** `[start, end)` covering `i` and everything beneath it. */
+export declare function subtreeRange(index: TreeIndex, i: number): readonly [number, number];
+/** Every descendant index of `i`, at any depth, in document order. */
+export declare function deepChildren(index: TreeIndex, i: number): number[];
+/** Heading children of `i` — one level down in the DERIVED tree, not by `level`. */
+export declare function childHeadings(blocks: Blocks, index: TreeIndex, i: number): number[];
+/** Body-text blocks belonging directly to `i`. */
+export declare function bodyChildren(blocks: Blocks, index: TreeIndex, i: number): number[];
+/** Chain of ancestors from nearest parent to root. */
+export declare function ancestors(index: TreeIndex, i: number): number[];
+/**
+ * Whether two block lists have the same STRUCTURE: the same blocks, at the same levels,
+ * folded and locked the same way. Text is not structure.
+ *
+ * Everything a view derives from the outline — the tree, the counts, the folds, the locks,
+ * the spine — depends on exactly these fields, and typing never changes one. A memo keyed
+ * on the LIST recomputes per character, because every edit makes a new list; keyed on this
+ * it recomputes when the outline actually moves. The `a === b` check is the fast path:
+ * structural ops share unchanged blocks by reference, and so does the editor's conversion,
+ * so for typing this is a pointer comparison per block.
+ */
+export declare function sameStructure(a: Blocks, b: Blocks): boolean;
+export declare function hasChildren(index: TreeIndex, i: number): boolean;
+/** Index of the nearest preceding heading, or -1. Used by the indent rules. */
+export declare function prevHeading(blocks: Blocks, i: number): number;
+/**
+ * Indices that should actually be rendered, honouring `collapsed`.
+ *
+ * This is the project's primary scale lever. ProseMirror puts the entire document
+ * in the DOM and cannot be virtualized, so the working set has to be small by
+ * construction — and an outline collapsed to level 2 renders hundreds of blocks
+ * rather than tens of thousands. A collapsed subtree must render as NOTHING, not
+ * as hidden DOM, or the lever does no work.
+ */
+export declare function visibleIndices(blocks: Blocks, index: TreeIndex): number[];
+/** Convenience for callers that want blocks rather than indices. */
+export declare function visibleBlocks<C>(blocks: Blocks<C>, index: TreeIndex): Block<C>[];
+/**
+ * Is `i` read-only — either locked itself, or inside a locked subtree?
+ *
+ * Walks ancestors rather than reading a stored flag, which is what keeps lock state
+ * correct for free when a block is moved, indented, or outdented: a block dragged out
+ * of a locked chapter stops being locked because its ancestry changed, with no
+ * bookkeeping pass to get wrong.
+ */
+export declare function isLocked(blocks: Blocks, index: TreeIndex, i: number): boolean;
+/**
+ * The nearest ancestor (or self) that carries the lock, or -1.
+ *
+ * The UI needs this to say WHAT is locked — "this chapter is read-only" is actionable,
+ * "this paragraph is read-only" leaves the reader hunting for the padlock.
+ */
+export declare function lockOwner(blocks: Blocks, index: TreeIndex, i: number): number;
+/** Indices of every read-only block, for bulk checks like a paste guard. */
+export declare function lockedIndices(blocks: Blocks, index: TreeIndex): number[];
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAQ,MAAM,YAAY,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAoCpD;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAEnF;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAIlE;AAED,oFAAoF;AACpF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMnF;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMlF;AAED,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAY3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAWzE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAEhF;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM7E;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,EAAE,CAIxE"}