@tarhnama/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mahdi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @tarhnama/core
+
+Framework-agnostic outline document model: flat blocks with outline levels, plus a derived tree index. No DOM, no editor dependency.
+
+No DOM and no editor dependency, so it runs in Node — batch conversion, indexing, tests.
+
+```bash
+npm install @tarhnama/core
+```
+
+Part of **طرح‌نما**, a Persian-first outline editor. Everything is optional — features,
+styling, and copy — so it can be embedded without bringing opinions you did not ask for.
+See the [consumer guide](https://github.com/mahdi/tarhnama/blob/main/docs/CONSUMING.md) for the styling levels,
+the feature switches and the i18n contract.
+
+Licensed MIT.

package/dist/code-tokens.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The colouring 1a draws in a code block — keywords in the accent, strings in green —
+ * as a pure function over text, so the editor's decorations and both readers colour the
+ * same characters.
+ *
+ * Deliberately small. It is not a parser and does not try to be: a full grammar per
+ * language is a dependency this package must not force on a host, and a host that wants
+ * one passes its own tokenizer with the same signature. What it does, it does exactly —
+ * whole words only, escapes honoured, comment markers inside strings left alone — because
+ * a highlighter that is right most of the time teaches the reader to distrust the colours.
+ *
+ * Numbers and identifiers are not tokens. The prototype colours neither consistently
+ * (`editor` is accent once in 1a and plain on the next line; `const` is plain in 2a-06),
+ * so there is no rule to measure — see docs/DESIGN-REQUESTS.md.
+ */
+export type CodeTokenKind = 'keyword' | 'string' | 'comment';
+export interface CodeToken {
+    /** Offset of the first character, in UTF-16 code units of the block's text. */
+    readonly from: number;
+    /** Offset after the last character. */
+    readonly to: number;
+    readonly kind: CodeTokenKind;
+}
+/** A host-supplied replacement for `tokenizeCode`, e.g. one backed by a real grammar. */
+export type CodeTokenizer = (code: string, lang: string | undefined) => readonly CodeToken[];
+export declare function tokenizeCode(code: string, lang: string | undefined): CodeToken[];
+export interface CodeSegment {
+    readonly text: string;
+    /** Absent for the text between tokens. */
+    readonly kind?: CodeTokenKind;
+}
+/**
+ * The text cut into runs, each token its own. Every renderer goes through this, so the
+ * editor and both readers colour the same characters — including when a HOST tokenizer
+ * returns something malformed: a token that is empty, out of range or overlaps the one
+ * before is skipped, and the text itself always comes back whole.
+ */
+export declare function codeSegments(code: string, tokens: readonly CodeToken[]): CodeSegment[];
+//# sourceMappingURL=code-tokens.d.ts.map

package/dist/code-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-tokens.d.ts","sourceRoot":"","sources":["../src/code-tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B;AAED,yFAAyF;AACzF,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,KAAK,SAAS,SAAS,EAAE,CAAC;AAiG7F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,EAAE,CA4DhF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,WAAW,EAAE,CAWtF"}

package/dist/code-tokens.js

@@ -0,0 +1,189 @@
+/**
+ * The colouring 1a draws in a code block — keywords in the accent, strings in green —
+ * as a pure function over text, so the editor's decorations and both readers colour the
+ * same characters.
+ *
+ * Deliberately small. It is not a parser and does not try to be: a full grammar per
+ * language is a dependency this package must not force on a host, and a host that wants
+ * one passes its own tokenizer with the same signature. What it does, it does exactly —
+ * whole words only, escapes honoured, comment markers inside strings left alone — because
+ * a highlighter that is right most of the time teaches the reader to distrust the colours.
+ *
+ * Numbers and identifiers are not tokens. The prototype colours neither consistently
+ * (`editor` is accent once in 1a and plain on the next line; `const` is plain in 2a-06),
+ * so there is no rule to measure — see docs/DESIGN-REQUESTS.md.
+ */
+const words = (list) => new Set(list.split(/\s+/).filter(Boolean));
+const C_LIKE = {
+    lineComment: '//',
+    blockComment: true,
+    quotes: `'"\``,
+    rawQuotes: '',
+    multilineQuotes: '`',
+    tripleQuotes: false,
+    hashNeedsBoundary: false,
+    memberAccessIsNotKeyword: true,
+};
+/*
+ * Contextual words that are routinely identifiers (`type`, `from`, `of`, `as`, `get`, `set`)
+ * are left out: colouring `const type = …` as a keyword is wrong far more often than
+ * leaving `import x from` plain is.
+ */
+const JS = {
+    ...C_LIKE,
+    keywords: words(`
+    abstract async await break case catch class const continue debugger declare default delete
+    do else enum export extends false finally for function if implements import in instanceof
+    interface keyof let namespace new null private protected public readonly return satisfies
+    static super switch this throw true try typeof undefined var void while with yield
+  `),
+};
+const JSON_GRAMMAR = {
+    keywords: words('true false null'),
+    lineComment: null,
+    blockComment: false,
+    quotes: '"',
+    rawQuotes: '',
+    multilineQuotes: '',
+    tripleQuotes: false,
+    hashNeedsBoundary: false,
+    memberAccessIsNotKeyword: false,
+};
+const PYTHON = {
+    keywords: words(`
+    False None True and as assert async await break class continue def del elif else except
+    finally for from global if import in is lambda nonlocal not or pass raise return try while
+    with yield
+  `),
+    lineComment: '#',
+    blockComment: false,
+    quotes: `'"`,
+    rawQuotes: '',
+    multilineQuotes: '',
+    tripleQuotes: true,
+    hashNeedsBoundary: false,
+    memberAccessIsNotKeyword: true,
+};
+const SHELL = {
+    keywords: words('if then else elif fi case esac for while until do done in function return exit local export select'),
+    lineComment: '#',
+    blockComment: false,
+    quotes: `'"`,
+    rawQuotes: "'",
+    multilineQuotes: `'"`,
+    tripleQuotes: false,
+    hashNeedsBoundary: true,
+    memberAccessIsNotKeyword: false,
+};
+const GRAMMARS = {
+    js: JS, jsx: JS, mjs: JS, cjs: JS, javascript: JS,
+    ts: JS, tsx: JS, mts: JS, cts: JS, typescript: JS,
+    json: JSON_GRAMMAR, jsonc: { ...JSON_GRAMMAR, lineComment: '//', blockComment: true },
+    py: PYTHON, python: PYTHON, python3: PYTHON,
+    sh: SHELL, bash: SHELL, zsh: SHELL, shell: SHELL, console: SHELL,
+};
+const WORD_START = /[\p{L}_$]/u;
+const WORD_PART = /[\p{L}\p{N}_$]/u;
+export function tokenizeCode(code, lang) {
+    const grammar = lang ? GRAMMARS[lang.trim().toLowerCase()] : undefined;
+    if (!grammar)
+        return [];
+    const tokens = [];
+    const length = code.length;
+    let i = 0;
+    while (i < length) {
+        const ch = code[i];
+        if (grammar.lineComment && code.startsWith(grammar.lineComment, i)) {
+            const atBoundary = i === 0 || /\s/.test(code[i - 1]);
+            if (!grammar.hashNeedsBoundary || atBoundary) {
+                const end = lineEnd(code, i);
+                tokens.push({ from: i, to: end, kind: 'comment' });
+                i = end;
+                continue;
+            }
+        }
+        if (grammar.blockComment && code.startsWith('/*', i)) {
+            const close = code.indexOf('*/', i + 2);
+            const end = close === -1 ? length : close + 2;
+            tokens.push({ from: i, to: end, kind: 'comment' });
+            i = end;
+            continue;
+        }
+        if (grammar.quotes.includes(ch)) {
+            const end = grammar.tripleQuotes && code.startsWith(ch.repeat(3), i)
+                ? tripleQuoteEnd(code, i, ch)
+                : quoteEnd(code, i, ch, grammar.multilineQuotes.includes(ch), !grammar.rawQuotes.includes(ch));
+            tokens.push({ from: i, to: end, kind: 'string' });
+            i = end;
+            continue;
+        }
+        if (WORD_START.test(ch)) {
+            let end = i + 1;
+            while (end < length && WORD_PART.test(code[end]))
+                end += 1;
+            const word = code.slice(i, end);
+            const member = grammar.memberAccessIsNotKeyword && i > 0 && code[i - 1] === '.';
+            if (!member && grammar.keywords.has(word))
+                tokens.push({ from: i, to: end, kind: 'keyword' });
+            i = end;
+            continue;
+        }
+        // A digit run is skipped whole, so `1e5` or `0x1f` never starts a word in its middle.
+        if (/\p{N}/u.test(ch)) {
+            let end = i + 1;
+            while (end < length && WORD_PART.test(code[end]))
+                end += 1;
+            i = end;
+            continue;
+        }
+        i += 1;
+    }
+    return tokens;
+}
+/**
+ * The text cut into runs, each token its own. Every renderer goes through this, so the
+ * editor and both readers colour the same characters — including when a HOST tokenizer
+ * returns something malformed: a token that is empty, out of range or overlaps the one
+ * before is skipped, and the text itself always comes back whole.
+ */
+export function codeSegments(code, tokens) {
+    const segments = [];
+    let at = 0;
+    for (const token of tokens) {
+        if (token.from < at || token.to <= token.from || token.to > code.length)
+            continue;
+        if (token.from > at)
+            segments.push({ text: code.slice(at, token.from) });
+        segments.push({ text: code.slice(token.from, token.to), kind: token.kind });
+        at = token.to;
+    }
+    if (at < code.length)
+        segments.push({ text: code.slice(at) });
+    return segments;
+}
+function lineEnd(code, from) {
+    const newline = code.indexOf('\n', from);
+    return newline === -1 ? code.length : newline;
+}
+/** After the closing quote; an unterminated single-line quote stops at the end of its line. */
+function quoteEnd(code, from, quote, multiline, escapes) {
+    let i = from + 1;
+    while (i < code.length) {
+        const ch = code[i];
+        if (escapes && ch === '\\') {
+            i += 2;
+            continue;
+        }
+        if (ch === quote)
+            return i + 1;
+        if (ch === '\n' && !multiline)
+            return i;
+        i += 1;
+    }
+    return code.length;
+}
+function tripleQuoteEnd(code, from, quote) {
+    const close = code.indexOf(quote.repeat(3), from + 3);
+    return close === -1 ? code.length : close + 3;
+}
+//# sourceMappingURL=code-tokens.js.map

package/dist/code-tokens.js.map

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

package/dist/context-menu.d.ts

@@ -0,0 +1,59 @@
+import type { OutlineFeatureName, OutlineFeatures } from './features.js';
+/**
+ * What a right-click on the document offers.
+ *
+ * The spine's handle already has a node menu. The TEXT does not, so right-clicking a
+ * paragraph gets the browser's own menu — spell-check and "view source", nothing about the
+ * document you are writing.
+ *
+ * Computed as DATA, like the shortcut registry and for the same reasons: a host can render
+ * it in their own menu component, translate it through their own label pack, filter it, or
+ * ignore it entirely. Nothing here holds a closure or touches the DOM.
+ */
+export type ContextCommand = 'cut' | 'copy' | 'paste' | 'undo' | 'redo' | 'indent' | 'outdent' | 'moveUp' | 'moveDown' | 'toggleCollapse' | 'isolate' | 'focus' | 'toggleLock';
+/** What the host knows about the place that was right-clicked. */
+export interface ContextTarget {
+    readonly blockId: string;
+    readonly level: number;
+    readonly hasSelection: boolean;
+    readonly locked: boolean;
+    readonly collapsed: boolean;
+    /** Whether this heading governs anything — a fold with nothing under it does nothing. */
+    readonly governsSubtree: boolean;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /**
+     * Whether a sibling exists to move past.
+     *
+     * Part of the target rather than derived here, for the same reason as the undo stack:
+     * this function is handed one block, and "is there a previous sibling" is a question only
+     * the whole document can answer. Getting it wrong is not cosmetic — "move down" was live
+     * on a heading with nowhere to go, and choosing it did nothing.
+     */
+    readonly canMoveUp: boolean;
+    readonly canMoveDown: boolean;
+}
+export interface ContextMenuItem {
+    readonly command: ContextCommand;
+    /** English; a host translates through their own label pack. */
+    readonly label: string;
+    readonly enabled: boolean;
+    /** A rule drawn before this item. Named here so a renderer does not invent grouping. */
+    readonly separator?: boolean;
+    readonly feature?: OutlineFeatureName;
+}
+/**
+ * Build the menu for one right-click.
+ *
+ * Two rules, and the difference between them is the whole design:
+ *
+ * **A command that cannot act right now is DIMMED.** The menu has the same shape every
+ * time it opens, so its geometry can be learned and the third item is always the third
+ * item. This is the rule the toolbars follow.
+ *
+ * **A command whose FEATURE is off is REMOVED.** Dimming says "not now", which is a
+ * promise. A feature the host switched off is never coming back, and leaving it there
+ * spends the reader's attention on it at every opening, forever.
+ */
+export declare function contextMenuFor(target: ContextTarget, features: OutlineFeatures): readonly ContextMenuItem[];
+//# sourceMappingURL=context-menu.d.ts.map

package/dist/context-menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-menu.d.ts","sourceRoot":"","sources":["../src/context-menu.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEzE;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GACtB,KAAK,GACL,MAAM,GACN,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,UAAU,GACV,gBAAgB,GAChB,SAAS,GACT,OAAO,GACP,YAAY,CAAC;AAEjB,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;CACvC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,eAAe,GACxB,SAAS,eAAe,EAAE,CA4D5B"}

package/dist/context-menu.js

@@ -0,0 +1,69 @@
+/**
+ * Build the menu for one right-click.
+ *
+ * Two rules, and the difference between them is the whole design:
+ *
+ * **A command that cannot act right now is DIMMED.** The menu has the same shape every
+ * time it opens, so its geometry can be learned and the third item is always the third
+ * item. This is the rule the toolbars follow.
+ *
+ * **A command whose FEATURE is off is REMOVED.** Dimming says "not now", which is a
+ * promise. A feature the host switched off is never coming back, and leaving it there
+ * spends the reader's attention on it at every opening, forever.
+ */
+export function contextMenuFor(target, features) {
+    // A lock stops EDITING, never reading — so copy survives it and the mutating pair does not.
+    const editable = !target.locked;
+    const all = [
+        {
+            command: 'cut',
+            label: 'Cut',
+            enabled: target.hasSelection && editable,
+            feature: 'clipboard',
+        },
+        { command: 'copy', label: 'Copy', enabled: target.hasSelection, feature: 'clipboard' },
+        { command: 'paste', label: 'Paste', enabled: editable, feature: 'clipboard' },
+        {
+            command: 'undo',
+            label: 'Undo',
+            enabled: target.canUndo,
+            separator: true,
+            feature: 'history',
+        },
+        { command: 'redo', label: 'Redo', enabled: target.canRedo, feature: 'history' },
+        /*
+         * Structural commands carry no feature: indent and outdent ARE the outline, not a
+         * feature of it, and an editor without them is a different product rather than this
+         * one configured down.
+         */
+        { command: 'indent', label: 'Indent', enabled: editable && target.level > 0, separator: true },
+        { command: 'outdent', label: 'Outdent', enabled: editable && target.level > 1 },
+        { command: 'moveUp', label: 'Move up', enabled: editable && target.canMoveUp },
+        { command: 'moveDown', label: 'Move down', enabled: editable && target.canMoveDown },
+        {
+            command: 'toggleCollapse',
+            label: target.collapsed ? 'Expand' : 'Collapse',
+            // A heading that governs nothing has nothing to fold — the spine's eighth state,
+            // in menu form.
+            enabled: target.governsSubtree,
+            separator: true,
+            feature: 'collapse',
+        },
+        {
+            command: 'isolate',
+            label: 'Keep only this subtree open',
+            enabled: target.governsSubtree,
+            feature: 'collapse',
+        },
+        { command: 'focus', label: 'Focus this subtree', enabled: target.governsSubtree },
+        {
+            command: 'toggleLock',
+            label: target.locked ? 'Unlock' : 'Lock',
+            enabled: true,
+            separator: true,
+            feature: 'lock',
+        },
+    ];
+    return all.filter((item) => item.feature === undefined || features[item.feature]);
+}
+//# sourceMappingURL=context-menu.js.map

package/dist/context-menu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-menu.js","sourceRoot":"","sources":["../src/context-menu.ts"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAqB,EACrB,QAAyB;IAEzB,4FAA4F;IAC5F,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC;IAEhC,MAAM,GAAG,GAAsB;QAC7B;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK;YACZ,OAAO,EAAE,MAAM,CAAC,YAAY,IAAI,QAAQ;YACxC,OAAO,EAAE,WAAW;SACrB;QACD,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE;QACtF,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE;QAE7E;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,MAAM;YACb,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,SAAS;SACnB;QACD,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE;QAE/E;;;;WAIG;QACH,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE;QAC9F,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE;QAC/E,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,SAAS,EAAE;QAC9E,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,IAAI,MAAM,CAAC,WAAW,EAAE;QAEpF;YACE,OAAO,EAAE,gBAAgB;YACzB,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU;YAC/C,iFAAiF;YACjF,gBAAgB;YAChB,OAAO,EAAE,MAAM,CAAC,cAAc;YAC9B,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,UAAU;SACpB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,6BAA6B;YACpC,OAAO,EAAE,MAAM,CAAC,cAAc;YAC9B,OAAO,EAAE,UAAU;SACpB;QACD,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,CAAC,cAAc,EAAE;QAEjF;YACE,OAAO,EAAE,YAAY;YACrB,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;YACxC,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,IAAI;YACf,OAAO,EAAE,MAAM;SAChB;KACF,CAAC;IAEF,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AACpF,CAAC"}

package/dist/features.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+/** Every switchable behaviour. Deliberately flat and small; this is a public contract. */
+export interface OutlineFeatures {
+    /**
+     * `[[` autocomplete, anchor commands, link input rules, reference previews.
+     * Existing link marks still render and still round-trip when this is off.
+     */
+    readonly links: boolean;
+    /** Bold/italic/colour/highlight commands and the formatting keymap (⌘B and friends). */
+    readonly formatting: boolean;
+    /** Collapse state, the spine, the hidden-count decorations, ⌘. and the ladder. */
+    readonly collapse: boolean;
+    /** Read-only subtrees, the lock guard, and the padlock affordance. */
+    readonly lock: boolean;
+    /** Undo/redo. Turn OFF when adopting Yjs: two undo managers fight (see CLAUDE.md §4). */
+    readonly history: boolean;
+    /** Table editing commands. Existing tables still render either way. */
+    readonly tables: boolean;
+    /** Image insertion. Existing images still render either way. */
+    readonly images: boolean;
+    /**
+     * Outline-aware copy: the host's serializer decides the `text/plain` flavour.
+     * Off leaves ProseMirror's default, which loses every level.
+     */
+    readonly clipboard: boolean;
+}
+export type OutlineFeatureName = keyof OutlineFeatures;
+/**
+ * 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 declare const ALL_FEATURES: OutlineFeatures;
+/** Nothing but text. Useful as a base to switch individual features back on. */
+export declare const NO_FEATURES: OutlineFeatures;
+/**
+ * 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 declare function resolveFeatures(input?: Partial<OutlineFeatures> | readonly OutlineFeatureName[] | undefined): OutlineFeatures;
+/**
+ * How the document is being used.
+ *
+ * A separate axis from features, not another flag among them: `read` is not "formatting
+ * off plus links off", it is a different contract — nothing may mutate the document, and
+ * the machinery that exists to mutate it does not need to be constructed at all.
+ */
+export type OutlineMode = 'edit' | 'read';
+/**
+ * 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 declare function featuresForMode(features: OutlineFeatures, mode: OutlineMode): OutlineFeatures;
+/**
+ * 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 declare function featureKey(features: OutlineFeatures): string;
+//# sourceMappingURL=features.d.ts.map

package/dist/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../src/features.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,eAAe,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,eAS1B,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,WAAW,EAAE,eASzB,CAAC;AAIF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,KAAK,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAC3E,eAAe,CAkBjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,GAAG,eAAe,CAU7F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAE5D"}