@lax-wp/editor 0.4.15 → 0.4.16

package/dist/extensions/redline/review/nodeResolvers.d.ts

@@ -0,0 +1,29 @@
+import type { Editor } from '@tiptap/core';
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+import type { RedlineChange } from '../changeTypes';
+/**
+ * Per-node-type review resolvers (change-tracking.md M3 — accept/reject
+ * semantics per encoding).
+ *
+ * Each resolver receives the shared ResolveContext (one transaction per
+ * change) and returns:
+ * - `true` / `false`  — the change was handled (dispatched or not),
+ * - `'fallthrough'`   — the target node could not be located; control
+ *   continues to later resolvers and ultimately the text path, exactly
+ *   matching the legacy if-chain's fall-through behavior.
+ */
+export interface ResolveContext {
+    editor: Editor;
+    state: EditorState;
+    tr: Transaction;
+    dispatchWithSkipMeta: () => void;
+}
+export type ResolveResult = boolean | 'fallthrough';
+export declare const resolveImageChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveDividerChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveTableRowChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveTableColumnChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveTableChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveSignatureChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveBlockquoteChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+export declare const resolveVariableChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;

package/dist/extensions/redline/review/pairedNodes.d.ts

@@ -0,0 +1,38 @@
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+/**
+ * Paired-node resolution (change-tracking.md M3.6 — atomicity).
+ *
+ * When a gesture deletes/pastes block nodes together with text, the nodes
+ * share the text change's mark id (see engine/blockNodes and the paste
+ * batch). Resolving that text change must resolve the paired nodes in the
+ * SAME transaction, mapping positions through earlier edits.
+ *
+ * Four node kinds use the `redline*` attribute scheme and identical action
+ * semantics, differing only in their "insert" action name and which extra
+ * attrs get cleared — previously four copy-pasted blocks, now one function:
+ *
+ * | node           | insert action | extra cleared attr   |
+ * |----------------|---------------|----------------------|
+ * | horizontalRule | 'insert'      | redlineGroupId       |
+ * | image          | 'insert'      | redlinePriorAction   |
+ * | signature      | 'add'         | redlinePriorAction   |
+ * | variableText   | 'add'         | redlinePriorAction   |
+ *
+ * Tables use the `data-redline-*` scheme with type-based (not action-based)
+ * semantics and keep their own resolver.
+ */
+interface PlainAttrNodeSpec {
+    nodeName: string;
+    insertAction: 'insert' | 'add';
+    /** Extra attribute keys cleared alongside the shared redline* identity attrs. */
+    extraClearKeys: string[];
+}
+export declare const PAIRED_PLAIN_ATTR_NODES: PlainAttrNodeSpec[];
+export declare function resolvePairedPlainAttrNodes(state: EditorState, tr: Transaction, targetMarkIds: Set<string>, operation: 'accept' | 'reject', spec: PlainAttrNodeSpec): void;
+/**
+ * Tables deleted in the same selection as text share its mark id via
+ * `data-redline-id`; semantics are type-based (insertion vs deletion type)
+ * with `data-redline-prior-type` remembering an overlaid same-user insertion.
+ */
+export declare function resolvePairedTables(state: EditorState, tr: Transaction, targetMarkIds: Set<string>, operation: 'accept' | 'reject'): void;
+export {};

package/dist/extensions/redline/review/structuralRevert.d.ts

@@ -0,0 +1,20 @@
+import type { Editor } from '@tiptap/core';
+/**
+ * Structural-revert helpers (change-tracking.md M3 — reject semantics for
+ * node-level formats).
+ *
+ * Rejecting a format-change suggestion must physically restore the previous
+ * structure, which for lists/headings/alignment/blockquotes/indent cannot be
+ * done with mark operations alone — the recorded editor commands are re-run
+ * with the skip meta so the revert itself is not tracked as a new change.
+ */
+export type TrackedListState = 'none' | 'task' | `bullet:${string}` | `ordered:${string}`;
+export type TrackedHeadingState = 'paragraph' | `h${1 | 2 | 3 | 4 | 5 | 6}`;
+export type TrackedTextAlignState = 'left' | 'center' | 'right' | 'justify';
+export type TrackedBlockquoteState = boolean;
+export declare const applyTrackedListState: (editor: Editor, from: number, to: number, targetState: TrackedListState) => void;
+export declare const applyTrackedHeadingState: (editor: Editor, from: number, to: number, targetState: TrackedHeadingState) => void;
+export declare const applyTrackedTextAlignState: (editor: Editor, from: number, to: number, targetState: TrackedTextAlignState) => void;
+export declare const applyTrackedMarkerFontSizeState: (editor: Editor, from: number, to: number, targetState: string | null) => void;
+export declare const applyTrackedBlockquoteState: (editor: Editor, from: number, to: number, targetState: TrackedBlockquoteState) => void;
+export declare const applyTrackedIndentState: (editor: Editor, from: number, to: number, targetIndent: number) => void;

package/dist/extensions/redline/review/textResolver.d.ts

@@ -0,0 +1,9 @@
+import type { RedlineChange } from '../changeTypes';
+import type { ResolveContext, ResolveResult } from './nodeResolvers';
+export declare const resolveLinkChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => ResolveResult;
+/**
+ * Handles format-change and plain insertion/deletion marks, then resolves
+ * paired block nodes sharing the same mark id. This is the final resolver —
+ * it always returns a boolean.
+ */
+export declare const resolveTextChange: (ctx: ResolveContext, change: RedlineChange, operation: "accept" | "reject") => boolean;

package/dist/extensions/redline/schema/marks.d.ts

@@ -0,0 +1,65 @@
+import { Mark } from '@tiptap/core';
+import { type RedlineBaseAttributes, type RedlineExtendedAttributes } from './shared';
+/**
+ * Redline inline marks (change-tracking.md M0.1).
+ *
+ * Two shapes, one insertion/deletion pair per authoring mode:
+ *
+ * - insertion marks carry the extended attribute set (formatChanges,
+ *   linkData, groupId) and derive their class/tooltip via
+ *   getRedlineInsertionPresentation,
+ * - deletion marks carry only the base identity attributes and a static
+ *   class; all visual treatment (strikethrough/colors) comes from the
+ *   decoration CSS, never inline styles.
+ *
+ * All marks are `inclusive: false`: typing at a mark edge must not silently
+ * extend someone's suggestion — extension is an explicit engine decision
+ * (adjacency/typing-session grouping in the tracking engine).
+ */
+export interface RedlineMarkOptions {
+    HTMLAttributes: Record<string, string>;
+}
+export type UserInsertionAttributes = RedlineExtendedAttributes;
+export type AIInsertionAttributes = RedlineExtendedAttributes;
+export type UserDeletionAttributes = RedlineBaseAttributes;
+export type AIDeletionAttributes = RedlineBaseAttributes;
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        userInsertion: {
+            /** Set user insertion mark */
+            setUserInsertion: (attributes: UserInsertionAttributes) => ReturnType;
+            /** Toggle user insertion mark */
+            toggleUserInsertion: (attributes: UserInsertionAttributes) => ReturnType;
+            /** Unset user insertion mark */
+            unsetUserInsertion: () => ReturnType;
+        };
+        userDeletion: {
+            /** Set user deletion mark */
+            setUserDeletion: (attributes: UserDeletionAttributes) => ReturnType;
+            /** Toggle user deletion mark */
+            toggleUserDeletion: (attributes: UserDeletionAttributes) => ReturnType;
+            /** Unset user deletion mark */
+            unsetUserDeletion: () => ReturnType;
+        };
+        aiInsertion: {
+            /** Set AI insertion mark */
+            setAIInsertion: (attributes: AIInsertionAttributes) => ReturnType;
+            /** Toggle AI insertion mark */
+            toggleAIInsertion: (attributes: AIInsertionAttributes) => ReturnType;
+            /** Unset AI insertion mark */
+            unsetAIInsertion: () => ReturnType;
+        };
+        aiDeletion: {
+            /** Set AI deletion mark */
+            setAIDeletion: (attributes: AIDeletionAttributes) => ReturnType;
+            /** Toggle AI deletion mark */
+            toggleAIDeletion: (attributes: AIDeletionAttributes) => ReturnType;
+            /** Unset AI deletion mark */
+            unsetAIDeletion: () => ReturnType;
+        };
+    }
+}
+export declare const UserInsertion: Mark<RedlineMarkOptions, any>;
+export declare const AIInsertion: Mark<RedlineMarkOptions, any>;
+export declare const UserDeletion: Mark<RedlineMarkOptions, any>;
+export declare const AIDeletion: Mark<RedlineMarkOptions, any>;

package/dist/extensions/redline/schema/shared.d.ts

@@ -0,0 +1,34 @@
+import type { Attribute } from '@tiptap/core';
+export interface RedlineBaseAttributes {
+    id: string;
+    userId: string;
+    userName: string;
+    timestamp: string;
+}
+export interface RedlineExtendedAttributes extends RedlineBaseAttributes {
+    formatChanges?: string;
+    linkData?: string;
+}
+export declare const createRedlineBaseAttributes: (includeExtendedFields?: boolean) => Record<string, Attribute>;
+export declare const getRedlineInsertionPresentation: (htmlAttributes: Record<string, unknown>, baseClassName: string, regularColor: string) => {
+    title?: string | undefined;
+    style: string;
+    className: string;
+};
+export declare const createRedlineMarkCommands: <TAttributes>(markName: string) => {
+    setMarkCommand: (attributes: TAttributes) => ({ commands }: {
+        commands: {
+            setMark: (name: string, attrs: TAttributes) => boolean;
+        };
+    }) => boolean;
+    toggleMarkCommand: (attributes: TAttributes) => ({ commands }: {
+        commands: {
+            toggleMark: (name: string, attrs: TAttributes) => boolean;
+        };
+    }) => boolean;
+    unsetMarkCommand: () => ({ commands }: {
+        commands: {
+            unsetMark: (name: string) => boolean;
+        };
+    }) => boolean;
+};

package/dist/extensions/redline/session.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Redline session state (change-tracking.md M1/M2 — engine context).
+ *
+ * The tracking engine spans several cooperating ProseMirror plugins (keymap,
+ * input props, appendTransaction trackers) that must agree on batch identity
+ * within one synchronous editing gesture:
+ *
+ * - paste batch    — one mark id per paste so text + dividers + images pasted
+ *                    together appear as a single panel card,
+ * - deletion batch — one mark id per Backspace/Delete gesture so dividers
+ *                    removed together with text share the text's card,
+ * - typing session — cross-block grouping (Docs model): typing + Enter +
+ *                    typing stays one card until the cursor navigates away,
+ * - pending list format — a list toggled on an EMPTY paragraph has no text
+ *                    range to mark yet; the intent is parked here and merged
+ *                    into the next insertion so the panel shows
+ *                    "Add List Item" instead of plain "Add".
+ *
+ * Batches are deliberately cleared on the next macrotask (setTimeout 0):
+ * every appendTransaction triggered by the same gesture runs synchronously,
+ * so "this tick" is exactly the batch boundary.
+ *
+ * Previously this state was spread across module-level singletons
+ * (redlineSharedMeta.ts) and factory closures; it is now one object owned by
+ * the Redline extension and passed explicitly to the engine functions.
+ */
+export interface BatchState {
+    activeMarkId: string | null;
+    activeTimestamp: string | null;
+}
+export interface PendingListFormat {
+    listOld: string | null;
+    listNew: string | null;
+    userId: string | null;
+    userName: string | null;
+    mode: 'user' | 'ai' | null;
+}
+export declare class RedlineSession {
+    /** Shared mark identity for the current paste gesture. */
+    readonly pasteBatch: BatchState;
+    /** Shared mark identity for the current keyboard-deletion gesture. */
+    readonly deletionBatch: BatchState;
+    /** Cross-block typing session (cleared on pure cursor navigation). */
+    typingSessionMarkId: string | null;
+    typingSessionUserId: string | null;
+    /** List activation on an empty paragraph, awaiting the first insertion. */
+    readonly pendingListFormat: PendingListFormat;
+    private pasteTimeout;
+    /** Opens a paste batch for the current tick; auto-clears next macrotask. */
+    beginPasteBatch(markId: string, timestamp: string): void;
+    /** Opens a deletion batch for the current tick; auto-clears next macrotask. */
+    beginDeletionBatch(markId: string, timestamp: string): void;
+    setTypingSession(markId: string, userId: string): void;
+    /** Called by the view plugin on pure cursor navigation (selection moved,
+     *  doc unchanged): ends the cross-block typing session and abandons any
+     *  pending list format the user navigated away from. */
+    endTypingSession(): void;
+    setPendingListFormat(update: PendingListFormat): void;
+    clearPendingListFormat(): void;
+}
+/**
+ * The shared session instance.
+ *
+ * A single module-level instance (not per-extension) mirrors the legacy
+ * contract exactly: tracker plugins constructed in different factories must
+ * observe the same batch state within a gesture. The editor is a singleton
+ * per package consumer, so this is safe in practice; tests that need
+ * isolation can call `resetRedlineSession()`.
+ */
+export declare const redlineSession: RedlineSession;
+export declare const resetRedlineSession: () => void;

package/dist/extensions/redline/types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared types for the redline (track changes) system.
+ */
+/** Entity performing the change (user or AI). */
+export interface RedlineEntity {
+    id: string;
+    name: string;
+}
+export type RedlineMode = 'user' | 'ai';
+/** Configuration options for the Redline extension. */
+export interface RedlineOptions {
+    isActive: boolean;
+    mode: RedlineMode;
+    currentEntity: RedlineEntity;
+}
+/**
+ * Runtime tracking context resolved per keystroke/transaction: the live
+ * enabled/mode toggle plus the identity to attribute changes to.
+ */
+export interface RedlineContext {
+    isActive: boolean;
+    mode: RedlineMode;
+    entity: RedlineEntity;
+}

package/dist/extensions/trackedChanges/TrackedChanges.d.ts

@@ -0,0 +1,64 @@
+import { Extension } from '@tiptap/core';
+import { type TrackedChangesShared } from './plugin';
+import type { Suggestion, SuggestionEventHandler, SuggestionFilter, SuggestionUserMetadata, UntrackedOperationHandler } from './types';
+export interface TrackedChangesOptions {
+    /** Start with suggest mode on. */
+    enabled: boolean;
+    /** Author attributed on new suggestions (M9 identity binding). */
+    userId: string;
+    /** Display metadata stored with every mark (name, color…). */
+    userMetadata: SuggestionUserMetadata;
+    /** Fired on suggestion create/update/accept/reject, local and remote (M4.3). */
+    onSuggestionEvent?: SuggestionEventHandler;
+    /** Fired with the full suggestion list whenever it changes (feeds the M7 store). */
+    onSuggestionsChange?: (suggestions: Suggestion[]) => void;
+    /** Fired when an operation is blocked or passes through untracked (5.3/5.8) — show a toast. */
+    onUntrackedOperation?: UntrackedOperationHandler;
+}
+export interface TrackedChangesStorage {
+    enabled: boolean;
+    userId: string;
+    userMetadata: SuggestionUserMetadata;
+    shared: TrackedChangesShared;
+    /** Query API over the plugin-state index (M4). */
+    getSuggestions: () => Suggestion[];
+    on: (handler: SuggestionEventHandler) => void;
+    off: (handler: SuggestionEventHandler) => void;
+    /** @internal */
+    handlers: Set<SuggestionEventHandler>;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        trackedChanges: {
+            /** Turn suggest mode on (M4.4). */
+            enableSuggesting: () => ReturnType;
+            /** Turn suggest mode off. */
+            disableSuggesting: () => ReturnType;
+            toggleSuggesting: () => ReturnType;
+            /** Bind the identity attributed on new suggestions (M5: call on auth changes). */
+            setSuggestionUser: (user: {
+                userId: string;
+                userMetadata?: SuggestionUserMetadata;
+            }) => ReturnType;
+            /** Accept one suggestion by id ("acceptSuggestion" is taken by AI autocompletion). */
+            acceptTrackedChange: (id: string) => ReturnType;
+            /** Reject one suggestion by id. */
+            rejectTrackedChange: (id: string) => ReturnType;
+            /** Accept every suggestion, optionally filtered by user or ids (M3.5). */
+            acceptAllTrackedChanges: (filter?: SuggestionFilter) => ReturnType;
+            /** Reject every suggestion, optionally filtered by user or ids (M3.5). */
+            rejectAllTrackedChanges: (filter?: SuggestionFilter) => ReturnType;
+            /** Move the selection to a suggestion and scroll it into view. */
+            goToSuggestion: (id: string) => ReturnType;
+        };
+    }
+}
+/**
+ * Tracked Changes — our own suggest-mode extension (change-tracking.md v2).
+ *
+ * Packages M0 (schema marks), M1 (tracking engine), M2 (input behavior),
+ * M3 (review engine) and M4 (query/events/commands) as one Tiptap extension.
+ * Suggestions live entirely inside the document as marks, so Yjs sync and
+ * persistence handle replication and storage for free (D1).
+ */
+export declare const TrackedChanges: Extension<TrackedChangesOptions, TrackedChangesStorage>;

package/dist/extensions/trackedChanges/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tracked Changes — shared constants (see change-tracking.md, M0/M1).
+ */
+/** Mark names (M0.1). */
+export declare const INSERTION_MARK_NAME = "insertion";
+export declare const DELETION_MARK_NAME = "deletion";
+export declare const MODIFICATION_MARK_NAME = "modification";
+export declare const SUGGESTION_MARK_NAMES: readonly ["insertion", "deletion", "modification"];
+/**
+ * Transaction meta key. Values:
+ *  - 'track'     — a transaction the engine rewrote (never re-process)
+ *  - 'normalize' — merge/cleanup pass from appendTransaction
+ *  - 'resolve'   — an accept/reject transaction from the review engine
+ */
+export declare const TRACKED_CHANGES_META = "trackedChanges$";
+/** Current encoding version, stamped on every mark (M0, edge case 5.7). */
+export declare const SUGGESTION_SCHEMA_VERSION = 1;
+/** DOM data attributes emitted by renderHTML (M0.1). */
+export declare const DATA_SUGGESTION_ID = "data-suggestion-id";
+export declare const DATA_SUGGESTION_USER = "data-suggestion-user";
+export declare const DATA_SUGGESTION_TYPE = "data-type";
+export declare const DATA_SUGGESTION_CREATED_AT = "data-suggestion-created-at";
+export declare const DATA_SUGGESTION_USER_METADATA = "data-suggestion-user-metadata";
+export declare const DATA_SUGGESTION_SCHEMA_VERSION = "data-suggestion-schema-version";
+/** Extra attributes for the `modification` mark (M0.1). */
+export declare const DATA_MODIFICATION_MARK_NAME = "data-modification-mark-name";
+export declare const DATA_MODIFICATION_ACTION = "data-modification-action";
+export declare const DATA_MODIFICATION_PREVIOUS_ATTRS = "data-modification-previous-attrs";
+export declare const DATA_MODIFICATION_NEW_ATTRS = "data-modification-new-attrs";
+/** Metas of other plugins whose transactions must never be rewritten (M1.3). */
+export declare const YJS_SYNC_META = "y-sync$";
+export declare const YJS_UNDO_META = "y-undo$";
+export declare const PM_HISTORY_META = "history$";
+export declare const COMPOSITION_META = "composition";

package/dist/extensions/trackedChanges/engine.d.ts

@@ -0,0 +1,32 @@
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+import type { SuggestionUserMetadata, UntrackedOperationHandler } from './types';
+/**
+ * M1 — Tracking Engine.
+ *
+ * `rewriteTransaction` receives a would-be-dispatched local transaction and
+ * rebuilds it per the step-rewriting semantics table in change-tracking.md so
+ * that nothing is ever really deleted and everything added is attributed.
+ * It is a pure function over (state, tr) so it is unit-testable without a view.
+ */
+export interface TrackContext {
+    userId: string;
+    userMetadata: SuggestionUserMetadata;
+    /** Timestamp stamped on new suggestion marks. */
+    now: number;
+    /** Which way the caret should walk after a rewritten deletion (M2.2). */
+    deleteDirection?: 'backward' | 'forward';
+    /** Notified when an operation is blocked or passed through untracked (5.3/5.8). */
+    onUntracked?: UntrackedOperationHandler;
+}
+/**
+ * M1.3 — exemption guards. Transactions that must pass through untouched:
+ * remote Yjs sync, undo/redo, history-excluded, our own rewrites, IME
+ * composition (rewriting mid-composition corrupts IME input — edge case 5.1).
+ */
+export declare function isExemptTransaction(tr: Transaction, composing?: boolean): boolean;
+/**
+ * Rebuild `tr` as a tracked transaction. Every step's coordinates are mapped
+ * from its own doc into the rebuilt transaction's doc via the inverted
+ * original mapping composed with our own mapping (M1.5).
+ */
+export declare function rewriteTransaction(state: EditorState, tr: Transaction, ctx: TrackContext): Transaction;

package/dist/extensions/trackedChanges/index.d.ts

@@ -0,0 +1,13 @@
+export { TrackedChanges } from './TrackedChanges';
+export type { TrackedChangesOptions, TrackedChangesStorage } from './TrackedChanges';
+export { InsertionMark, DeletionMark, ModificationMark } from './marks';
+export { findSuggestions } from './query';
+export { resolveSuggestions } from './review';
+export type { ResolveAction } from './review';
+export { rewriteTransaction, isExemptTransaction } from './engine';
+export type { TrackContext } from './engine';
+export { trackedChangesPluginKey } from './plugin';
+export type { TrackedChangesPluginState } from './plugin';
+export * from './types';
+export { INSERTION_MARK_NAME, DELETION_MARK_NAME, MODIFICATION_MARK_NAME, TRACKED_CHANGES_META, SUGGESTION_SCHEMA_VERSION, } from './constants';
+export { suggestionColorForUser } from './utils';

package/dist/extensions/trackedChanges/marks.d.ts

@@ -0,0 +1,20 @@
+import { Mark } from '@tiptap/core';
+/**
+ * `insertion` — proposed new content (M0.1).
+ * `inclusive: true` so continued typing at the edge extends the author's own
+ * insertion (edge case 5.5); the engine re-attributes other users' typing.
+ */
+export declare const InsertionMark: Mark<any, any>;
+/**
+ * `deletion` — content proposed for removal; it stays in the document with a
+ * strikethrough (M0.1). `inclusive: false` so typing at the edge never silently
+ * extends someone's deletion (edge case 5.5).
+ */
+export declare const DeletionMark: Mark<any, any>;
+/**
+ * `modification` — a proposed formatting change (Tier 2, M0.1). The real
+ * formatting is *not* applied until accept; the mark records exactly what to
+ * apply (`markName`, `action`, `previousAttrs`, `newAttrs`).
+ * `excludes: ''` lets several pending format changes stack on the same text.
+ */
+export declare const ModificationMark: Mark<any, any>;

package/dist/extensions/trackedChanges/normalize.d.ts

@@ -0,0 +1,2 @@
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+export declare function createNormalizeTransaction(state: EditorState): Transaction | null;

package/dist/extensions/trackedChanges/plugin.d.ts

@@ -0,0 +1,32 @@
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+import type { ResolveMeta } from './review';
+import type { Suggestion, SuggestionEvent } from './types';
+/**
+ * M2 (input behavior) + M4.2/M4.3 (plugin-state suggestion index + events),
+ * as one ProseMirror plugin owned by the TrackedChanges extension.
+ */
+export interface TrackedChangesPluginState {
+    suggestions: Map<string, Suggestion>;
+    /** Present when the last transaction was an accept/reject (M3.7). */
+    lastResolve: ResolveMeta | null;
+    /** True when the last doc change arrived via Yjs sync. */
+    lastChangeWasRemote: boolean;
+}
+export interface TrackedChangesShared {
+    /** Set by handleKeyDown so the engine knows which way the caret walks (M2.2). */
+    deleteDirection: 'backward' | 'forward' | null;
+    /** Selection anchor recorded at compositionstart for IME reconciliation (M2.4). */
+    compositionStart: number | null;
+}
+export interface TrackedChangesPluginDeps {
+    isEnabled: () => boolean;
+    getUser: () => {
+        userId: string;
+        userMetadata: Record<string, unknown> | null;
+    };
+    emit: (event: SuggestionEvent) => void;
+    onSuggestionsChange?: (suggestions: Suggestion[]) => void;
+    shared: TrackedChangesShared;
+}
+export declare const trackedChangesPluginKey: PluginKey<TrackedChangesPluginState>;
+export declare function createTrackedChangesPlugin(deps: TrackedChangesPluginDeps): Plugin;

package/dist/extensions/trackedChanges/query.d.ts

@@ -0,0 +1,3 @@
+import type { Node as PMNode } from '@tiptap/pm/model';
+import type { Suggestion } from './types';
+export declare function findSuggestions(doc: PMNode): Suggestion[];

package/dist/extensions/trackedChanges/review.d.ts

@@ -0,0 +1,34 @@
+import type { EditorState, Transaction } from '@tiptap/pm/state';
+import type { SuggestionFilter } from './types';
+/**
+ * M3 — Review Engine. Accept/reject as pure document transforms.
+ *
+ * Accept:  insertion → unmark (content becomes real); deletion → really delete;
+ *          modification → apply the recorded change, drop the mark.
+ * Reject:  exact inverse — insertion → delete the content; deletion → unmark;
+ *          modification → discard (the change was never applied, so the text
+ *          already carries `previousAttrs`).
+ *
+ * Nested/stacked truth table (M3.4) falls out of op ordering below:
+ *  - Reject an insertion carrying a stacked deletion → the content is deleted,
+ *    so both vanish (the substrate is gone).
+ *  - Accept an insertion carrying a stacked deletion → only the insertion mark
+ *    is removed; the deletion suggestion survives on now-real content.
+ *  - Accept a deletion stacked on someone's insertion → the content is deleted;
+ *    the insertion suggestion is consumed with it.
+ */
+export type ResolveAction = 'accept' | 'reject';
+export interface ResolveMeta {
+    kind: 'resolve';
+    action: ResolveAction;
+    ids: string[];
+}
+export interface ResolveTarget extends SuggestionFilter {
+    all?: boolean;
+}
+/**
+ * Resolve every suggestion matched by `target` into the provided transaction
+ * (M3.5: bulk operations are one transaction — one undo step, one Yjs update).
+ * Returns false when nothing matched.
+ */
+export declare function resolveSuggestions(state: EditorState, tr: Transaction, target: ResolveTarget, action: ResolveAction): boolean;

package/dist/extensions/trackedChanges/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Tracked Changes — public types (change-tracking.md M4).
+ */
+/** Suggestion type surfaced by the query API (M4.1). */
+export type SuggestionType = 'add' | 'delete' | 'replace' | 'markChange';
+export type SuggestionMarkKind = 'insertion' | 'deletion' | 'modification';
+/** Arbitrary per-user display metadata carried on every mark (name, color, avatar…). */
+export type SuggestionUserMetadata = Record<string, unknown> | null;
+/** Attributes shared by all three suggestion marks (M0.1). */
+export interface SuggestionMarkAttrs {
+    id: string | null;
+    userId: string | null;
+    createdAt: number | null;
+    userMetadata: SuggestionUserMetadata;
+    schemaVersion: number;
+}
+/** Extra attributes carried by the `modification` mark (M0.1). */
+export interface ModificationMarkAttrs extends SuggestionMarkAttrs {
+    /** The formatting mark this suggestion proposes to add/remove (e.g. 'bold', 'link'). */
+    markName: string | null;
+    action: 'add' | 'remove' | null;
+    /** Attrs of the pre-existing same-type mark (so reject/accept can restore an exact href). */
+    previousAttrs: Record<string, unknown> | null;
+    newAttrs: Record<string, unknown> | null;
+}
+/** One contiguous document range carrying a suggestion mark. */
+export interface SuggestionRange {
+    from: number;
+    to: number;
+    markKind: SuggestionMarkKind;
+}
+/** A suggestion as returned by the query API (M4.1). */
+export interface Suggestion {
+    id: string;
+    type: SuggestionType;
+    userId: string | null;
+    userMetadata: SuggestionUserMetadata;
+    createdAt: number | null;
+    ranges: SuggestionRange[];
+    /** Text excluding content contributed by *nested* suggestions of other users. */
+    text: string;
+    /** The literal text of every range. */
+    fullText: string;
+    /** Present for `markChange` suggestions. */
+    modification?: {
+        markName: string | null;
+        action: 'add' | 'remove' | null;
+        previousAttrs: Record<string, unknown> | null;
+        newAttrs: Record<string, unknown> | null;
+    };
+}
+/** Event names emitted on the tracked-changes emitter (M4.3). */
+export type SuggestionEventName = 'suggestion:create' | 'suggestion:update' | 'suggestion:accept' | 'suggestion:reject';
+export interface SuggestionEvent {
+    name: SuggestionEventName;
+    suggestion: Suggestion;
+    /** True when the change arrived via collaboration rather than local editing. */
+    remote: boolean;
+}
+export type SuggestionEventHandler = (event: SuggestionEvent) => void;
+/**
+ * Operations the engine cannot represent yet (Tier 2/3).
+ * 'block-structure' — Enter / paragraph join / block paste, blocked in suggest mode (edge case 5.3).
+ * 'untracked-step'  — wrap/unwrap, node attrs… passed through untracked with this notice (edge case 5.8).
+ */
+export type UntrackedOperationKind = 'block-structure' | 'untracked-step';
+export type UntrackedOperationHandler = (kind: UntrackedOperationKind, detail?: string) => void;
+/** Filter accepted by bulk accept/reject commands (M3.5). */
+export interface SuggestionFilter {
+    userId?: string;
+    ids?: string[];
+}

package/dist/extensions/trackedChanges/utils.d.ts

@@ -0,0 +1,20 @@
+import type { Mark, Node as PMNode } from '@tiptap/pm/model';
+/**
+ * UUIDv4 suggestion ids (M0.5) — counters would collide across concurrent
+ * offline clients and Yjs would happily merge them into one corrupted suggestion.
+ */
+export declare function createSuggestionId(): string;
+export declare function isSuggestionMark(mark: Mark): boolean;
+export declare function getInsertionMark(node: PMNode): Mark | undefined;
+export declare function getDeletionMark(node: PMNode): Mark | undefined;
+export declare function getModificationMarks(node: PMNode): Mark[];
+/** Serialize an attrs object into a DOM data attribute. */
+export declare function jsonAttrToDom(value: unknown): string | null;
+/** Parse a DOM data attribute back into an attrs object. */
+export declare function jsonAttrFromDom(value: string | null): Record<string, unknown> | null;
+/**
+ * Deterministic per-user hue so mark colors match across clients without
+ * coordination. An explicit `userMetadata.color` always wins (M8: colors are
+ * derived from userId, matching awareness cursors).
+ */
+export declare function suggestionColorForUser(userId: string | null, userMetadata: Record<string, unknown> | null): string;