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

package/dist/NativeEditorDocumentBridge.d.ts

@@ -0,0 +1,72 @@
+import { NativeEditorErrorBase } from './NativeEditorBoundaryError';
+import { type NativeCollaborationTransportConfig, type NativeCollaborationTransportEvent } from './NativeEditorCollaborationTransport';
+import { type NativeEditorState, type NativeEditorCommitInfo, type NativeEditorMutationOutcome } from './NativeEditorResultNormalization';
+import { type DocumentJSON, type ContentSnapshot, type NativeEditorAtomicRenderSnapshot, type NativeEditorReplaceDocumentRequest, type NativeEditorInputRequest, type NativeEditorCommandRequest, type NativeEditorLocalApiRequest, type NativeEditorSelectionRequest, type NativeEditorSnapshotMetadata, type NativeEditorLocalAwarenessIntent } from './NativeEditorTypes';
+import { type NativeEditorSnapshotExport } from './NativeEditorRenderNormalization';
+/**
+ * Typed imperative v2 bridge bound to one decimal-string editor id. Every
+ * entry normalizes the frozen result record, keeps revisions as decimal
+ * strings, and throws typed errors; results that arrive for a destroyed
+ * handle (including re-entrant destroy races) are classified non-retryable.
+ */
+export declare class NativeEditorDocumentBridge {
+    private readonly _editorId;
+    private _destroyed;
+    /** @internal Reset intent waiting for the interactive view handoff. */
+    _pendingViewReset: {
+        json: string;
+    } | null;
+    private _nextRequestId;
+    private readonly _errorListeners;
+    private _collaborationProtocolAdapter;
+    private _collaborationProtocolAdapterSubscription;
+    /** @internal Created by createNativeEditorDocumentHandle. */
+    constructor(editorId: string);
+    get editorId(): string;
+    get isDestroyed(): boolean;
+    private assertAlive;
+    private callV2;
+    private nextRequestId;
+    /**
+     * Serialize a request envelope with canonical decimal-string u64 fields.
+     */
+    private buildEnvelopeJson;
+    /** Destroy the session. Repeated destroy is safe. */
+    destroy(): void;
+    /** Subscribe to autonomous native failures; returns the unsubscribe. */
+    addErrorListener(listener: (error: NativeEditorErrorBase) => void): () => void;
+    /**
+     * @internal Route one autonomous native failure (input/accessibility) to
+     * the error listeners exactly once. Accepts a bare error record or the
+     * frozen envelope form; malformed payloads surface as a non-retryable
+     * contract violation so the view stays usable.
+     */
+    _emitAutonomousError(raw: unknown): void;
+    getState(): NativeEditorState;
+    getDocumentJson(): DocumentJSON;
+    getDocumentHtml(): string;
+    getContentSnapshot(): ContentSnapshot;
+    /**
+     * Fetch the complete typed, immutable render snapshot a bound native view
+     * applies after a JS-driven engine change. Without a scalar mirror, its
+     * selection is the engine-authoritative selection; a mirror resolves only
+     * this snapshot's selection into document and scalar positions.
+     */
+    renderUpdate(mirrorScalarSelection?: {
+        anchor: number;
+        head: number;
+    }): NativeEditorAtomicRenderSnapshot;
+    replaceDocument(request: NativeEditorReplaceDocumentRequest): NativeEditorCommitInfo;
+    applyInput(request: NativeEditorInputRequest): NativeEditorMutationOutcome;
+    applyCommand(request: NativeEditorCommandRequest): NativeEditorMutationOutcome;
+    applyLocalApi(request: NativeEditorLocalApiRequest): NativeEditorMutationOutcome;
+    setSelection(request: NativeEditorSelectionRequest): NativeEditorMutationOutcome;
+    undo(): boolean;
+    redo(): boolean;
+    snapshotExport(): NativeEditorSnapshotExport;
+    snapshotRestore(metadata: NativeEditorSnapshotMetadata, encodedState: Uint8Array): NativeEditorCommitInfo;
+    configureCollaborationTransport(config: NativeCollaborationTransportConfig | null): void;
+    private handleCollaborationProtocolAdapterEvent;
+    setLocalAwareness(intent: NativeEditorLocalAwarenessIntent | null): void;
+    addCollaborationTransportListener(listener: (event: NativeCollaborationTransportEvent) => void): () => void;
+}

package/dist/NativeEditorDocumentBridge.js

@@ -0,0 +1,305 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeEditorDocumentBridge = void 0;
+const NativeEditorBoundaryError_1 = require("./NativeEditorBoundaryError");
+const NativeEditorCollaborationTransport_1 = require("./NativeEditorCollaborationTransport");
+const NativeEditorResultNormalization_1 = require("./NativeEditorResultNormalization");
+const NativeEditorNativeModule_1 = require("./NativeEditorNativeModule");
+const NativeEditorRenderNormalization_1 = require("./NativeEditorRenderNormalization");
+const NativeEditorLocalAwareness_1 = require("./NativeEditorLocalAwareness");
+/**
+ * Typed imperative v2 bridge bound to one decimal-string editor id. Every
+ * entry normalizes the frozen result record, keeps revisions as decimal
+ * strings, and throws typed errors; results that arrive for a destroyed
+ * handle (including re-entrant destroy races) are classified non-retryable.
+ */
+class NativeEditorDocumentBridge {
+    /** @internal Created by createNativeEditorDocumentHandle. */
+    constructor(editorId) {
+        this._destroyed = false;
+        /** @internal Reset intent waiting for the interactive view handoff. */
+        this._pendingViewReset = null;
+        this._nextRequestId = 0n;
+        this._errorListeners = new Set();
+        this._collaborationProtocolAdapter = null;
+        this._collaborationProtocolAdapterSubscription = null;
+        this._editorId = editorId;
+    }
+    get editorId() {
+        return this._editorId;
+    }
+    get isDestroyed() {
+        return this._destroyed;
+    }
+    assertAlive() {
+        if (this._destroyed)
+            throw (0, NativeEditorResultNormalization_1.destroyedHandleError)();
+    }
+    callV2(invoke, normalizeValue) {
+        this.assertAlive();
+        const raw = invoke();
+        // A re-entrant destroy racing the native call makes any result
+        // arriving now a result for a destroyed handle: non-retryable.
+        if (this._destroyed)
+            throw (0, NativeEditorResultNormalization_1.destroyedHandleError)();
+        return (0, NativeEditorResultNormalization_1.unwrapNativeEditorV2Result)(raw, normalizeValue);
+    }
+    nextRequestId() {
+        if (this._nextRequestId >= 18446744073709551615n) {
+            throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)('NativeEditorBridge: v2 request id exhausted');
+        }
+        this._nextRequestId += 1n;
+        return this._nextRequestId.toString();
+    }
+    /**
+     * Serialize a request envelope with canonical decimal-string u64 fields.
+     */
+    buildEnvelopeJson(payload, baseDocumentRevision) {
+        const parts = [
+            `"version":${NativeEditorNativeModule_1.V2_ENVELOPE_VERSION}`,
+            `"requestId":"${this.nextRequestId()}"`,
+        ];
+        if (baseDocumentRevision !== undefined) {
+            const digits = (0, NativeEditorResultNormalization_1.requireV2DecimalId)(baseDocumentRevision, 'baseDocumentRevision');
+            parts.push(`"baseDocumentRevision":"${digits}"`);
+        }
+        const payloadJson = JSON.stringify(payload);
+        const inner = payloadJson.slice(1, payloadJson.length - 1);
+        if (inner.length > 0)
+            parts.push(inner);
+        return `{${parts.join(',')}}`;
+    }
+    /** Destroy the session. Repeated destroy is safe. */
+    destroy() {
+        if (this._destroyed)
+            return;
+        try {
+            (0, NativeEditorResultNormalization_1.unwrapNativeEditorV2Result)((0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2Destroy', this._editorId), NativeEditorResultNormalization_1.normalizeNativeEditorV2Unit);
+        }
+        catch (error) {
+            // An already-destroyed native session still satisfies the
+            // caller's goal; every other failure is reported.
+            if (error instanceof NativeEditorBoundaryError_1.NativeEditorNonRetryableError &&
+                (error.code === 'ENGINE_DESTROYED' || error.code === 'ENGINE_DESTROYING')) {
+                // An already-destroyed native session still commits the
+                // local teardown below.
+            }
+            else {
+                throw error;
+            }
+        }
+        this._destroyed = true;
+        this._collaborationProtocolAdapter = null;
+        this._collaborationProtocolAdapterSubscription?.remove();
+        this._collaborationProtocolAdapterSubscription = null;
+        this._errorListeners.clear();
+    }
+    /** Subscribe to autonomous native failures; returns the unsubscribe. */
+    addErrorListener(listener) {
+        this._errorListeners.add(listener);
+        return () => {
+            this._errorListeners.delete(listener);
+        };
+    }
+    /**
+     * @internal Route one autonomous native failure (input/accessibility) to
+     * the error listeners exactly once. Accepts a bare error record or the
+     * frozen envelope form; malformed payloads surface as a non-retryable
+     * contract violation so the view stays usable.
+     */
+    _emitAutonomousError(raw) {
+        if (this._destroyed)
+            return;
+        const candidate = (0, NativeEditorResultNormalization_1.isPlainRecord)(raw) && 'error' in raw ? raw : { error: raw };
+        const normalized = (0, NativeEditorBoundaryError_1.normalizeNativeEditorV2Error)(candidate);
+        const exception = normalized == null
+            ? (0, NativeEditorResultNormalization_1.invalidV2ResultError)()
+            : (0, NativeEditorBoundaryError_1.nativeEditorV2ErrorToException)(normalized);
+        for (const listener of this._errorListeners) {
+            listener(exception);
+        }
+    }
+    getState() {
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2GetState', this._editorId), NativeEditorResultNormalization_1.normalizeNativeEditorV2StateValue);
+    }
+    getDocumentJson() {
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2GetDocumentJson', this._editorId), NativeEditorRenderNormalization_1.normalizeNativeEditorV2DocumentJsonValue);
+    }
+    getDocumentHtml() {
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2GetDocumentHtml', this._editorId), NativeEditorResultNormalization_1.normalizeNativeEditorV2HtmlValue);
+    }
+    getContentSnapshot() {
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2GetContentSnapshot', this._editorId), NativeEditorRenderNormalization_1.normalizeNativeEditorV2ContentSnapshotValue);
+    }
+    /**
+     * Fetch the complete typed, immutable render snapshot a bound native view
+     * applies after a JS-driven engine change. Without a scalar mirror, its
+     * selection is the engine-authoritative selection; a mirror resolves only
+     * this snapshot's selection into document and scalar positions.
+     */
+    renderUpdate(mirrorScalarSelection) {
+        this.assertAlive();
+        const mirrorAnchor = mirrorScalarSelection?.anchor ?? null;
+        const mirrorHead = mirrorScalarSelection?.head ?? null;
+        if ((mirrorAnchor == null) !== (mirrorHead == null)) {
+            throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)('NativeEditorBridge: render update mirror requires both scalar anchor and head');
+        }
+        if (mirrorAnchor != null)
+            (0, NativeEditorResultNormalization_1.requireNativeEditorV2U32)(mirrorAnchor, 'mirrorScalarAnchor');
+        if (mirrorHead != null)
+            (0, NativeEditorResultNormalization_1.requireNativeEditorV2U32)(mirrorHead, 'mirrorScalarHead');
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2RenderUpdate', this._editorId, mirrorAnchor, mirrorHead), NativeEditorRenderNormalization_1.normalizeNativeEditorV2RenderUpdateValue);
+    }
+    replaceDocument(request) {
+        this.assertAlive();
+        const payload = {};
+        if (request.setJson !== undefined)
+            payload.setJson = request.setJson;
+        if (request.setHtml !== undefined)
+            payload.setHtml = request.setHtml;
+        payload.history = request.history;
+        const requestJson = this.buildEnvelopeJson(payload);
+        const result = this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2ReplaceDocument', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2CommitValue);
+        if (request.history === 'resetAndClear' && 'documentRevision' in result) {
+            this._pendingViewReset = {
+                json: JSON.stringify({ ...payload, documentRevision: result.documentRevision }),
+            };
+        }
+        else {
+            this._pendingViewReset = null;
+        }
+        return result;
+    }
+    applyInput(request) {
+        this.assertAlive();
+        const requestJson = this.buildEnvelopeJson({ text: request.text }, request.baseDocumentRevision);
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2ApplyInput', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2MutationOutcomeValue);
+    }
+    applyCommand(request) {
+        this.assertAlive();
+        const requestJson = this.buildEnvelopeJson({ command: request.command }, request.baseDocumentRevision);
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2ApplyCommand', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2MutationOutcomeValue);
+    }
+    applyLocalApi(request) {
+        this.assertAlive();
+        const payload = {};
+        if (request.setJson !== undefined)
+            payload.setJson = request.setJson;
+        if (request.setHtml !== undefined)
+            payload.setHtml = request.setHtml;
+        payload.history = request.history;
+        const requestJson = this.buildEnvelopeJson(payload, request.baseDocumentRevision);
+        const result = this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2ApplyLocalApi', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2MutationOutcomeValue);
+        if (request.history === 'resetAndClear' && 'documentRevision' in result) {
+            this._pendingViewReset = {
+                json: JSON.stringify({ ...payload, documentRevision: result.documentRevision }),
+            };
+        }
+        else {
+            this._pendingViewReset = null;
+        }
+        return result;
+    }
+    setSelection(request) {
+        this.assertAlive();
+        const requestJson = this.buildEnvelopeJson({ selection: request.selection }, request.baseDocumentRevision);
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2SetSelection', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2MutationOutcomeValue);
+    }
+    undo() {
+        this.assertAlive();
+        const requestJson = this.buildEnvelopeJson({});
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2Undo', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2ChangedValue);
+    }
+    redo() {
+        this.assertAlive();
+        const requestJson = this.buildEnvelopeJson({});
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2Redo', this._editorId, requestJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2ChangedValue);
+    }
+    snapshotExport() {
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2SnapshotExport', this._editorId), NativeEditorRenderNormalization_1.normalizeNativeEditorV2SnapshotExportValue);
+    }
+    snapshotRestore(metadata, encodedState) {
+        this.assertAlive();
+        const bytes = (0, NativeEditorResultNormalization_1.requireV2Bytes)(encodedState, 'snapshot encodedState');
+        return this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2SnapshotRestore', this._editorId, JSON.stringify(metadata), bytes), NativeEditorResultNormalization_1.normalizeNativeEditorV2CommitValue);
+    }
+    configureCollaborationTransport(config) {
+        this.assertAlive();
+        const wireConfig = config === null ? null : (0, NativeEditorCollaborationTransport_1.collaborationTransportWireConfig)(config);
+        const previousAdapter = this._collaborationProtocolAdapter;
+        const nextAdapter = config?.protocolAdapter ?? null;
+        if (nextAdapter !== null && this._collaborationProtocolAdapterSubscription === null) {
+            this._collaborationProtocolAdapterSubscription = (0, NativeEditorNativeModule_1.getNativeModule)().addListener('onCollaborationTransportEvent', (rawEvent) => this.handleCollaborationProtocolAdapterEvent(rawEvent));
+        }
+        this._collaborationProtocolAdapter = nextAdapter;
+        try {
+            this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2CollaborationConfigureTransport', this._editorId, wireConfig === null ? null : JSON.stringify(wireConfig)), NativeEditorResultNormalization_1.normalizeNativeEditorV2Unit);
+        }
+        catch (error) {
+            this._collaborationProtocolAdapter = previousAdapter;
+            if (previousAdapter === null &&
+                this._collaborationProtocolAdapterSubscription !== null) {
+                this._collaborationProtocolAdapterSubscription.remove();
+                this._collaborationProtocolAdapterSubscription = null;
+            }
+            throw error;
+        }
+        if (nextAdapter === null && this._collaborationProtocolAdapterSubscription !== null) {
+            this._collaborationProtocolAdapterSubscription.remove();
+            this._collaborationProtocolAdapterSubscription = null;
+        }
+    }
+    handleCollaborationProtocolAdapterEvent(rawEvent) {
+        if (this._destroyed || this._collaborationProtocolAdapter === null)
+            return;
+        const event = (0, NativeEditorCollaborationTransport_1.normalizeNativeCollaborationTransportEvent)(rawEvent);
+        if (event?.editorId !== this._editorId || event.kind !== 'protocolAdapter') {
+            return;
+        }
+        const adapter = this._collaborationProtocolAdapter;
+        const context = {
+            attemptId: event.attemptId,
+            generation: event.generation,
+            negotiatedProtocol: event.negotiatedProtocol,
+        };
+        const callback = event.phase === 'open'
+            ? () => adapter.onOpen(context)
+            : () => adapter.onMessage(context, event.frame);
+        void Promise.resolve()
+            .then(callback)
+            .then((result) => (0, NativeEditorCollaborationTransport_1.serializeCollaborationProtocolAdapterResult)(result))
+            .catch(() => '{"action":"reject"}')
+            .then((responseJson) => {
+            if (this._destroyed)
+                return;
+            try {
+                this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2CollaborationResolveProtocolAdapter', this._editorId, event.attemptId, event.eventId, responseJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2Unit);
+            }
+            catch {
+                // Native treats stale attempt responses as no-ops. A live
+                // resolution failure is surfaced by its transport event;
+                // adapter payloads and callback errors are never logged.
+            }
+        });
+    }
+    setLocalAwareness(intent) {
+        this.assertAlive();
+        const awarenessJson = intent === null
+            ? 'null'
+            : (0, NativeEditorLocalAwareness_1.serializeLocalAwarenessIntent)((0, NativeEditorLocalAwareness_1.validateLocalAwarenessIntent)(intent));
+        this.callV2(() => (0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2CollaborationSetAwareness', this._editorId, awarenessJson), NativeEditorResultNormalization_1.normalizeNativeEditorV2Unit);
+    }
+    addCollaborationTransportListener(listener) {
+        this.assertAlive();
+        const subscription = (0, NativeEditorNativeModule_1.getNativeModule)().addListener('onCollaborationTransportEvent', (rawEvent) => {
+            if (this._destroyed)
+                return;
+            const event = (0, NativeEditorCollaborationTransport_1.normalizeNativeCollaborationTransportEvent)(rawEvent);
+            if (event?.editorId === this._editorId) {
+                listener(event);
+            }
+        });
+        return () => subscription.remove();
+    }
+}
+exports.NativeEditorDocumentBridge = NativeEditorDocumentBridge;

package/dist/NativeEditorDocumentHandle.d.ts

@@ -0,0 +1,70 @@
+import { type ResolvedDocumentSchema } from './schemas';
+import { NativeEditorErrorBase } from './NativeEditorBoundaryError';
+import { NativeEditorDocumentBridge } from './NativeEditorDocumentBridge';
+import { type NativeCollaborationTransportConfig, type NativeCollaborationTransportEvent } from './NativeEditorCollaborationTransport';
+import { type NativeEditorLocalAwarenessIntent, type NativeEditorCreateConfig } from './NativeEditorTypes';
+export declare const NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND: unique symbol;
+export declare const NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN: Readonly<{}>;
+export declare const AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES: WeakSet<object>;
+export declare const NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS: WeakMap<object, ResolvedDocumentSchema>;
+/**
+ * One native document session, shared by everything that touches the
+ * document: the editor view, the headless `useNativeEditorDocument` binding,
+ * and the collaboration controller. Obtain one from
+ * {@link createNativeEditorDocumentHandle} — it cannot be constructed
+ * directly — and `destroy()` it when its owner unmounts.
+ */
+export interface NativeEditorDocumentHandle {
+    readonly [NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND]: true;
+    /** Decimal-string session id, shared with the native view. */
+    readonly editorId: string;
+    /** Typed imperative access to the engine. The React APIs use this for you. */
+    readonly bridge: NativeEditorDocumentBridge;
+    readonly isDestroyed: boolean;
+    /** Release the native session. Every later call fails as non-retryable. */
+    destroy(): void;
+    /** Observe engine failures raised outside a caller's own call. Returns an unsubscribe function. */
+    addErrorListener(listener: (error: NativeEditorErrorBase) => void): () => void;
+    /** Point the native transport at a server, or pass null to detach. */
+    configureCollaborationTransport(config: NativeCollaborationTransportConfig | null): void;
+    /** Publish local presence, or pass null to withdraw it. */
+    setLocalAwareness(intent: NativeEditorLocalAwarenessIntent | null): void;
+    /** Observe transport state, errors, and protocol-adapter requests. Returns an unsubscribe function. */
+    addCollaborationTransportListener(listener: (event: NativeCollaborationTransportEvent) => void): () => void;
+}
+export declare class NativeEditorDocumentHandleImpl implements NativeEditorDocumentHandle {
+    readonly editorId: string;
+    readonly bridge: NativeEditorDocumentBridge;
+    readonly [NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND]: true;
+    constructor(token: typeof NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN, editorId: string, bridge: NativeEditorDocumentBridge, documentDescriptor: ResolvedDocumentSchema);
+    get isDestroyed(): boolean;
+    destroy(): void;
+    addErrorListener(listener: (error: NativeEditorErrorBase) => void): () => void;
+    configureCollaborationTransport(config: NativeCollaborationTransportConfig | null): void;
+    setLocalAwareness(intent: NativeEditorLocalAwarenessIntent | null): void;
+    addCollaborationTransportListener(listener: (event: NativeCollaborationTransportEvent) => void): () => void;
+}
+/** @internal Handle-owned schema metadata for source-module view bindings. */
+export declare function _getNativeEditorDocumentHandleDescriptor(handle: NativeEditorDocumentHandle): ResolvedDocumentSchema;
+/** @internal Source-module boundary assertion; intentionally absent from the package index. */
+export declare function _assertNativeEditorDocumentHandle(value: unknown): asserts value is NativeEditorDocumentHandle;
+/**
+ * Create the native document session every other API binds to. Create it once
+ * per document — `useMemo`, not on each render — and destroy it when its
+ * owner unmounts.
+ *
+ * @throws NativeEditorErrorBase when the config is rejected: a malformed
+ * schema, an out-of-range limit, or content the engine cannot parse.
+ *
+ * @example
+ * ```ts
+ * const documentHandle = useMemo(
+ *     () => createNativeEditorDocumentHandle({
+ *         initialization: { type: 'localHtml', html: '<p>Hello world</p>' },
+ *     }),
+ *     []
+ * );
+ * useEffect(() => () => documentHandle.destroy(), [documentHandle]);
+ * ```
+ */
+export declare function createNativeEditorDocumentHandle(config: NativeEditorCreateConfig): NativeEditorDocumentHandle;

package/dist/NativeEditorDocumentHandle.js

@@ -0,0 +1,89 @@
+"use strict";
+var _a;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeEditorDocumentHandleImpl = exports.NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS = exports.AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES = exports.NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN = exports.NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND = void 0;
+exports._getNativeEditorDocumentHandleDescriptor = _getNativeEditorDocumentHandleDescriptor;
+exports._assertNativeEditorDocumentHandle = _assertNativeEditorDocumentHandle;
+exports.createNativeEditorDocumentHandle = createNativeEditorDocumentHandle;
+const NativeEditorDocumentBridge_1 = require("./NativeEditorDocumentBridge");
+const NativeEditorResultNormalization_1 = require("./NativeEditorResultNormalization");
+const NativeEditorCreateConfig_1 = require("./NativeEditorCreateConfig");
+const NativeEditorNativeModule_1 = require("./NativeEditorNativeModule");
+const NativeEditorRenderNormalization_1 = require("./NativeEditorRenderNormalization");
+exports.NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND = Symbol('NativeEditorDocumentHandle.brand');
+exports.NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN = Object.freeze({});
+exports.AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES = new WeakSet();
+exports.NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS = new WeakMap();
+class NativeEditorDocumentHandleImpl {
+    constructor(token, editorId, bridge, documentDescriptor) {
+        this.editorId = editorId;
+        this.bridge = bridge;
+        this[_a] = true;
+        if (token !== exports.NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN) {
+            throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)('NativeEditorBridge: NativeEditorDocumentHandle cannot be constructed directly');
+        }
+        exports.AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES.add(this);
+        exports.NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS.set(this, documentDescriptor);
+    }
+    get isDestroyed() {
+        return this.bridge.isDestroyed;
+    }
+    destroy() {
+        this.bridge.destroy();
+    }
+    addErrorListener(listener) {
+        return this.bridge.addErrorListener(listener);
+    }
+    configureCollaborationTransport(config) {
+        this.bridge.configureCollaborationTransport(config);
+    }
+    setLocalAwareness(intent) {
+        this.bridge.setLocalAwareness(intent);
+    }
+    addCollaborationTransportListener(listener) {
+        return this.bridge.addCollaborationTransportListener(listener);
+    }
+}
+exports.NativeEditorDocumentHandleImpl = NativeEditorDocumentHandleImpl;
+_a = exports.NATIVE_EDITOR_DOCUMENT_HANDLE_BRAND;
+/** @internal Handle-owned schema metadata for source-module view bindings. */
+function _getNativeEditorDocumentHandleDescriptor(handle) {
+    _assertNativeEditorDocumentHandle(handle);
+    const documentDescriptor = exports.NATIVE_EDITOR_DOCUMENT_HANDLE_DESCRIPTORS.get(handle);
+    if (documentDescriptor === undefined) {
+        throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)('NativeEditorBridge: authentic NativeEditorDocumentHandle has no document descriptor');
+    }
+    return documentDescriptor;
+}
+/** @internal Source-module boundary assertion; intentionally absent from the package index. */
+function _assertNativeEditorDocumentHandle(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') ||
+        value === null ||
+        !exports.AUTHENTIC_NATIVE_EDITOR_DOCUMENT_HANDLES.has(value)) {
+        throw (0, NativeEditorResultNormalization_1.invalidV2RequestError)('NativeEditorBridge: expected an authentic NativeEditorDocumentHandle');
+    }
+}
+/**
+ * Create the native document session every other API binds to. Create it once
+ * per document — `useMemo`, not on each render — and destroy it when its
+ * owner unmounts.
+ *
+ * @throws NativeEditorErrorBase when the config is rejected: a malformed
+ * schema, an out-of-range limit, or content the engine cannot parse.
+ *
+ * @example
+ * ```ts
+ * const documentHandle = useMemo(
+ *     () => createNativeEditorDocumentHandle({
+ *         initialization: { type: 'localHtml', html: '<p>Hello world</p>' },
+ *     }),
+ *     []
+ * );
+ * useEffect(() => () => documentHandle.destroy(), [documentHandle]);
+ * ```
+ */
+function createNativeEditorDocumentHandle(config) {
+    const { configJson, snapshotState, documentDescriptor } = (0, NativeEditorCreateConfig_1.buildV2CreateRequest)(config);
+    const value = (0, NativeEditorResultNormalization_1.unwrapNativeEditorV2Result)((0, NativeEditorNativeModule_1.invokeNativeEditorV2)('editorV2Create', configJson, snapshotState), NativeEditorRenderNormalization_1.normalizeNativeEditorV2CreateValue);
+    return new NativeEditorDocumentHandleImpl(exports.NATIVE_EDITOR_DOCUMENT_HANDLE_TOKEN, value.editorId, new NativeEditorDocumentBridge_1.NativeEditorDocumentBridge(value.editorId), documentDescriptor);
+}

package/dist/NativeEditorLocalAwareness.d.ts

@@ -0,0 +1,34 @@
+import { type NativeEditorLocalAwarenessSelection } from './NativeEditorTypes';
+export declare const LOCAL_AWARENESS_INTENT_KEYS: Set<string>;
+export declare const LOCAL_AWARENESS_SELECTION_VALUES: WeakMap<object, Readonly<{
+    anchor: number;
+    head: number;
+}>>;
+export declare function invalidLocalAwarenessIntent(message?: string): never;
+/**
+ * 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.
+ */
+export declare function createNativeEditorLocalAwarenessSelection(anchor: number, head: number): NativeEditorLocalAwarenessSelection;
+export declare function isLocalAwarenessRecord(value: unknown): value is Record<string, unknown>;
+export declare function localAwarenessOwnDataValue(record: Record<string, unknown>, key: string): unknown;
+export declare function validateLocalAwarenessSelection(selection: unknown): {
+    anchor: number;
+    head: number;
+};
+/** Reject caller-owned sticky cursor data before a native call can occur. */
+export declare function rejectReservedAwarenessCursor(value: unknown): void;
+export declare function normalizeLocalAwarenessState(value: unknown): Record<string, unknown>;
+export interface NativeEditorLocalAwarenessWireIntent {
+    state: Record<string, unknown>;
+    focused: boolean;
+    /** Absent retains the Rust-owned cursor; `null` clears it. */
+    selection?: {
+        type: 'text';
+        anchor: number;
+        head: number;
+    } | null;
+}
+export declare function validateLocalAwarenessIntent(intent: unknown): NativeEditorLocalAwarenessWireIntent;
+export declare function serializeLocalAwarenessIntent(intent: NativeEditorLocalAwarenessWireIntent): string;