smartrte-core 0.2.0 → 1.0.0-beta.1

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

@@ -0,0 +1,122 @@
+import type { ResolvedPos, SmartDocument, SmartMark, SmartNode, SmartRange, SmartSchema, SmartSelection } from "../types.js";
+export type ScopeRequest = {
+    want: "inline-range";
+} | {
+    want: "block-range";
+} | {
+    want: "container-tree";
+    stopAt?: (node: SmartNode) => boolean;
+} | {
+    want: "list-selection";
+} | {
+    want: "table-grid";
+} | {
+    want: "atomic-node";
+} | {
+    want: "describe";
+};
+export type ScopeKind = "inline-range" | "block-range" | "container-tree" | "list-selection" | "table-grid" | "atomic-node" | "mixed" | "empty";
+export interface ScopeBase {
+    kind: ScopeKind;
+    /** Normalized, direction-independent. Always from <= to. */
+    range: SmartRange;
+    /** Nearest isolating ancestor fully containing this scope, if any. */
+    isolatingAncestorId: string | null;
+    /** True when the request could not be satisfied exactly and was clamped. */
+    clamped: boolean;
+    /** Why it was clamped — isolating boundary, atom boundary, document edge. */
+    clampReason?: "isolating" | "atomic" | "document-edge" | "schema";
+}
+export interface InlineRun {
+    ownerNodeId: string;
+    from: number;
+    to: number;
+    containsAtoms: boolean;
+}
+export interface InlineRangeScope extends ScopeBase {
+    kind: "inline-range";
+    runs: InlineRun[];
+    collapsed: boolean;
+    storedMarkAnchor?: ResolvedPos;
+}
+export interface BlockRangeScope extends ScopeBase {
+    kind: "block-range";
+    blockIds: string[];
+    promotedFromPartial: boolean;
+    commonParentId: string | null;
+}
+export interface ContainerTreeScope extends ScopeBase {
+    kind: "container-tree";
+    rootId: string;
+    nodeIds: string[];
+    promotedFromPartial: boolean;
+}
+export interface ListSelectionScope extends ScopeBase {
+    kind: "list-selection";
+    listId: string;
+    items: {
+        itemId: string;
+        depth: number;
+        hasChildList: boolean;
+    }[];
+    partialSubtree: boolean;
+    promotedFromPartial: boolean;
+}
+export interface TableGridScope extends ScopeBase {
+    kind: "table-grid";
+    tableId: string;
+    rect: {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+    cellIds: string[];
+    coveredCellIds: string[];
+    rectangular: boolean;
+}
+export interface AtomicNodeScope extends ScopeBase {
+    kind: "atomic-node";
+    nodeId: string;
+    inline: boolean;
+}
+export interface MixedScope extends ScopeBase {
+    kind: "mixed";
+    parts: ResolvedScope[];
+}
+export interface EmptyScope extends ScopeBase {
+    kind: "empty";
+}
+export type ResolvedScope = InlineRangeScope | BlockRangeScope | ContainerTreeScope | ListSelectionScope | TableGridScope | AtomicNodeScope | MixedScope | EmptyScope;
+export interface SelectionDescription {
+    blockTypes: string[];
+    marks: {
+        mark: SmartMark;
+        coverage: "all" | "partial";
+    }[];
+    inList: {
+        listId: string;
+        depth: number;
+    } | null;
+    inTable: {
+        tableId: string;
+        cellId: string;
+    } | null;
+    isolatingAncestorId: string | null;
+    atoms: string[];
+    collapsed: boolean;
+    spansIsolatingBoundary: boolean;
+}
+export type ScopeResult = ResolvedScope | SelectionDescription;
+export interface PositionLookup {
+    positionOf(nodeId: string): ResolvedPos | null;
+    rangeOf(nodeId: string): SmartRange | null;
+    contentRangeOf(nodeId: string): SmartRange | null;
+    exists(nodeId: string): boolean;
+}
+export interface ScopeIndex {
+    resolve(document: SmartDocument, selection: SmartSelection, request: ScopeRequest, schema: SmartSchema): ScopeResult;
+    positions(document: SmartDocument, schema: SmartSchema): PositionLookup;
+    readonly liveNodeCount: number;
+}
+export type ResolveScope = (document: SmartDocument, selection: SmartSelection, request: ScopeRequest, schema: SmartSchema) => ScopeResult;

package/dist/foundation/scope/types.js

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

package/dist/foundation/security/urlPolicy.d.ts

@@ -0,0 +1,21 @@
+export interface SafeLinkAttrs {
+    href: string;
+    target?: string;
+}
+export type NormalizedLinkKind = "url" | "email" | "phone" | "anchor" | "invalid";
+export interface NormalizedLinkResult {
+    kind: NormalizedLinkKind;
+    href: string | null;
+    input: string;
+}
+export declare const normalizeLinkInput: (input: string | undefined | null) => NormalizedLinkResult;
+export declare const sanitizeLinkHref: (href: string | undefined | null) => string | null;
+export declare const sanitizeLinkTarget: (target: string | undefined) => string | undefined;
+export declare const sanitizeLinkAttrs: (input: {
+    href?: string;
+    target?: string;
+}) => SafeLinkAttrs | null;
+export declare const sanitizeResourceUrl: (input: string | undefined | null, options?: {
+    allowBlob?: boolean;
+    allowedDataMimeTypes?: ReadonlySet<string>;
+}) => string | null;

package/dist/foundation/security/urlPolicy.js

@@ -0,0 +1,75 @@
+const allowedProtocols = new Set(["http:", "https:", "mailto:", "tel:"]);
+const resourceProtocols = new Set(["http:", "https:"]);
+const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const bareDomainPattern = /^(?:www\.)?[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+(?:[/?#][^\s]*)?$/;
+const phonePattern = /^\+?[\d\s().-]{7,}$/;
+const normalizePhone = (value) => {
+    const hasLeadingPlus = value.trim().startsWith("+");
+    const digits = value.replace(/[^\d]/g, "");
+    if (digits.length < 7)
+        return null;
+    return `${hasLeadingPlus ? "+" : ""}${digits}`;
+};
+export const normalizeLinkInput = (input) => {
+    const trimmed = input?.trim() || "";
+    if (!trimmed)
+        return { kind: "invalid", href: null, input: "" };
+    if (/^mailto:/i.test(trimmed)) {
+        const email = trimmed.slice("mailto:".length).trim();
+        const href = emailPattern.test(email) ? `mailto:${email}` : null;
+        return { kind: href ? "email" : "invalid", href, input: trimmed };
+    }
+    if (/^tel:/i.test(trimmed)) {
+        const phone = normalizePhone(trimmed.slice("tel:".length));
+        const href = phone ? `tel:${phone}` : null;
+        return { kind: href ? "phone" : "invalid", href, input: trimmed };
+    }
+    if (emailPattern.test(trimmed))
+        return { kind: "email", href: `mailto:${trimmed}`, input: trimmed };
+    const phone = normalizePhone(trimmed);
+    if (phone && (trimmed.startsWith("+") || phonePattern.test(trimmed))) {
+        return { kind: "phone", href: `tel:${phone}`, input: trimmed };
+    }
+    if (/^#[A-Za-z][\w:.-]*$/.test(trimmed))
+        return { kind: "anchor", href: trimmed, input: trimmed };
+    if (bareDomainPattern.test(trimmed))
+        return { kind: "url", href: `https://${trimmed}`, input: trimmed };
+    try {
+        const parsed = new URL(trimmed);
+        const href = allowedProtocols.has(parsed.protocol) ? trimmed : null;
+        return { kind: href ? "url" : "invalid", href, input: trimmed };
+    }
+    catch {
+        return { kind: "invalid", href: null, input: trimmed };
+    }
+};
+export const sanitizeLinkHref = (href) => normalizeLinkInput(href).href;
+export const sanitizeLinkTarget = (target) => target?.trim() || undefined;
+export const sanitizeLinkAttrs = (input) => {
+    const href = sanitizeLinkHref(input.href);
+    return href ? { href, target: sanitizeLinkTarget(input.target) } : null;
+};
+export const sanitizeResourceUrl = (input, options = {}) => {
+    const value = input?.trim() || "";
+    if (!value || /[\u0000-\u001f\u007f]/.test(value))
+        return null;
+    if (/^(?:\/[^/]|\.\.?\/)/.test(value))
+        return value;
+    // A path-relative resource such as `images/photo.png` is valid persisted
+    // content. Reject anything that looks like a scheme so executable protocols
+    // cannot disguise themselves as relative paths.
+    if (!/^[A-Za-z][A-Za-z0-9+.-]*:/.test(value) && !value.startsWith("//") && !/\s/.test(value))
+        return value;
+    if (options.allowBlob && /^blob:/i.test(value))
+        return value;
+    const data = value.match(/^data:([^;,]+)(?:;[^,]*)?,/i);
+    if (data)
+        return options.allowedDataMimeTypes?.has(data[1].toLowerCase()) ? value : null;
+    try {
+        const parsed = new URL(value);
+        return resourceProtocols.has(parsed.protocol) ? value : null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/foundation/structural/contentTarget.d.ts

@@ -0,0 +1,21 @@
+import type { PositionLookup } from "../scope/types.js";
+import type { SmartDocument, SmartSchema } from "../types.js";
+export interface ContentTargetContext {
+    readonly schema: SmartSchema;
+    readonly positions: PositionLookup;
+}
+export interface ContentTargetLineageEntry {
+    readonly nodeId: string;
+    readonly type: string;
+}
+export interface ResolvedContentTarget {
+    readonly ownerId: string;
+    /** Target-subtree lineage, outermost first and including the owner. */
+    readonly lineage: readonly ContentTargetLineageEntry[];
+}
+/**
+ * Resolves the previous visible content owner in logical document order.
+ * It descends through the deepest last sibling subtree, climbs across parent
+ * boundaries when needed, and never crosses the nearest isolating ancestor.
+ */
+export declare const resolvePrecedingContentTarget: (document: SmartDocument, nodeId: string, ctx: ContentTargetContext) => ResolvedContentTarget | null;

package/dist/foundation/structural/contentTarget.js

@@ -0,0 +1,51 @@
+import { isTextNode } from "../identity.js";
+import { nodeAtPath } from "../positions.js";
+const isContentOwner = (node, schema) => {
+    const expression = schema.nodes[node.type]?.content || "";
+    return expression.includes("inline") || expression.includes("text");
+};
+const deepestLastContentOwner = (node, schema, lineage = []) => {
+    const nextLineage = [...lineage, { nodeId: node.id, type: node.type }];
+    for (let index = (node.children?.length || 0) - 1; index >= 0; index -= 1) {
+        const child = node.children?.[index];
+        if (!child || isTextNode(child))
+            continue;
+        const target = deepestLastContentOwner(child, schema, nextLineage);
+        if (target)
+            return target;
+    }
+    return isContentOwner(node, schema) ? { ownerId: node.id, lineage: nextLineage } : null;
+};
+const nearestIsolatingPath = (document, path, schema) => {
+    let result = [];
+    for (let depth = 0; depth <= path.length; depth += 1) {
+        const candidate = path.slice(0, depth);
+        const node = nodeAtPath(document, candidate);
+        if (node && !isTextNode(node) && schema.nodes[node.type]?.isolating)
+            result = candidate;
+    }
+    return result;
+};
+/**
+ * Resolves the previous visible content owner in logical document order.
+ * It descends through the deepest last sibling subtree, climbs across parent
+ * boundaries when needed, and never crosses the nearest isolating ancestor.
+ */
+export const resolvePrecedingContentTarget = (document, nodeId, ctx) => {
+    const located = ctx.positions.positionOf(nodeId);
+    if (!located)
+        return null;
+    let path = [...located.pos.path, located.pos.offset];
+    const isolationPath = nearestIsolatingPath(document, path, ctx.schema);
+    while (path.length > isolationPath.length) {
+        const parentPath = path.slice(0, -1);
+        const index = path[path.length - 1];
+        if (index > 0) {
+            const sibling = nodeAtPath(document, [...parentPath, index - 1]);
+            if (sibling && !isTextNode(sibling))
+                return deepestLastContentOwner(sibling, ctx.schema);
+        }
+        path = parentPath;
+    }
+    return null;
+};

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

@@ -0,0 +1,2 @@
+export * from "./contentTarget.js";
+export * from "./move.js";

package/dist/foundation/structural/index.js

@@ -0,0 +1,2 @@
+export * from "./contentTarget.js";
+export * from "./move.js";

package/dist/foundation/structural/move.d.ts

@@ -0,0 +1,7 @@
+import type { PositionLookup } from "../scope/types.js";
+import type { SmartOperation } from "../types.js";
+export interface SiblingMoveContext {
+    readonly positions: PositionLookup;
+}
+/** Shared implementation used by block.move and list.move. */
+export declare const moveContiguousSiblings: (nodeIds: readonly string[], direction: "up" | "down", ctx: SiblingMoveContext) => SmartOperation[];

package/dist/foundation/structural/move.js

@@ -0,0 +1,35 @@
+import { isTextNode } from "../identity.js";
+/** Shared implementation used by block.move and list.move. */
+export const moveContiguousSiblings = (nodeIds, direction, ctx) => {
+    const located = [...new Set(nodeIds)].map((nodeId) => {
+        const resolved = ctx.positions.positionOf(nodeId);
+        const node = resolved?.parent.children?.[resolved.pos.offset];
+        if (!resolved || !node || isTextNode(node) || node.id !== nodeId)
+            return null;
+        return { nodeId, parentId: resolved.parent.id, path: resolved.pos.path, index: resolved.pos.offset };
+    });
+    if (located.some((entry) => !entry))
+        return [];
+    const entries = located.filter((entry) => Boolean(entry))
+        .sort((left, right) => left.index - right.index);
+    if (!entries.length || entries.some((entry) => entry.parentId !== entries[0].parentId)
+        || entries.some((entry, index) => index > 0 && entry.index !== entries[index - 1].index + 1))
+        return [];
+    const first = entries[0].index;
+    const last = entries[entries.length - 1].index;
+    const parent = ctx.positions.positionOf(entries[0].nodeId).parent;
+    if (direction === "up") {
+        if (first === 0)
+            return [];
+        const preceding = parent.children?.[first - 1];
+        if (!preceding || isTextNode(preceding))
+            return [];
+        return [{ type: "moveNode", from: { path: [...entries[0].path], offset: first - 1 }, to: { path: [...entries[0].path], offset: last }, nodeId: preceding.id }];
+    }
+    if (last >= (parent.children?.length || 0) - 1)
+        return [];
+    const following = parent.children?.[last + 1];
+    if (!following || isTextNode(following))
+        return [];
+    return [{ type: "moveNode", from: { path: [...entries[0].path], offset: last + 1 }, to: { path: [...entries[0].path], offset: first }, nodeId: following.id }];
+};

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./inline.js";
+export * from "./structural.js";

package/dist/foundation/suggestions/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./inline.js";
+export * from "./structural.js";

package/dist/foundation/suggestions/inline.d.ts

@@ -0,0 +1,64 @@
+import type { MarkCommandContext } from "../marks/types.js";
+import type { ResolvedScope } from "../scope/types.js";
+import type { SmartDocument, SmartMark, SmartOperation, SmartPos, SmartRange } from "../types.js";
+import type { SuggestionKind } from "./types.js";
+export interface SuggestSpanParams {
+    readonly authorId: string;
+    readonly id?: string;
+    readonly createdAt?: number;
+}
+/**
+ * Builds a single insertText operation carrying a fresh "insert"-kind
+ * suggestion mark alongside whatever other marks the caller wants (e.g.
+ * storedMarks/bold). The text is inserted for real - track-changes mode
+ * means the document contains the real, live content immediately, tagged
+ * for later accept/reject, not a deferred change.
+ */
+export declare const suggestInsertOperation: (pos: SmartPos, text: string, params: SuggestSpanParams, extraMarks?: readonly SmartMark[]) => SmartOperation;
+/**
+ * Marks a selection's content with a "delete"-kind suggestion instead of
+ * actually deleting it - the content stays in the document (rendered
+ * struck-through) until the suggestion is accepted. Reuses
+ * applyMarkCommand directly: a suggestion mark is, mechanically, just
+ * another mark, so the existing per-owner range splitting/exclusion
+ * machinery already does exactly what's needed for a selection spanning
+ * multiple paragraphs.
+ */
+export declare const suggestDeleteCommand: (document: SmartDocument, scope: ResolvedScope, params: SuggestSpanParams, ctx: MarkCommandContext) => SmartOperation[];
+/**
+ * The single-range counterpart to suggestDeleteCommand, for a caller that
+ * already has a concrete single-owner SmartRange in hand (e.g. the input
+ * pipeline's ambient track-changes mode) and has no ResolvedScope to
+ * resolve - one addMark operation, no scope/positions machinery involved.
+ */
+export declare const suggestDeleteRangeOperation: (range: SmartRange, params: SuggestSpanParams) => SmartOperation;
+export interface SuggestionRun {
+    readonly ownerNodeId: string;
+    readonly range: SmartRange;
+    readonly mark: SmartMark;
+    readonly text: string;
+}
+/**
+ * Finds every contiguous run of text carrying a suggestion mark with the
+ * given id, anywhere in the document - not scoped to a caret position
+ * (unlike resolveMarkRun), since accept/reject is driven by a UI marker
+ * click, not necessarily a caret inside the run. A suggestion can in
+ * principle be split across owners by an intervening structural edit
+ * (rare), so this returns one entry per owner it's found in, not
+ * assuming a single contiguous span.
+ */
+export declare const findSuggestionRuns: (document: SmartDocument, id: string) => SuggestionRun[];
+/** Accept: "insert" runs keep their text (mark stripped); "delete" runs are actually removed. */
+export declare const acceptSuggestionCommand: (document: SmartDocument, id: string) => SmartOperation[];
+/** Reject: "insert" runs are removed (the proposed addition never happened); "delete" runs keep their text (mark stripped). */
+export declare const rejectSuggestionCommand: (document: SmartDocument, id: string) => SmartOperation[];
+export interface InlineSuggestionSummary {
+    readonly id: string;
+    readonly authorId: string;
+    readonly kind: SuggestionKind;
+    readonly createdAt: number;
+    /** Concatenation of every run's text sharing this id, in document order - a display preview, not authoritative content. */
+    readonly text: string;
+}
+/** One entry per distinct suggestion id found anywhere in the document - the panel-listing counterpart to findSuggestionRuns' by-id lookup. */
+export declare const listInlineSuggestions: (document: SmartDocument) => InlineSuggestionSummary[];

package/dist/foundation/suggestions/inline.js

@@ -0,0 +1,116 @@
+import { createNodeId, isTextNode } from "../identity.js";
+import { comparePos } from "../positions.js";
+import { applyMarkCommand } from "../marks/commands.js";
+const suggestionMark = (kind, params) => ({
+    type: "suggestion",
+    attrs: { id: params.id || createNodeId(), authorId: params.authorId, kind, createdAt: params.createdAt ?? Date.now() },
+});
+/**
+ * Builds a single insertText operation carrying a fresh "insert"-kind
+ * suggestion mark alongside whatever other marks the caller wants (e.g.
+ * storedMarks/bold). The text is inserted for real - track-changes mode
+ * means the document contains the real, live content immediately, tagged
+ * for later accept/reject, not a deferred change.
+ */
+export const suggestInsertOperation = (pos, text, params, extraMarks = []) => ({
+    type: "insertText",
+    pos,
+    text,
+    marks: [...extraMarks, suggestionMark("insert", params)],
+});
+/**
+ * Marks a selection's content with a "delete"-kind suggestion instead of
+ * actually deleting it - the content stays in the document (rendered
+ * struck-through) until the suggestion is accepted. Reuses
+ * applyMarkCommand directly: a suggestion mark is, mechanically, just
+ * another mark, so the existing per-owner range splitting/exclusion
+ * machinery already does exactly what's needed for a selection spanning
+ * multiple paragraphs.
+ */
+export const suggestDeleteCommand = (document, scope, params, ctx) => applyMarkCommand(document, scope, { markType: "suggestion", attrs: suggestionMark("delete", params).attrs }, ctx);
+/**
+ * The single-range counterpart to suggestDeleteCommand, for a caller that
+ * already has a concrete single-owner SmartRange in hand (e.g. the input
+ * pipeline's ambient track-changes mode) and has no ResolvedScope to
+ * resolve - one addMark operation, no scope/positions machinery involved.
+ */
+export const suggestDeleteRangeOperation = (range, params) => ({
+    type: "addMark", range, mark: suggestionMark("delete", params),
+});
+/**
+ * Finds every contiguous run of text carrying a suggestion mark with the
+ * given id, anywhere in the document - not scoped to a caret position
+ * (unlike resolveMarkRun), since accept/reject is driven by a UI marker
+ * click, not necessarily a caret inside the run. A suggestion can in
+ * principle be split across owners by an intervening structural edit
+ * (rare), so this returns one entry per owner it's found in, not
+ * assuming a single contiguous span.
+ */
+export const findSuggestionRuns = (document, id) => {
+    const runs = [];
+    const visit = (node, path) => {
+        if (isTextNode(node))
+            return;
+        const children = node.children || [];
+        if (children.some((child) => isTextNode(child))) {
+            let offset = 0;
+            let current = null;
+            const flush = (to) => {
+                if (current)
+                    runs.push({ ownerNodeId: node.id, range: { from: { path: [...path], offset: current.from }, to: { path: [...path], offset: to } }, mark: current.mark, text: current.text });
+                current = null;
+            };
+            children.forEach((child) => {
+                const width = isTextNode(child) ? child.text.length : 1;
+                const mark = isTextNode(child) ? child.marks?.find((candidate) => candidate.type === "suggestion" && candidate.attrs?.id === id) : undefined;
+                if (mark && isTextNode(child))
+                    current = current ? { ...current, text: current.text + child.text } : { from: offset, mark, text: child.text };
+                else
+                    flush(offset);
+                offset += width;
+            });
+            flush(offset);
+        }
+        children.forEach((child, index) => visit(child, [...path, index]));
+    };
+    visit(document, []);
+    return runs;
+};
+// deleteText ops targeting the same owner must run back-to-front, or an
+// earlier deletion shifts the offsets a later one still expects.
+const byDescendingPosition = (a, b) => -comparePos(a.range.from, b.range.from);
+/** Accept: "insert" runs keep their text (mark stripped); "delete" runs are actually removed. */
+export const acceptSuggestionCommand = (document, id) => [...findSuggestionRuns(document, id)].sort(byDescendingPosition).map((run) => run.mark.attrs?.kind === "delete"
+    ? { type: "deleteText", pos: run.range.from, text: run.text }
+    : { type: "removeMark", range: run.range, mark: run.mark });
+/** Reject: "insert" runs are removed (the proposed addition never happened); "delete" runs keep their text (mark stripped). */
+export const rejectSuggestionCommand = (document, id) => [...findSuggestionRuns(document, id)].sort(byDescendingPosition).map((run) => run.mark.attrs?.kind === "insert"
+    ? { type: "deleteText", pos: run.range.from, text: run.text }
+    : { type: "removeMark", range: run.range, mark: run.mark });
+/** One entry per distinct suggestion id found anywhere in the document - the panel-listing counterpart to findSuggestionRuns' by-id lookup. */
+export const listInlineSuggestions = (document) => {
+    const summaries = new Map();
+    const visit = (node) => {
+        if (isTextNode(node))
+            return;
+        (node.children || []).forEach((child) => {
+            if (isTextNode(child)) {
+                const mark = child.marks?.find((candidate) => candidate.type === "suggestion");
+                if (mark?.attrs) {
+                    const id = String(mark.attrs.id);
+                    const existing = summaries.get(id);
+                    summaries.set(id, {
+                        id,
+                        authorId: String(mark.attrs.authorId),
+                        kind: mark.attrs.kind,
+                        createdAt: Number(mark.attrs.createdAt),
+                        text: (existing?.text || "") + child.text,
+                    });
+                }
+            }
+            visit(child);
+        });
+    };
+    visit(document);
+    return [...summaries.values()];
+};

package/dist/foundation/suggestions/structural.d.ts

@@ -0,0 +1,40 @@
+import type { AnnotationRange } from "../annotations/types.js";
+import type { PositionLookup } from "../scope/types.js";
+import type { SmartDocument, SmartOperation, SmartSchema, SmartTransaction } from "../types.js";
+/**
+ * A proposed removal of a whole structural node (a paragraph, list item,
+ * table row, ...) - the AnnotationRange half of Phase 12a §2.3's hybrid
+ * architecture (2026-08-24 decision). Unlike an inline suggestion (a mark
+ * on real text, see inline.ts), the node stays exactly as it is in the
+ * live document until accepted - there is no equivalent "tag the node and
+ * insert it for real" mechanism for a *new* structural node yet (see the
+ * module-level limitation note below); only proposed removal is supported.
+ *
+ * `range` always anchors both endpoints to the same node id (a whole-node
+ * span, offsets undefined) - the exact same shape CommentMarkers/
+ * resolveAnnotationRange already render and rebase correctly for whole-
+ * node anchors.
+ */
+export interface StructuralSuggestion {
+    readonly id: string;
+    readonly authorId: string;
+    readonly kind: "removeNode";
+    readonly range: AnnotationRange;
+    readonly createdAt: number;
+}
+export declare const structuralSuggestionFromNode: (nodeId: string, authorId: string, opts?: {
+    readonly id?: string;
+    readonly createdAt?: number;
+}) => StructuralSuggestion;
+/** Accept: actually removes the node. No-op (empty operations) if it no longer resolves - already gone, nothing to do. */
+export declare const acceptStructuralSuggestionCommand: (document: SmartDocument, suggestion: StructuralSuggestion, positions: PositionLookup) => SmartOperation[];
+/**
+ * Replays a transaction's operations to keep every suggestion's range
+ * anchored, exactly mirroring comments/rebase.ts's
+ * rebaseCommentThreadsThroughTransaction (same reasoning: a fresh
+ * PositionLookup per operation, reference-identity preserved for untouched
+ * suggestions). Kept as a separate, structurally-parallel implementation
+ * rather than sharing code with comments/rebase.ts, to avoid touching that
+ * already-shipped, already-tested module for this.
+ */
+export declare const rebaseStructuralSuggestionsThroughTransaction: (suggestions: readonly StructuralSuggestion[], beforeDocument: SmartDocument, transaction: SmartTransaction, schema: SmartSchema) => readonly StructuralSuggestion[];

package/dist/foundation/suggestions/structural.js

@@ -0,0 +1,47 @@
+import { createNodeId } from "../identity.js";
+import { applyOperation } from "../operations.js";
+import { createScopeIndex } from "../scope/resolveScope.js";
+import { defaultMergeOrphanPolicy, rebaseAnnotationRange, resolveAnnotationRange } from "../annotations/range.js";
+export const structuralSuggestionFromNode = (nodeId, authorId, opts = {}) => ({
+    id: opts.id || createNodeId(),
+    authorId,
+    kind: "removeNode",
+    range: { startId: nodeId, endId: nodeId },
+    createdAt: opts.createdAt ?? Date.now(),
+});
+/** Accept: actually removes the node. No-op (empty operations) if it no longer resolves - already gone, nothing to do. */
+export const acceptStructuralSuggestionCommand = (document, suggestion, positions) => {
+    const resolvedRange = resolveAnnotationRange(suggestion.range, positions);
+    if (!resolvedRange)
+        return [];
+    const resolved = positions.positionOf(suggestion.range.startId);
+    const node = resolved?.parent.children?.[resolved.pos.offset];
+    if (!resolved || !node)
+        return [];
+    return [{ type: "removeNode", pos: resolved.pos, node }];
+};
+// Reject never touches the document - a proposed removal never removed
+// anything, so discarding the StructuralSuggestion record itself (a
+// caller/storage concern, not a core one) is the entire "reject" action.
+/**
+ * Replays a transaction's operations to keep every suggestion's range
+ * anchored, exactly mirroring comments/rebase.ts's
+ * rebaseCommentThreadsThroughTransaction (same reasoning: a fresh
+ * PositionLookup per operation, reference-identity preserved for untouched
+ * suggestions). Kept as a separate, structurally-parallel implementation
+ * rather than sharing code with comments/rebase.ts, to avoid touching that
+ * already-shipped, already-tested module for this.
+ */
+export const rebaseStructuralSuggestionsThroughTransaction = (suggestions, beforeDocument, transaction, schema) => {
+    if (!suggestions.length || !transaction.operations.length)
+        return suggestions;
+    let runningDocument = beforeDocument;
+    let ranges = suggestions.map((suggestion) => suggestion.range);
+    for (const operation of transaction.operations) {
+        const positions = createScopeIndex().positions(runningDocument, schema);
+        const onOrphan = (range, mergeOp, lookup) => defaultMergeOrphanPolicy(runningDocument)(range, mergeOp, lookup) ?? range;
+        ranges = ranges.map((range) => rebaseAnnotationRange(range, operation, positions, onOrphan) ?? range);
+        runningDocument = applyOperation(runningDocument, operation);
+    }
+    return suggestions.map((suggestion, index) => ranges[index] === suggestion.range ? suggestion : { ...suggestion, range: ranges[index] });
+};

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

@@ -0,0 +1,19 @@
+export type SuggestionKind = "insert" | "delete";
+/**
+ * Attrs carried on the "suggestion" text mark (Phase 12a §2.3, hybrid
+ * architecture per user decision 2026-08-24): an inline suggestion is real
+ * content in the live document, tagged the same way bold/italic/link are,
+ * rather than a separate not-yet-applied proposal. "insert" marks text that
+ * was actually inserted, pending acceptance; "delete" marks text that is
+ * still present but proposed for removal. This is deliberately NOT a
+ * separate SuggestionThread-style out-of-band record the way CommentThread
+ * is - reusing the marks pipeline means split/merge/undo/rendering all
+ * already work for free (see marks/dom.ts, operations.ts's generic mark
+ * carry-through).
+ */
+export interface SuggestionMarkAttrs {
+    readonly id: string;
+    readonly authorId: string;
+    readonly kind: SuggestionKind;
+    readonly createdAt: number;
+}

package/dist/foundation/suggestions/types.js

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

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { createSubtreeRenderer, FoundationSubtreeRenderer } from "./renderer.js";
+export { createInputPipeline, FoundationInputPipeline } from "./input.js";