smartrte-core 0.2.1 → 1.0.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.0.0-beta.2
+
+- Add an opt-in `renderFormulaHtml` option to `serializeCanonicalListHtml` that bakes real KaTeX-rendered HTML into exported formula elements, instead of leaving an empty placeholder — for consumers (e.g. a read-only preview) that display this HTML directly without also running KaTeX against it themselves. Off by default; no change for existing consumers.
+
+## 1.0.0-beta.1
+
+**BREAKING CHANGE.** This is the first release built on the canonical, schema-driven document model. Every published version through 0.2.1 was built on the older discriminated-union model; none of the work below has shipped before.
+
+- Introduce the canonical document model and editing engine (`smartrte-core/foundation`): schema-driven nodes with stable IDs, a scope/position API, structural history, and dedicated engines for lists, marks, blocks, tables, and atoms (images, formulas, media).
+- Add a clipboard pipeline with source-aware normalization (Word, Google Docs, spreadsheets, Markdown, native) and a sanitize-first security boundary.
+- Add DOCX, PDF, and Markdown format codecs with an explicit, tested `FeatureFormatCodec` fidelity contract (`full`/`semantic`/`lossy`/`unsupported`) per feature and format — no fidelity claim ships without a passing round-trip fixture.
+- Add live KaTeX rendering for formula atoms (real HTML + MathML output, `trust:false`, `strict:"error"`), replacing plain-text LaTeX source display.
+- Make the package genuinely framework-agnostic: no DOM-library dependency in the format codecs (parse5/`@xmldom/xmldom` replace real-DOM usage), zero React imports anywhere in `smartrte-core`.
+- **Breaking:** the package root (`.`) no longer re-exports the legacy discriminated-union model, its plugin system, or the HTML/Markdown compatibility layers. That surface is unchanged and still fully available at `smartrte-core/legacy`; only the accidental root-level duplication was removed.
+- **Breaking:** `smartrte-core/foundation` now exports `FOUNDATION_SMART_LIST_PRESETS` and related list-preset helpers (previously unreachable from the package's public exports).
+
 ## 0.2.1
 
 - Keep superscript and subscript mutually exclusive when converting selected text.

package/README.md

@@ -3,3 +3,26 @@
 Framework-agnostic document model, selection, transaction, history, and
 normalization primitives. This package is not yet wired into the published
 React editor; it establishes the compatibility-safe migration boundary.
+
+## Foundation contract
+
+The frozen Phase 1/C0 kernel is available from the dedicated subpath:
+
+```ts
+import {
+  createFoundationEditor,
+  foundationSchema,
+  resolveScope,
+  type ResolvedPos,
+  type SmartTransaction,
+} from "smartrte-core/foundation";
+```
+
+The package root remains the compatibility API for the current React adapter.
+New kernel and Phase 2 resolver work must use `smartrte-core/foundation`; do not
+extend the legacy raw-path contracts. `pnpm run lint:foundation-boundary`
+enforces that boundary. Root promotion is an explicit Phase 3 list-migration
+exit criterion. See `docs/FOUNDATION_CONTRACT.md` in the repository for the
+locked decisions and `docs/SEMANTIC_SELECTION_CONTRACT.md` for Phase 2.
+The persistent apply, incremental index, renderer, and browser-input contracts
+are recorded in `docs/CANONICAL_EDITING_SURFACE.md`.

package/dist/command.d.ts

@@ -1,13 +1,13 @@
-import type { SmartDocument } from "./model.js";
-import type { SmartSelection } from "./selection.js";
-import type { SmartTransaction } from "./transaction.js";
-export interface CommandContext {
-    document: SmartDocument;
-    selection: SmartSelection;
+import type { LegacySmartDocument } from "./model.js";
+import type { LegacySmartSelection } from "./selection.js";
+import type { LegacySmartTransaction } from "./transaction.js";
+export interface LegacyCommandContext {
+    document: LegacySmartDocument;
+    selection: LegacySmartSelection;
     now?: () => number;
 }
 export interface SmartCommand<Input = unknown> {
     id: string;
-    isEnabled(context: CommandContext, input?: Input): boolean;
-    execute(context: CommandContext, input?: Input): SmartTransaction;
+    isEnabled(context: LegacyCommandContext, input?: Input): boolean;
+    execute(context: LegacyCommandContext, input?: Input): LegacySmartTransaction;
 }

package/dist/editor.d.ts

@@ -0,0 +1,32 @@
+import { type SmartHistoryState } from "./history.js";
+import { type SmartRtePlugin } from "./plugin.js";
+import { type SmartEditorState, type LegacySmartTransaction } from "./transaction.js";
+export interface CreateSmartEditorOptions {
+    state: SmartEditorState;
+    plugins?: SmartRtePlugin[];
+    historyLimit?: number;
+    readOnly?: boolean;
+}
+export type SmartEditorListener = (state: SmartEditorState, transaction: LegacySmartTransaction) => void;
+export declare class SmartEditor {
+    private currentState;
+    private currentHistory;
+    private readonly plugins;
+    private readonly schema;
+    private readonly commands;
+    private readonly listeners;
+    private readOnly;
+    constructor(options: CreateSmartEditorOptions);
+    get state(): SmartEditorState;
+    get history(): SmartHistoryState;
+    get pluginIds(): string[];
+    setReadOnly(readOnly: boolean): void;
+    canExecute<Input>(id: string, input?: Input): boolean;
+    execute<Input>(id: string, input?: Input): boolean;
+    dispatch(transaction: LegacySmartTransaction): boolean;
+    undo(): boolean;
+    redo(): boolean;
+    subscribe(listener: SmartEditorListener): () => void;
+    private withPluginNormalization;
+}
+export declare const createSmartEditor: (options: CreateSmartEditorOptions) => SmartEditor;

package/dist/editor.js

@@ -0,0 +1,121 @@
+import { applyTransactionWithHistory, createHistoryState, redoHistory, undoHistory, } from "./history.js";
+import { createSmartSchema, normalizeSmartDocument, validateSmartDocument, } from "./schema.js";
+import { orderPlugins } from "./plugin.js";
+import { applyTransaction } from "./transaction.js";
+const sameDocument = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+export class SmartEditor {
+    constructor(options) {
+        this.commands = new Map();
+        this.listeners = new Set();
+        this.plugins = orderPlugins(options.plugins || []);
+        this.schema = createSmartSchema(this.plugins
+            .filter((plugin) => plugin.schema)
+            .map((plugin) => ({ id: plugin.id, ...plugin.schema })));
+        const document = normalizeSmartDocument(options.state.document, this.schema);
+        const validation = validateSmartDocument(document, this.schema);
+        if (!validation.valid)
+            throw new Error(`Initial document is invalid: ${validation.issues[0]?.message}`);
+        this.currentState = { document, selection: options.state.selection };
+        this.currentHistory = createHistoryState(options.historyLimit);
+        this.readOnly = options.readOnly ?? false;
+        this.plugins.forEach((plugin) => {
+            Object.entries(plugin.commands || {}).forEach(([id, command]) => {
+                if (this.commands.has(id))
+                    throw new Error(`Duplicate command id "${id}".`);
+                this.commands.set(id, command);
+            });
+        });
+    }
+    get state() {
+        return this.currentState;
+    }
+    get history() {
+        return this.currentHistory;
+    }
+    get pluginIds() {
+        return this.plugins.map((plugin) => plugin.id);
+    }
+    setReadOnly(readOnly) {
+        this.readOnly = readOnly;
+    }
+    canExecute(id, input) {
+        if (this.readOnly)
+            return false;
+        const command = this.commands.get(id);
+        return Boolean(command?.isEnabled(this.currentState, input));
+    }
+    execute(id, input) {
+        if (!this.canExecute(id, input))
+            return false;
+        const command = this.commands.get(id);
+        return this.dispatch(command.execute(this.currentState, input));
+    }
+    dispatch(transaction) {
+        if (this.readOnly && transaction.source === "user")
+            return false;
+        const prepared = this.withPluginNormalization(transaction);
+        const result = applyTransactionWithHistory(this.currentState, this.currentHistory, prepared);
+        this.currentState = result.state;
+        this.currentHistory = result.history;
+        this.plugins.forEach((plugin) => plugin.onTransaction?.(prepared));
+        this.listeners.forEach((listener) => listener(this.currentState, prepared));
+        return true;
+    }
+    undo() {
+        if (this.readOnly)
+            return false;
+        const result = undoHistory(this.currentState, this.currentHistory);
+        if (!result.applied)
+            return false;
+        this.currentState = result.state;
+        this.currentHistory = result.history;
+        const transaction = result.history.redo[result.history.redo.length - 1]?.inverse;
+        if (transaction)
+            this.listeners.forEach((listener) => listener(this.currentState, transaction));
+        return true;
+    }
+    redo() {
+        if (this.readOnly)
+            return false;
+        const result = redoHistory(this.currentState, this.currentHistory);
+        if (!result.applied)
+            return false;
+        this.currentState = result.state;
+        this.currentHistory = result.history;
+        const transaction = result.history.undo[result.history.undo.length - 1]?.forward;
+        if (transaction)
+            this.listeners.forEach((listener) => listener(this.currentState, transaction));
+        return true;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    withPluginNormalization(transaction) {
+        const base = applyTransaction(this.currentState, transaction);
+        let document = base.document;
+        for (let pass = 0; pass < 10; pass += 1) {
+            const beforePass = document;
+            document = normalizeSmartDocument(document, this.schema);
+            this.plugins.forEach((plugin) => {
+                (plugin.normalizers || []).forEach((normalizer) => {
+                    document = normalizeSmartDocument(normalizer(document), this.schema);
+                });
+            });
+            if (sameDocument(document, beforePass))
+                break;
+            if (pass === 9)
+                throw new Error("Plugin normalization did not reach a fixed point.");
+        }
+        const validation = validateSmartDocument(document, this.schema);
+        if (!validation.valid)
+            throw new Error(`Plugin normalization produced an invalid document: ${validation.issues[0]?.message}`);
+        if (sameDocument(document, base.document))
+            return transaction;
+        return {
+            ...transaction,
+            operations: [...transaction.operations, { type: "replaceNode", path: [], node: document }],
+        };
+    }
+}
+export const createSmartEditor = (options) => new SmartEditor(options);

package/dist/foundation/annotations/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./range.js";

package/dist/foundation/annotations/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./range.js";

package/dist/foundation/annotations/range.d.ts

@@ -0,0 +1,54 @@
+import type { SmartDocument, SmartOperation, SmartRange } from "../types.js";
+import type { PositionLookup } from "../scope/types.js";
+import type { AnnotationRange, MergeOrphanPolicy } from "./types.js";
+/**
+ * Resolves an AnnotationRange against the current document. For every
+ * operation type except splitNode/mergeNode, node identity survives
+ * unchanged (move: the id follows the node; insert/remove/text/marks: never
+ * touch node ids; setNodeType: id explicitly preserved), so this alone is
+ * enough to track a range through most edits - PositionLookup's `positionOf`
+ * resolves it fresh each call. Returns null once an anchor id no longer
+ * exists (removed, or retired by a merge with no rebase applied).
+ */
+export declare const resolveAnnotationRange: (range: AnnotationRange, positions: PositionLookup) => SmartRange | null;
+/**
+ * Rebases an AnnotationRange through a single operation. Every operation
+ * type other than split/merge/an-explicitly-marked-merge-shaped-removeNode-
+ * or-replaceNode is a no-op here - node identity already survives them, so
+ * the range's stored ids stay valid and `resolveAnnotationRange` picks up
+ * the new position on its own next call. `positions` must resolve against
+ * the document as it existed immediately before `operation` is applied.
+ */
+export declare const rebaseAnnotationRange: (range: AnnotationRange, operation: SmartOperation, positions: PositionLookup, onOrphan: MergeOrphanPolicy) => AnnotationRange | null;
+/**
+ * Folds `rebaseAnnotationRange` over a sequence of operations, e.g. every
+ * operation in one transaction, in order. Each step's `positions` must
+ * resolve against the document as it existed immediately before that step's
+ * operation - the caller (which is already applying the operations to
+ * advance the document) is in the natural position to supply this.
+ */
+export declare const rebaseAnnotationRangeThroughOperations: (range: AnnotationRange, steps: readonly {
+    readonly operation: SmartOperation;
+    readonly positions: PositionLookup;
+}[], onOrphan: MergeOrphanPolicy) => AnnotationRange | null;
+/**
+ * Reference `MergeOrphanPolicy`: snap to the surviving node rather than
+ * drop (Phase 12a's decision - a comment on content that got merged into
+ * something else is still relevant to that content's new home; silently
+ * vanishing it loses data with no recovery path). Only applicable to a
+ * real `mergeNode` operation (`input.ts`'s cross-block Backspace/Delete
+ * text-merge) - unlike `mergedInto`/`retiredInto` above, `mergeNode`'s own
+ * shape has no explicit survivor field, so deriving it needs the actual
+ * document tree (the sibling immediately preceding the merge point,
+ * matching how `input.ts`'s `queueRangeDeletion` constructs the
+ * operation: `retiredId` is the right/consumed block, the left/absorbing
+ * block sits one offset earlier at the same parent). `positions` alone
+ * (an id-keyed lookup) can't answer "what's at this path" in the reverse
+ * direction, so this needs `document` explicitly, unlike every other
+ * function in this file.
+ *
+ * Table-cell-merge and list-item-merge don't need this - they always
+ * populate `mergedInto`/`retiredInto` themselves, so `rebaseAnnotationRange`
+ * snaps them unconditionally with no caller policy involved at all.
+ */
+export declare const defaultMergeOrphanPolicy: (document: SmartDocument) => MergeOrphanPolicy;

package/dist/foundation/annotations/range.js

@@ -0,0 +1,158 @@
+import { isTextNode } from "../identity.js";
+import { nodeAtPath } from "../positions.js";
+const samePath = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+const resolveEndpoint = (id, offset, side, positions) => {
+    if (offset === undefined) {
+        const outer = positions.rangeOf(id);
+        return outer ? outer[side] : null;
+    }
+    const resolved = positions.positionOf(id);
+    if (!resolved)
+        return null;
+    return { path: [...resolved.pos.path, resolved.pos.offset], offset };
+};
+/**
+ * Resolves an AnnotationRange against the current document. For every
+ * operation type except splitNode/mergeNode, node identity survives
+ * unchanged (move: the id follows the node; insert/remove/text/marks: never
+ * touch node ids; setNodeType: id explicitly preserved), so this alone is
+ * enough to track a range through most edits - PositionLookup's `positionOf`
+ * resolves it fresh each call. Returns null once an anchor id no longer
+ * exists (removed, or retired by a merge with no rebase applied).
+ */
+export const resolveAnnotationRange = (range, positions) => {
+    const from = resolveEndpoint(range.startId, range.startOffset, "from", positions);
+    const to = resolveEndpoint(range.endId, range.endOffset, "to", positions);
+    return from && to ? { from, to } : null;
+};
+const splitTargetPath = (operation) => operation.pos.path.slice(0, operation.pos.path.length - operation.depth);
+/**
+ * Split keeps the pre-split id on the left half and mints `newId` for the
+ * right half. An endpoint whose offset lands at or past the split point
+ * moved into the right half - its id must be rewritten, or it would keep
+ * resolving (via `positionOf`) to the left half's now-unrelated content,
+ * silently pointing at the wrong node instead of failing loudly. An
+ * endpoint anchored to a different node entirely, or one whose offset is
+ * undefined (whole-node anchor, not yet split-aware), passes through
+ * unchanged.
+ */
+const rebaseEndpointThroughSplit = (id, offset, operation, positions) => {
+    if (offset === undefined)
+        return { id, offset };
+    const resolved = positions.positionOf(id);
+    if (!resolved)
+        return { id, offset };
+    const path = [...resolved.pos.path, resolved.pos.offset];
+    if (!samePath(path, splitTargetPath(operation)))
+        return { id, offset };
+    if (offset < operation.pos.offset)
+        return { id, offset };
+    return { id: operation.newId, offset: offset - operation.pos.offset };
+};
+const rebaseThroughSplit = (range, operation, positions) => {
+    const start = rebaseEndpointThroughSplit(range.startId, range.startOffset, operation, positions);
+    const end = rebaseEndpointThroughSplit(range.endId, range.endOffset, operation, positions);
+    return { startId: start.id, startOffset: start.offset, endId: end.id, endOffset: end.offset };
+};
+const rebaseThroughMerge = (range, operation, positions, onOrphan) => {
+    if (range.startId !== operation.retiredId && range.endId !== operation.retiredId)
+        return range;
+    return onOrphan(range, operation, positions);
+};
+/**
+ * An endpoint anchored to a retired id snaps to its survivor's whole-node
+ * span (offset cleared, not remapped) - the survivor is a different node
+ * whose content was assembled by concatenating multiple sources in an
+ * order this generic mechanism has no way to know (e.g. `mergeItems`'
+ * `mergeOwners` combines two paragraphs' text in an order that depends on
+ * merge direction), so a stale offset into the retired node's own text
+ * cannot be reliably remapped into the merged text - a wrong-but-
+ * plausible-looking offset would be worse than an honest whole-node
+ * anchor. Unlike the mergeNode case above, there is no caller-supplied
+ * policy here: `mergedInto`/`retiredInto` are opt-in fields a command
+ * populates only when it knows exactly where the content went, so
+ * snapping is the unambiguous, mechanical consequence of the field's
+ * presence, not a product decision requiring caller input - the actual
+ * product decision already happened at the command layer, by choosing to
+ * populate the field at all instead of leaving the operation as a plain,
+ * policy-free removeNode/replaceNode.
+ */
+const snapEndpoint = (id, offset, retiredId, survivorId) => id === retiredId ? { id: survivorId } : { id, offset };
+// Preserves reference identity when neither endpoint actually matches
+// retiredId - a consumer rebasing many ranges through the same operation
+// (see comments/rebase.ts) relies on `===` to cheaply tell which ones
+// actually changed, e.g. to avoid re-persisting or re-rendering untouched
+// threads.
+const rebaseThroughMergedRemove = (range, retiredId, survivorId) => {
+    if (range.startId !== retiredId && range.endId !== retiredId)
+        return range;
+    const start = snapEndpoint(range.startId, range.startOffset, retiredId, survivorId);
+    const end = snapEndpoint(range.endId, range.endOffset, retiredId, survivorId);
+    return { startId: start.id, startOffset: start.offset, endId: end.id, endOffset: end.offset };
+};
+const rebaseThroughRetiredReplace = (range, retirements) => retirements.reduce((current, { retiredId, survivorId }) => rebaseThroughMergedRemove(current, retiredId, survivorId), range);
+/**
+ * Rebases an AnnotationRange through a single operation. Every operation
+ * type other than split/merge/an-explicitly-marked-merge-shaped-removeNode-
+ * or-replaceNode is a no-op here - node identity already survives them, so
+ * the range's stored ids stay valid and `resolveAnnotationRange` picks up
+ * the new position on its own next call. `positions` must resolve against
+ * the document as it existed immediately before `operation` is applied.
+ */
+export const rebaseAnnotationRange = (range, operation, positions, onOrphan) => {
+    if (operation.type === "splitNode")
+        return rebaseThroughSplit(range, operation, positions);
+    if (operation.type === "mergeNode")
+        return rebaseThroughMerge(range, operation, positions, onOrphan);
+    if (operation.type === "removeNode" && operation.mergedInto && !isTextNode(operation.node)) {
+        return rebaseThroughMergedRemove(range, operation.node.id, operation.mergedInto);
+    }
+    if (operation.type === "replaceNode" && operation.retiredInto?.length)
+        return rebaseThroughRetiredReplace(range, operation.retiredInto);
+    return range;
+};
+/**
+ * Folds `rebaseAnnotationRange` over a sequence of operations, e.g. every
+ * operation in one transaction, in order. Each step's `positions` must
+ * resolve against the document as it existed immediately before that step's
+ * operation - the caller (which is already applying the operations to
+ * advance the document) is in the natural position to supply this.
+ */
+export const rebaseAnnotationRangeThroughOperations = (range, steps, onOrphan) => {
+    let current = range;
+    for (const step of steps) {
+        if (!current)
+            return null;
+        current = rebaseAnnotationRange(current, step.operation, step.positions, onOrphan);
+    }
+    return current;
+};
+/**
+ * Reference `MergeOrphanPolicy`: snap to the surviving node rather than
+ * drop (Phase 12a's decision - a comment on content that got merged into
+ * something else is still relevant to that content's new home; silently
+ * vanishing it loses data with no recovery path). Only applicable to a
+ * real `mergeNode` operation (`input.ts`'s cross-block Backspace/Delete
+ * text-merge) - unlike `mergedInto`/`retiredInto` above, `mergeNode`'s own
+ * shape has no explicit survivor field, so deriving it needs the actual
+ * document tree (the sibling immediately preceding the merge point,
+ * matching how `input.ts`'s `queueRangeDeletion` constructs the
+ * operation: `retiredId` is the right/consumed block, the left/absorbing
+ * block sits one offset earlier at the same parent). `positions` alone
+ * (an id-keyed lookup) can't answer "what's at this path" in the reverse
+ * direction, so this needs `document` explicitly, unlike every other
+ * function in this file.
+ *
+ * Table-cell-merge and list-item-merge don't need this - they always
+ * populate `mergedInto`/`retiredInto` themselves, so `rebaseAnnotationRange`
+ * snaps them unconditionally with no caller policy involved at all.
+ */
+export const defaultMergeOrphanPolicy = (document) => (range, operation) => {
+    const parent = nodeAtPath(document, operation.pos.path);
+    if (!parent || isTextNode(parent) || !parent.children)
+        return null;
+    const survivor = parent.children[operation.pos.offset - 1];
+    if (!survivor || isTextNode(survivor))
+        return null;
+    return rebaseThroughMergedRemove(range, operation.retiredId, survivor.id);
+};

package/dist/foundation/annotations/types.d.ts

@@ -0,0 +1,33 @@
+import type { SmartOperation } from "../types.js";
+import type { PositionLookup } from "../scope/types.js";
+/**
+ * A range anchored to node ids rather than a path/offset, so it survives
+ * structural edits elsewhere in the document without being carried through
+ * every transaction. Resolve it on demand via `resolveAnnotationRange`.
+ *
+ * An absent offset anchors to the whole node (its outer span) rather than a
+ * text position inside it. There is deliberately no `kind` discriminant yet
+ * (text range vs. whole-node anchor) - that is left for whichever phase
+ * first needs to distinguish them, so this primitive does not have to be
+ * retrofitted once real consumers exist.
+ */
+export interface AnnotationRange {
+    readonly startId: string;
+    readonly startOffset?: number;
+    readonly endId: string;
+    readonly endOffset?: number;
+}
+export type SplitNodeOperation = Extract<SmartOperation, {
+    type: "splitNode";
+}>;
+export type MergeNodeOperation = Extract<SmartOperation, {
+    type: "mergeNode";
+}>;
+/**
+ * Called when a merge retires a node id an AnnotationRange endpoint was
+ * anchored to. foundation/ has no opinion on whether the range should be
+ * dropped, snapped into the surviving node, or something else - comments and
+ * suggestions plausibly want different answers - so that decision is left
+ * entirely to the caller rather than baked into the primitive.
+ */
+export type MergeOrphanPolicy = (range: AnnotationRange, operation: MergeNodeOperation, positions: PositionLookup) => AnnotationRange | null;

package/dist/foundation/annotations/types.js

@@ -0,0 +1 @@
+export {};

package/dist/foundation/atom/commands.d.ts

@@ -0,0 +1,11 @@
+import type { AtomCommand, InsertAtomParams, ResizeAtomParams, UpdateAtomParams } from "./types.js";
+export declare const insertAtom: AtomCommand<InsertAtomParams>;
+export declare const updateAtom: AtomCommand<UpdateAtomParams>;
+export declare const deleteAtom: AtomCommand<Record<string, never>>;
+export declare const resizeAtom: AtomCommand<ResizeAtomParams>;
+export declare const atomCommands: {
+    readonly "atom.insert": AtomCommand<InsertAtomParams>;
+    readonly "atom.update": AtomCommand<UpdateAtomParams>;
+    readonly "atom.delete": AtomCommand<Record<string, never>>;
+    readonly "atom.resize": AtomCommand<ResizeAtomParams>;
+};

package/dist/foundation/atom/commands.js

@@ -0,0 +1,118 @@
+import { isTextNode } from "../identity.js";
+import { atomDeclarations } from "./declarations.js";
+const locate = (document, id, ctx) => {
+    const resolved = ctx.positions.positionOf(id);
+    if (!resolved)
+        return null;
+    if (resolved.kind === "inline") {
+        let inlineOffset = 0;
+        for (let index = 0; index < (resolved.parent.children?.length || 0); index += 1) {
+            const child = resolved.parent.children[index];
+            if (!isTextNode(child) && child.id === id && inlineOffset === resolved.pos.offset) {
+                return { node: child, pos: { path: [...resolved.pos.path], offset: index } };
+            }
+            inlineOffset += isTextNode(child) ? child.text.length : 1;
+        }
+        return null;
+    }
+    const node = resolved.parent.children?.[resolved.pos.offset];
+    if (!node || isTextNode(node) || node.id !== id)
+        return null;
+    return { node, pos: resolved.pos };
+};
+const cleanAttrs = (attrs) => Object.fromEntries(Object.entries(attrs).filter(([, value]) => value !== undefined));
+const inlineChildrenWithAtom = (owner, offset, atom) => {
+    if (!Number.isInteger(offset) || offset < 0)
+        return null;
+    const output = [];
+    let cursor = 0;
+    let inserted = false;
+    for (const child of owner.children || []) {
+        const width = isTextNode(child) ? child.text.length : 1;
+        if (!inserted && offset >= cursor && offset <= cursor + width) {
+            if (isTextNode(child)) {
+                const local = offset - cursor;
+                if (local)
+                    output.push({ ...child, text: child.text.slice(0, local) });
+                output.push(atom);
+                if (local < child.text.length)
+                    output.push({ ...child, text: child.text.slice(local) });
+            }
+            else {
+                if (offset === cursor)
+                    output.push(atom, child);
+                else if (offset === cursor + 1)
+                    output.push(child, atom);
+                else
+                    return null;
+            }
+            inserted = true;
+        }
+        else
+            output.push(child);
+        cursor += width;
+    }
+    if (!inserted && offset === cursor)
+        output.push(atom);
+    return inserted || offset === cursor ? output : null;
+};
+export const insertAtom = (document, _scope, params, ctx) => {
+    const attrs = cleanAttrs(params.attrs);
+    if (!params.declaration.validate(attrs))
+        return [];
+    const node = { type: params.declaration.type, id: params.nodeId, attrs };
+    if (params.declaration.group === "inline") {
+        if (!params.ownerId || params.offset === undefined)
+            return [];
+        const owner = locate(document, params.ownerId, ctx);
+        if (!owner)
+            return [];
+        const children = inlineChildrenWithAtom(owner.node, params.offset, node);
+        return children ? [{ type: "replaceNode", pos: owner.pos, before: owner.node, after: { ...owner.node, children } }] : [];
+    }
+    if (!params.parentId || params.index === undefined)
+        return [];
+    const range = ctx.positions.contentRangeOf(params.parentId);
+    const parentPosition = ctx.positions.positionOf(params.parentId);
+    const parent = parentPosition && parentPosition.parent.id === params.parentId
+        ? parentPosition.parent
+        : parentPosition?.parent.children?.[parentPosition.pos.offset];
+    if (!range || !parent || isTextNode(parent) || params.index < 0 || params.index > (parent.children?.length || 0))
+        return [];
+    return [{ type: "insertNode", pos: { path: [...range.from.path], offset: params.index }, node }];
+};
+const atomIds = (scope) => scope.kind === "atomic-node" ? [scope.nodeId]
+    : scope.kind === "mixed" ? scope.parts.flatMap(atomIds) : [];
+export const updateAtom = (document, scope, params, ctx) => atomIds(scope).flatMap((id) => {
+    const located = locate(document, id, ctx);
+    if (!located || ctx.schema.nodes[located.node.type]?.atomic !== true)
+        return [];
+    const after = cleanAttrs({ ...(located.node.attrs || {}), ...params.attrs });
+    const declaration = atomDeclarations.find((entry) => entry.type === located.node.type);
+    if (declaration && !declaration.validate(after))
+        return [];
+    return [{ type: "setNodeAttributes", pos: { path: [...located.pos.path, located.pos.offset], offset: 0 }, before: located.node.attrs || {}, after }];
+});
+export const deleteAtom = (document, scope, _params, ctx) => atomIds(scope).flatMap((id) => {
+    const located = locate(document, id, ctx);
+    return located && ctx.schema.nodes[located.node.type]?.atomic === true
+        ? [{ type: "removeNode", pos: located.pos, node: located.node }] : [];
+});
+export const resizeAtom = (document, scope, params, ctx) => {
+    const id = atomIds(scope)[0];
+    const located = id ? locate(document, id, ctx) : null;
+    if (!located)
+        return [];
+    const beforeWidth = Number(located.node.attrs?.width) || params.width;
+    const beforeHeight = Number(located.node.attrs?.height) || params.height;
+    const minWidth = Math.max(1, params.minWidth || 16);
+    const minHeight = Math.max(1, params.minHeight || 16);
+    let width = Math.max(minWidth, params.width);
+    let height = Math.max(minHeight, params.height);
+    if (params.preserveAspectRatio && beforeWidth > 0 && beforeHeight > 0)
+        height = width * beforeHeight / beforeWidth;
+    if (![width, height].every((value) => Number.isFinite(value) && value <= 100000))
+        return [];
+    return updateAtom(document, scope, { attrs: { width, height } }, ctx);
+};
+export const atomCommands = { "atom.insert": insertAtom, "atom.update": updateAtom, "atom.delete": deleteAtom, "atom.resize": resizeAtom };

package/dist/foundation/atom/composition.d.ts

@@ -0,0 +1,8 @@
+import type { SmartElementNode } from "../types.js";
+import type { CompositionToken } from "./types.js";
+/** Mapping-aware tokens: atoms occupy one opaque unit and are never flattened. */
+export declare const tokenizeCompositionOwner: (owner: SmartElementNode) => CompositionToken[];
+export declare const compositionSegmentAt: (tokens: readonly CompositionToken[], offset: number) => {
+    from: number;
+    to: number;
+};

package/dist/foundation/atom/composition.js

@@ -0,0 +1,22 @@
+import { isTextNode } from "../identity.js";
+/** Mapping-aware tokens: atoms occupy one opaque unit and are never flattened. */
+export const tokenizeCompositionOwner = (owner) => (owner.children || []).map((child) => isTextNode(child)
+    ? { kind: "text", text: child.text, marks: [...(child.marks || [])] }
+    : { kind: "atom", nodeId: child.id, atomType: child.type });
+export const compositionSegmentAt = (tokens, offset) => {
+    let cursor = 0;
+    for (const token of tokens) {
+        const width = token.kind === "atom" ? 1 : token.text.length;
+        if (token.kind === "atom" && (offset === cursor || offset === cursor + 1))
+            return { from: offset, to: offset };
+        cursor += width;
+    }
+    cursor = 0;
+    for (const token of tokens) {
+        const width = token.kind === "atom" ? 1 : token.text.length;
+        if (token.kind === "text" && offset >= cursor && offset <= cursor + width)
+            return { from: cursor, to: cursor + width };
+        cursor += width;
+    }
+    return { from: cursor, to: cursor };
+};

package/dist/foundation/atom/declarations.d.ts

@@ -0,0 +1,2 @@
+import type { AtomDeclaration } from "./types.js";
+export declare const atomDeclarations: readonly AtomDeclaration[];