@apollohg/react-native-rich-text-editor 2.0.0

package/dist/NativeEditorLocalAwareness.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_AWARENESS_SELECTION_VALUES = exports.LOCAL_AWARENESS_INTENT_KEYS = void 0;
+exports.invalidLocalAwarenessIntent = invalidLocalAwarenessIntent;
+exports.createNativeEditorLocalAwarenessSelection = createNativeEditorLocalAwarenessSelection;
+exports.isLocalAwarenessRecord = isLocalAwarenessRecord;
+exports.localAwarenessOwnDataValue = localAwarenessOwnDataValue;
+exports.validateLocalAwarenessSelection = validateLocalAwarenessSelection;
+exports.rejectReservedAwarenessCursor = rejectReservedAwarenessCursor;
+exports.normalizeLocalAwarenessState = normalizeLocalAwarenessState;
+exports.validateLocalAwarenessIntent = validateLocalAwarenessIntent;
+exports.serializeLocalAwarenessIntent = serializeLocalAwarenessIntent;
+const NativeEditorBoundaryError_1 = require("./NativeEditorBoundaryError");
+const NativeEditorResultNormalization_1 = require("./NativeEditorResultNormalization");
+const NativeEditorTypes_1 = require("./NativeEditorTypes");
+const NativeEditorCreateJson_1 = require("./NativeEditorCreateJson");
+exports.LOCAL_AWARENESS_INTENT_KEYS = new Set(['state', 'focused', 'selection']);
+exports.LOCAL_AWARENESS_SELECTION_VALUES = new WeakMap();
+function invalidLocalAwarenessIntent(message = 'invalid local awareness intent') {
+    throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)(`NativeEditorBridge: ${message}`);
+}
+/**
+ * Create the only caller-owned local-awareness selection accepted at the
+ * JavaScript-to-native boundary. The private WeakMap makes provenance an API
+ * capability instead of a structural object-shape check.
+ */
+function createNativeEditorLocalAwarenessSelection(anchor, head) {
+    const acceptedAnchor = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(anchor);
+    const acceptedHead = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(head);
+    if (acceptedAnchor == null || acceptedHead == null)
+        invalidLocalAwarenessIntent();
+    const selection = new NativeEditorTypes_1.NativeEditorLocalAwarenessSelectionValue(acceptedAnchor, acceptedHead);
+    Object.freeze(selection);
+    exports.LOCAL_AWARENESS_SELECTION_VALUES.set(selection, selection);
+    return selection;
+}
+function isLocalAwarenessRecord(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function localAwarenessOwnDataValue(record, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, key);
+    if (descriptor === undefined || !('value' in descriptor) || descriptor.enumerable !== true) {
+        invalidLocalAwarenessIntent();
+    }
+    return descriptor.value;
+}
+function validateLocalAwarenessSelection(selection) {
+    if (selection == null || typeof selection !== 'object')
+        invalidLocalAwarenessIntent();
+    // Do not inspect caller-held values before provenance succeeds: a Proxy
+    // can imitate every structural and own-data check, but it cannot inherit
+    // this module's WeakMap identity.
+    const factoryValue = exports.LOCAL_AWARENESS_SELECTION_VALUES.get(selection);
+    if (factoryValue === undefined)
+        invalidLocalAwarenessIntent();
+    const anchor = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(factoryValue.anchor);
+    const head = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(factoryValue.head);
+    if (anchor == null || head == null) {
+        invalidLocalAwarenessIntent();
+    }
+    return { anchor, head };
+}
+/** Reject caller-owned sticky cursor data before a native call can occur. */
+function rejectReservedAwarenessCursor(value) {
+    const pending = [value];
+    const seen = new WeakSet();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current == null || typeof current !== 'object')
+            continue;
+        if (seen.has(current))
+            continue;
+        seen.add(current);
+        for (const key of Reflect.ownKeys(current)) {
+            if (key === 'cursor')
+                invalidLocalAwarenessIntent('reserved cursor key is not allowed');
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor == null || !('value' in descriptor))
+                invalidLocalAwarenessIntent();
+            pending.push(descriptor.value);
+        }
+    }
+}
+function normalizeLocalAwarenessState(value) {
+    try {
+        const normalized = (0, NativeEditorCreateJson_1.normalizeV2JsonValue)(value, 'local awareness state', {
+            seen: new WeakSet(),
+            work: 0,
+        });
+        if (!isLocalAwarenessRecord(normalized) || Object.getPrototypeOf(normalized) !== null) {
+            invalidLocalAwarenessIntent();
+        }
+        rejectReservedAwarenessCursor(normalized);
+        return normalized;
+    }
+    catch (error) {
+        if (error instanceof NativeEditorBoundaryError_1.NativeEditorEngineBoundaryError)
+            throw error;
+        invalidLocalAwarenessIntent();
+    }
+}
+function validateLocalAwarenessIntent(intent) {
+    try {
+        if (!isLocalAwarenessRecord(intent) ||
+            Reflect.ownKeys(intent).some((key) => typeof key !== 'string' || !exports.LOCAL_AWARENESS_INTENT_KEYS.has(key)) ||
+            !Object.prototype.hasOwnProperty.call(intent, 'state') ||
+            !Object.prototype.hasOwnProperty.call(intent, 'focused')) {
+            invalidLocalAwarenessIntent();
+        }
+        const state = normalizeLocalAwarenessState(localAwarenessOwnDataValue(intent, 'state'));
+        const focused = localAwarenessOwnDataValue(intent, 'focused');
+        if (typeof focused !== 'boolean')
+            invalidLocalAwarenessIntent();
+        if (!Object.prototype.hasOwnProperty.call(intent, 'selection')) {
+            // Absent: retain whatever cursor Rust already holds.
+            return { state, focused };
+        }
+        const rawSelection = localAwarenessOwnDataValue(intent, 'selection');
+        if (rawSelection === null)
+            return { state, focused, selection: null };
+        const selection = validateLocalAwarenessSelection(rawSelection);
+        return { state, focused, selection: { type: 'text', ...selection } };
+    }
+    catch (error) {
+        if (error instanceof NativeEditorBoundaryError_1.NativeEditorEngineBoundaryError)
+            throw error;
+        invalidLocalAwarenessIntent();
+    }
+}
+function serializeLocalAwarenessIntent(intent) {
+    try {
+        const wire = Object.create(null);
+        wire.state = intent.state;
+        wire.focused = intent.focused;
+        if (intent.selection === null) {
+            wire.selection = null;
+        }
+        else if (intent.selection !== undefined) {
+            const selection = Object.create(null);
+            selection.type = intent.selection.type;
+            selection.anchor = intent.selection.anchor;
+            selection.head = intent.selection.head;
+            wire.selection = selection;
+        }
+        return (0, NativeEditorCreateJson_1.serializeV2CreateEnvelope)(wire);
+    }
+    catch {
+        invalidLocalAwarenessIntent();
+    }
+}

package/dist/NativeEditorNativeModule.d.ts

@@ -0,0 +1,48 @@
+import { type NativeEditorError } from './NativeEditorBoundaryError';
+export declare let _nativeModule: NativeEditorModule | null;
+export declare function getNativeModule(): NativeEditorModule;
+/** @internal Reset the cached native module reference. For testing only. */
+export declare function _resetNativeModuleCache(): void;
+export declare const ERR_V2_NATIVE_RESPONSE = "NativeEditorBridge: invalid v2 result record from native module";
+export declare const ERR_V2_DESTROYED = "NativeEditorBridge: v2 editor handle has been destroyed";
+export declare const V2_ENVELOPE_VERSION = 1;
+/**
+ * The v2 surface of the NativeEditor native module — the complete
+ * production ABI. Every call resolves the method lazily and fails clearly
+ * when the v2 surface is absent. Decimal-string identifiers keep full u64
+ * fidelity across the JavaScript boundary, and binaries travel as direct
+ * Uint8Array values (never JSON number arrays).
+ */
+export interface NativeEditorModule {
+    editorV2Create(configJson: string, snapshotState: Uint8Array | null): unknown;
+    editorV2Destroy(editorId: string): unknown;
+    editorV2GetState(editorId: string): unknown;
+    editorV2GetDocumentJson(editorId: string): unknown;
+    editorV2GetDocumentHtml(editorId: string): unknown;
+    editorV2GetContentSnapshot(editorId: string): unknown;
+    editorV2ReplaceDocument(editorId: string, requestJson: string): unknown;
+    editorV2ApplyInput(editorId: string, requestJson: string): unknown;
+    editorV2ApplyCommand(editorId: string, requestJson: string): unknown;
+    editorV2ApplyLocalApi(editorId: string, requestJson: string): unknown;
+    editorV2SetSelection(editorId: string, requestJson: string): unknown;
+    editorV2Undo(editorId: string, requestJson: string): unknown;
+    editorV2Redo(editorId: string, requestJson: string): unknown;
+    editorV2RenderUpdate(editorId: string, mirrorScalarAnchor: number | null, mirrorScalarHead: number | null): unknown;
+    editorV2CollaborationConfigureTransport(editorId: string, configJsonOrNull: string | null): unknown;
+    editorV2CollaborationResolveProtocolAdapter(editorId: string, attemptId: string, eventId: string, responseJson: string): unknown;
+    editorV2CollaborationSetAwareness(editorId: string, awarenessJson: string): unknown;
+    editorV2SnapshotExport(editorId: string): unknown;
+    editorV2SnapshotRestore(editorId: string, metadataJson: string, encodedState: Uint8Array): unknown;
+    addListener(eventName: 'onCollaborationTransportEvent', listener: (event: unknown) => void): {
+        remove(): void;
+    };
+}
+export declare function invokeNativeEditorV2<K extends keyof NativeEditorModule>(name: K, ...args: Parameters<NativeEditorModule[K]>): unknown;
+/** The discriminated envelope every v2 result record normalizes into. */
+export type NativeEditorResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: NativeEditorError;
+};

package/dist/NativeEditorNativeModule.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V2_ENVELOPE_VERSION = exports.ERR_V2_DESTROYED = exports.ERR_V2_NATIVE_RESPONSE = exports._nativeModule = void 0;
+exports.getNativeModule = getNativeModule;
+exports._resetNativeModuleCache = _resetNativeModuleCache;
+exports.invokeNativeEditorV2 = invokeNativeEditorV2;
+const expo_modules_core_1 = require("expo-modules-core");
+exports._nativeModule = null;
+function getNativeModule() {
+    if (!exports._nativeModule) {
+        exports._nativeModule = (0, expo_modules_core_1.requireNativeModule)('NativeEditor');
+    }
+    return exports._nativeModule;
+}
+/** @internal Reset the cached native module reference. For testing only. */
+function _resetNativeModuleCache() {
+    exports._nativeModule = null;
+}
+// The only construction path. Consumes the frozen v2 result records
+// ({ value, error }, exactly one side set), normalizes them at the JS boundary
+// (decimal-string u64s, direct binaries, unsafe-integer rejection), and raises
+// typed per-domain errors with a non-retryable class for
+// ENGINE_INVARIANT_FAILED and destroyed lifecycles.
+exports.ERR_V2_NATIVE_RESPONSE = 'NativeEditorBridge: invalid v2 result record from native module';
+exports.ERR_V2_DESTROYED = 'NativeEditorBridge: v2 editor handle has been destroyed';
+exports.V2_ENVELOPE_VERSION = 1;
+function invokeNativeEditorV2(name, ...args) {
+    const nativeModule = getNativeModule();
+    const method = nativeModule[name];
+    if (typeof method !== 'function') {
+        throw new Error(`NativeEditorBridge: native module does not expose the v2 entry ${String(name)}`);
+    }
+    return method.apply(nativeModule, args);
+}

package/dist/NativeEditorRenderNormalization.d.ts

@@ -0,0 +1,22 @@
+import { type ListContext, type RenderElement, type RenderBlocksPatch, type Selection, type ActiveState, type HistoryState, type NativeEditorAtomicRenderSnapshot, type DocumentJSON, type ContentSnapshot } from './NativeEditorTypes';
+export declare function validListContext(value: unknown): value is ListContext;
+export declare function validRenderElement(value: unknown): value is RenderElement;
+export declare function normalizeRenderBlocks(value: unknown): RenderElement[][] | null;
+export declare function normalizeRenderPatch(value: unknown): RenderBlocksPatch | null | undefined;
+export declare function normalizeRenderSelection(value: unknown): Selection | null;
+export declare function normalizeRenderActiveState(value: unknown): ActiveState | null;
+export declare function normalizeRenderHistoryState(value: unknown): HistoryState | null;
+export declare function deepFreezeV2Value<T>(value: T): T;
+/** Validate and freeze the one complete render/state snapshot. */
+export declare function normalizeNativeEditorV2RenderUpdateValue(value: unknown): NativeEditorAtomicRenderSnapshot | null;
+export declare function normalizeNativeEditorV2DocumentJsonValue(value: unknown): DocumentJSON | null;
+export declare function normalizeNativeEditorV2ContentSnapshotValue(value: unknown): ContentSnapshot | null;
+export interface NativeEditorSnapshotExport {
+    metadataJson: string;
+    encodedState: Uint8Array;
+}
+/** The snapshot export record arrives as direct fields (JSON + bytes), not a JSON string. */
+export declare function normalizeNativeEditorV2SnapshotExportValue(value: unknown): NativeEditorSnapshotExport | null;
+export declare function normalizeNativeEditorV2CreateValue(value: unknown): {
+    editorId: string;
+} | null;

package/dist/NativeEditorRenderNormalization.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validListContext = validListContext;
+exports.validRenderElement = validRenderElement;
+exports.normalizeRenderBlocks = normalizeRenderBlocks;
+exports.normalizeRenderPatch = normalizeRenderPatch;
+exports.normalizeRenderSelection = normalizeRenderSelection;
+exports.normalizeRenderActiveState = normalizeRenderActiveState;
+exports.normalizeRenderHistoryState = normalizeRenderHistoryState;
+exports.deepFreezeV2Value = deepFreezeV2Value;
+exports.normalizeNativeEditorV2RenderUpdateValue = normalizeNativeEditorV2RenderUpdateValue;
+exports.normalizeNativeEditorV2DocumentJsonValue = normalizeNativeEditorV2DocumentJsonValue;
+exports.normalizeNativeEditorV2ContentSnapshotValue = normalizeNativeEditorV2ContentSnapshotValue;
+exports.normalizeNativeEditorV2SnapshotExportValue = normalizeNativeEditorV2SnapshotExportValue;
+exports.normalizeNativeEditorV2CreateValue = normalizeNativeEditorV2CreateValue;
+const NativeEditorResultNormalization_1 = require("./NativeEditorResultNormalization");
+const EditorMentionThemeValidation_1 = require("./EditorMentionThemeValidation");
+function validListContext(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value))
+        return false;
+    return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, [
+        'ordered',
+        'index',
+        'total',
+        'start',
+        'isFirst',
+        'isLast',
+        'kind',
+        'checked',
+    ]) &&
+        typeof value.ordered === 'boolean' &&
+        (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.index) != null &&
+        (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.total) != null &&
+        (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.start) != null &&
+        typeof value.isFirst === 'boolean' &&
+        typeof value.isLast === 'boolean' &&
+        (value.kind == null || typeof value.kind === 'string') &&
+        (value.checked == null || typeof value.checked === 'boolean'));
+}
+function validRenderElement(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value) || !NativeEditorResultNormalization_1.RENDER_ELEMENT_TYPES.has(value.type)) {
+        return false;
+    }
+    switch (value.type) {
+        case 'textRun':
+            return ((0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['type', 'text', 'marks']) &&
+                typeof value.text === 'string' &&
+                Array.isArray(value.marks) &&
+                value.marks.every(NativeEditorResultNormalization_1.validRenderMark));
+        case 'blockStart':
+            return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, ['type', 'nodeType', 'depth', 'listContext', 'language']) &&
+                typeof value.nodeType === 'string' &&
+                (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.depth) != null &&
+                (value.language === undefined || typeof value.language === 'string') &&
+                (value.listContext === undefined || validListContext(value.listContext)));
+        case 'blockEnd':
+            return (0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['type']);
+        case 'voidInline':
+            return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, ['type', 'nodeType', 'docPos', 'attrs']) &&
+                typeof value.nodeType === 'string' &&
+                (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.docPos) != null &&
+                (value.attrs === undefined || (0, NativeEditorResultNormalization_1.isPlainRecord)(value.attrs)));
+        case 'voidBlock':
+            return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, ['type', 'nodeType', 'docPos', 'attrs', 'atomId']) &&
+                typeof value.nodeType === 'string' &&
+                (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.docPos) != null &&
+                (value.attrs === undefined || (0, NativeEditorResultNormalization_1.isPlainRecord)(value.attrs)) &&
+                (value.atomId === undefined || typeof value.atomId === 'string'));
+        case 'opaqueInlineAtom':
+            return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, [
+                'type',
+                'nodeType',
+                'label',
+                'docPos',
+                'attrs',
+                'mentionTheme',
+            ]) &&
+                typeof value.nodeType === 'string' &&
+                typeof value.label === 'string' &&
+                (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.docPos) != null &&
+                (value.attrs === undefined || (0, NativeEditorResultNormalization_1.isPlainRecord)(value.attrs)) &&
+                (value.mentionTheme === undefined || (0, EditorMentionThemeValidation_1.validEditorMentionTheme)(value.mentionTheme)));
+        case 'opaqueBlockAtom':
+            return ((0, NativeEditorResultNormalization_1.hasOnlyOwnKeys)(value, ['type', 'nodeType', 'label', 'docPos', 'attrs']) &&
+                typeof value.nodeType === 'string' &&
+                typeof value.label === 'string' &&
+                (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.docPos) != null &&
+                (value.attrs === undefined || (0, NativeEditorResultNormalization_1.isPlainRecord)(value.attrs)));
+    }
+    return false;
+}
+function normalizeRenderBlocks(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((block) => Array.isArray(block) && block.every((element) => validRenderElement(element)))
+        ? value
+        : null;
+}
+function normalizeRenderPatch(value) {
+    if (value === null)
+        return null;
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value) ||
+        !(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, [
+            'baseDocumentVersion',
+            'startIndex',
+            'deleteCount',
+            'renderBlocks',
+        ])) {
+        return undefined;
+    }
+    const renderBlocks = normalizeRenderBlocks(value.renderBlocks);
+    const baseDocumentVersion = (0, NativeEditorResultNormalization_1.normalizeNativeEditorV2DecimalId)(value.baseDocumentVersion);
+    const startIndex = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.startIndex);
+    const deleteCount = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.deleteCount);
+    if (renderBlocks == null ||
+        baseDocumentVersion == null ||
+        startIndex == null ||
+        deleteCount == null) {
+        return undefined;
+    }
+    return { baseDocumentVersion, startIndex, deleteCount, renderBlocks };
+}
+function normalizeRenderSelection(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value))
+        return null;
+    if (value.type === 'all')
+        return (0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['type']) ? { type: 'all' } : null;
+    if (value.type === 'text') {
+        if (!(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['type', 'anchor', 'head', 'anchorScalar', 'headScalar'])) {
+            return null;
+        }
+        const anchor = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.anchor);
+        const head = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.head);
+        const anchorScalar = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.anchorScalar);
+        const headScalar = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.headScalar);
+        if (anchor == null || head == null || anchorScalar == null || headScalar == null)
+            return null;
+        return { type: 'text', anchor, head, anchorScalar, headScalar };
+    }
+    if (value.type === 'node') {
+        if (!(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['type', 'pos', 'posScalar']))
+            return null;
+        const pos = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.pos);
+        const posScalar = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(value.posScalar);
+        if (pos == null || posScalar == null)
+            return null;
+        return { type: 'node', pos, posScalar };
+    }
+    return null;
+}
+function normalizeRenderActiveState(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value))
+        return null;
+    if (!(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, [
+        'marks',
+        'markAttrs',
+        'nodes',
+        'commands',
+        'allowedMarks',
+        'insertableNodes',
+    ]) ||
+        !(0, NativeEditorResultNormalization_1.booleanRecord)(value.marks) ||
+        !(0, NativeEditorResultNormalization_1.isPlainRecord)(value.markAttrs) ||
+        !Object.values(value.markAttrs).every(NativeEditorResultNormalization_1.isPlainRecord) ||
+        !(0, NativeEditorResultNormalization_1.booleanRecord)(value.nodes) ||
+        !(0, NativeEditorResultNormalization_1.booleanRecord)(value.commands) ||
+        !(0, NativeEditorResultNormalization_1.stringArray)(value.allowedMarks) ||
+        !(0, NativeEditorResultNormalization_1.stringArray)(value.insertableNodes)) {
+        return null;
+    }
+    return value;
+}
+function normalizeRenderHistoryState(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value) || !(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(value, ['canUndo', 'canRedo']))
+        return null;
+    const canUndo = (0, NativeEditorResultNormalization_1.optionalBoolean)(value.canUndo);
+    const canRedo = (0, NativeEditorResultNormalization_1.optionalBoolean)(value.canRedo);
+    return canUndo == null || canRedo == null ? null : { canUndo, canRedo };
+}
+function deepFreezeV2Value(value) {
+    if (value != null && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value)) {
+            deepFreezeV2Value(child);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}
+/** Validate and freeze the one complete render/state snapshot. */
+function normalizeNativeEditorV2RenderUpdateValue(value) {
+    const parsed = (0, NativeEditorResultNormalization_1.parseNativeEditorV2JsonValue)(value);
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(parsed))
+        return null;
+    if (!(0, NativeEditorResultNormalization_1.hasExactOwnKeys)(parsed, [
+        'renderBlocks',
+        'renderPatch',
+        'selection',
+        'activeState',
+        'historyState',
+        'documentVersion',
+        'stateRevision',
+        'scalarLength',
+        'documentIsEmpty',
+    ])) {
+        return null;
+    }
+    const renderBlocks = parsed.renderBlocks === null ? null : normalizeRenderBlocks(parsed.renderBlocks);
+    const renderPatch = normalizeRenderPatch(parsed.renderPatch);
+    const selection = normalizeRenderSelection(parsed.selection);
+    const activeState = normalizeRenderActiveState(parsed.activeState);
+    const historyState = normalizeRenderHistoryState(parsed.historyState);
+    const documentVersion = (0, NativeEditorResultNormalization_1.normalizeRevisionField)(parsed, 'documentVersion');
+    const stateRevision = (0, NativeEditorResultNormalization_1.normalizeRevisionField)(parsed, 'stateRevision');
+    const scalarLength = (0, NativeEditorResultNormalization_1.nativeEditorV2U32)(parsed.scalarLength);
+    const documentIsEmpty = parsed.documentIsEmpty;
+    if (renderPatch === undefined ||
+        selection == null ||
+        activeState == null ||
+        historyState == null ||
+        documentVersion == null ||
+        stateRevision == null ||
+        scalarLength == null ||
+        typeof documentIsEmpty !== 'boolean') {
+        return null;
+    }
+    let renderPayload;
+    if (renderBlocks == null) {
+        if (parsed.renderBlocks !== null || renderPatch == null)
+            return null;
+        renderPayload = { renderBlocks: null, renderPatch };
+    }
+    else {
+        if (renderPatch !== null)
+            return null;
+        renderPayload = { renderBlocks, renderPatch: null };
+    }
+    return deepFreezeV2Value({
+        ...renderPayload,
+        selection,
+        activeState,
+        historyState,
+        documentVersion,
+        stateRevision,
+        scalarLength,
+        documentIsEmpty,
+    });
+}
+function normalizeNativeEditorV2DocumentJsonValue(value) {
+    const parsed = (0, NativeEditorResultNormalization_1.parseNativeEditorV2JsonValue)(value);
+    return (0, NativeEditorResultNormalization_1.isPlainRecord)(parsed) ? parsed : null;
+}
+function normalizeNativeEditorV2ContentSnapshotValue(value) {
+    const parsed = (0, NativeEditorResultNormalization_1.parseNativeEditorV2JsonValue)(value);
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(parsed) || typeof parsed.html !== 'string' || !(0, NativeEditorResultNormalization_1.isPlainRecord)(parsed.json)) {
+        return null;
+    }
+    return { html: parsed.html, json: parsed.json };
+}
+/** The snapshot export record arrives as direct fields (JSON + bytes), not a JSON string. */
+function normalizeNativeEditorV2SnapshotExportValue(value) {
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(value) || typeof value.metadataJson !== 'string')
+        return null;
+    const encodedState = (0, NativeEditorResultNormalization_1.normalizeNativeEditorV2Bytes)(value.encodedState);
+    if (encodedState == null)
+        return null;
+    return { metadataJson: value.metadataJson, encodedState };
+}
+function normalizeNativeEditorV2CreateValue(value) {
+    const parsed = (0, NativeEditorResultNormalization_1.parseNativeEditorV2JsonValue)(value);
+    if (!(0, NativeEditorResultNormalization_1.isPlainRecord)(parsed))
+        return null;
+    const editorId = (0, NativeEditorResultNormalization_1.normalizeNativeEditorV2DecimalId)(parsed.editorId);
+    return editorId == null ? null : { editorId };
+}

package/dist/NativeEditorResultNormalization.d.ts

@@ -0,0 +1,108 @@
+import { NativeEditorEngineBoundaryError, NativeEditorNonRetryableError } from './NativeEditorBoundaryError';
+import { type NativeEditorResult } from './NativeEditorNativeModule';
+import { type RenderMark } from './NativeEditorTypes';
+import { type NativeEditorPeerInfo } from './NativeEditorCollaborationTransport';
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Validate a raw v2 result record: exactly one of value/error, every error
+ * field type, every domain/code string, and the caller-supplied value
+ * normalizer. Returns null for any contract violation; the imperative layer
+ * turns that into the non-retryable FFI_RESULT_INVALID error.
+ */
+export declare function normalizeNativeEditorV2Result<T>(raw: unknown, normalizeValue: (value: unknown) => T | null): NativeEditorResult<T> | null;
+/** Parse a JSON-string result value; anything else is a contract violation. */
+export declare function parseNativeEditorV2JsonValue(value: unknown): unknown | null;
+/**
+ * Validate a direct binary result value. JSON number arrays are rejected on
+ * purpose: the frozen v2 contract moves bytes as bytes.
+ */
+export declare function normalizeNativeEditorV2Bytes(value: unknown): Uint8Array | null;
+/** FfiUnitResult successes are exactly `true`; anything else is invalid. */
+export declare function normalizeNativeEditorV2Unit(value: unknown): true | null;
+/**
+ * Normalize a request/revision identifier to its canonical decimal string.
+ * V2 never accepts numeric compatibility values: JavaScript numbers cannot
+ * represent the complete Rust u64 domain.
+ */
+export declare function normalizeNativeEditorV2DecimalId(value: unknown): string | null;
+export declare function normalizeRevisionField(record: Record<string, unknown>, field: string): string | null;
+export declare function nativeEditorV2U32(value: unknown): number | null;
+/** Require one exact JavaScript/platform u32 value at the v2 boundary. */
+export declare function requireNativeEditorV2U32(value: unknown, field: string): number;
+export declare function optionalBoolean(value: unknown): boolean | null;
+export declare const V2_DOCUMENT_STATES: readonly ["LocalReady", "AwaitRemote", "RoomReady"];
+/**
+ * Readiness of the engine document. `AwaitRemote` is a room document still
+ * waiting for the server's copy: content getters return empty values and the
+ * view renders nothing until it promotes to `RoomReady`.
+ */
+export type NativeEditorDocumentState = (typeof V2_DOCUMENT_STATES)[number];
+export declare const V2_TRANSPORT_STATES: readonly ["Detached", "Disconnected", "Connecting", "Handshaking", "Synchronized", "Incompatible", "Destroying", "Destroyed"];
+/** Raw transport lifecycle. `YjsTransportStatus` is the friendlier projection of it. */
+export type NativeEditorTransportState = (typeof V2_TRANSPORT_STATES)[number];
+export declare const V2_RENDER_STATES: readonly ["Loading", "Ready"];
+/** Whether the engine has a render snapshot to draw. */
+export type NativeEditorRenderState = (typeof V2_RENDER_STATES)[number];
+export declare const V2_DOCUMENT_ORIGINS: readonly ["nativeView", "jsApi", "remoteCollaboration", "history", "restore", "import"];
+export type NativeEditorDocumentOrigin = (typeof V2_DOCUMENT_ORIGINS)[number];
+export declare function whitelisted<T extends string>(value: unknown, allowed: readonly T[]): T | null;
+/** The engine's own account of a session: readiness, revisions, and history. */
+export interface NativeEditorState {
+    documentState: NativeEditorDocumentState;
+    transportState: NativeEditorTransportState;
+    renderState: NativeEditorRenderState;
+    /** Decimal-string revision advancing on every document change. */
+    documentRevision: string;
+    /** Trusted origin of the transaction that produced documentRevision. */
+    documentOrigin: NativeEditorDocumentOrigin;
+    /** Decimal-string revision advancing on every state change, document or not. */
+    stateRevision: string;
+    canUndo: boolean;
+    canRedo: boolean;
+}
+export declare function normalizeNativeEditorV2StateValue(value: unknown): NativeEditorState | null;
+export type NativeEditorMutationOutcome = {
+    type: 'transaction';
+    changed: boolean;
+    documentRevision: string;
+    stateRevision: string;
+    canUndo: boolean;
+    canRedo: boolean;
+} | {
+    type: 'notApplicable';
+} | {
+    type: 'replacement';
+    changed: boolean;
+    documentRevision: string;
+};
+export declare function normalizeNativeEditorV2MutationOutcomeValue(value: unknown): NativeEditorMutationOutcome | null;
+export interface NativeEditorCommitInfo {
+    changed: boolean;
+    documentRevision: string;
+}
+export declare function normalizeNativeEditorV2CommitValue(value: unknown): NativeEditorCommitInfo | null;
+export declare function normalizeNativeEditorV2ChangedValue(value: unknown): boolean | null;
+export declare function normalizeNativeEditorV2HtmlValue(value: unknown): string | null;
+export declare const RENDER_ELEMENT_TYPES: Set<"textRun" | "blockStart" | "blockEnd" | "voidInline" | "voidBlock" | "opaqueInlineAtom" | "opaqueBlockAtom">;
+export declare function hasExactOwnKeys(record: Record<string, unknown>, expected: readonly string[]): boolean;
+export declare function hasOnlyOwnKeys(record: Record<string, unknown>, allowed: readonly string[]): boolean;
+export declare function booleanRecord(value: unknown): value is Record<string, boolean>;
+export declare function stringArray(value: unknown): value is string[];
+export declare function validJsonValue(value: unknown): boolean;
+export declare function validRenderMark(value: unknown): value is RenderMark;
+export declare function normalizeNativeEditorV2PeersValue(value: unknown): NativeEditorPeerInfo[] | null;
+export declare const REJECTED_V2_RECORD_PREVIEW_CHARS = 4000;
+/** Dev-only preview of a rejected boundary record, bounded so a large document never floods the log. */
+export declare function describeRejectedV2Record(raw: unknown): string;
+export declare function invalidV2ResultError(): NativeEditorNonRetryableError;
+export declare function destroyedHandleError(): NativeEditorNonRetryableError;
+export declare function invalidV2RequestError(message: string): NativeEditorEngineBoundaryError;
+/**
+ * Unwrap a raw v2 result record on the imperative path: typed per-domain
+ * throws for recoverable engine errors, the distinct non-retryable class for
+ * ENGINE_INVARIANT_FAILED / lifecycle-destroyed states and for malformed
+ * records (a bridge contract violation can never succeed on retry).
+ */
+export declare function unwrapNativeEditorV2Result<T>(raw: unknown, normalizeValue: (value: unknown) => T | null): T;
+export declare function requireV2DecimalId(value: string, field: string): string;
+export declare function requireV2Bytes(value: unknown, field: string): Uint8Array;