@opengeni/sdk 0.48.0 → 0.57.0

package/dist/core.js

@@ -1,16 +1,21 @@
 import {
-  OPENGENI_API_CONTRACT_HEADER,
-  OPENGENI_API_CONTRACT_REVISION,
-  OpenGeniClient,
   resolveWorkspaceVoiceInputEnabled
-} from "./chunk-MBGBLVUV.js";
+} from "./chunk-VYCTL62C.js";
+import {
+  OpenGeniClient
+} from "./chunk-PKQ377ED.js";
+import {
+  OPENGENI_API_CONTRACT_HEADER,
+  OPENGENI_API_CONTRACT_REVISION
+} from "./chunk-HJ3HHUT5.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
   isRetryableStreamError
-} from "./chunk-V5F253OG.js";
+} from "./chunk-GU6JF75T.js";
+import "./chunk-ST5DDKJP.js";
 export {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,

package/dist/desktop.d.ts

@@ -1,4 +1,4 @@
-import type { DesktopStreamCapability, StreamUrlRotatedPayload } from "./types";
+import type { DesktopStreamCapability, StreamUrlRotatedPayload } from "./types.js";
 /**
  * Translate the negotiated desktop capability into the WebSocket URL the noVNC
  * RFB client connects to. The scoped provider token is ALREADY embedded in the
@@ -30,12 +30,20 @@ export interface DesktopRfbLike {
     clipViewport: boolean;
     addEventListener(type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void): void;
     removeEventListener?: (type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void) => void;
+    /** Send clipboard text over the already-open RFB connection. */
+    clipboardPasteFrom?(text: string): void;
+    /** Send one RFB key event. A missing `down` emits a complete key press. */
+    sendKey?(keysym: number, code: string, down?: boolean): void;
+    /** Focus or release the RFB keyboard sink without reconnecting. */
+    focus?(options?: FocusOptions): void;
+    blur?(): void;
     disconnect(): void;
 }
 export type DesktopRfbFactory = (target: HTMLElement, url: string, opts: {
     credentials?: {
         password?: string | undefined;
     } | undefined;
+    wsProtocols?: string[] | undefined;
 }) => DesktopRfbLike;
 export type DesktopConnectionState = "idle" | "negotiating" | "connecting" | "connected" | "rotating" | "reconnecting" | "error" | "ended";
 export type DesktopStreamEvent = {

package/dist/editable-artifact-resources.d.ts

@@ -0,0 +1,96 @@
+import type { OpenGeniRequestOptions } from "./client.js";
+import type { EditableArtifactModality } from "./editable-artifacts/types.js";
+/** Durable metadata returned by the editable-artifact product API. */
+export type EditableArtifactResource = Readonly<{
+    id: string;
+    modality: EditableArtifactModality;
+    title: string;
+    lifecycle: "active" | "archived";
+    headSequence: number;
+    stateHash: string;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type EditableArtifactListResource = Readonly<{
+    artifacts: readonly EditableArtifactResource[];
+}>;
+export type CreateEditableArtifactResourceRequest = Readonly<{
+    /** Stable across transport retries; conflicting reuse is rejected. */
+    idempotencyKey: string;
+    /** Exact writer replica that will open the first live editing session. */
+    replicaId: string;
+    modality: EditableArtifactModality;
+    title: string;
+}>;
+export type ImportEditableArtifactResourceRequest = Readonly<{
+    idempotencyKey: string;
+    replicaId: string;
+    modality: EditableArtifactModality;
+    title: string;
+    sourceFileId: string;
+}>;
+export type ReadEditableArtifactResourceOptions = OpenGeniRequestOptions & Readonly<{
+    /** Writer/read replica used to mint artifact-scoped authority. */
+    replicaId: string;
+}>;
+export type ListSessionEditableArtifactResourcesOptions = OpenGeniRequestOptions & Readonly<{
+    replicaId: string;
+}>;
+export type EditableArtifactMaterializationFormat = "xlsx" | "pptx" | "docx" | "pdf" | "png" | "webp";
+export type EditableArtifactPinnedVersionResource = Readonly<{
+    id: string;
+    artifactId: string;
+    modality: EditableArtifactModality;
+    snapshotId: string;
+    headSequence: number;
+    causalFrontier: readonly Readonly<{
+        replicaId: string;
+        counter: number;
+    }>[] | null;
+    nativeRevision: number | null;
+    stateHash: string;
+    name: string;
+    pinned: true;
+    createdAt: string;
+    replayed: boolean;
+}>;
+export type PinEditableArtifactVersionRequest = Readonly<{
+    replicaId: string;
+    idempotencyKey: string;
+    name: string;
+}>;
+export type EditableArtifactMaterializationResultResource = Readonly<{
+    id: string;
+    byteSize: number;
+    contentHash: string;
+    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/pdf" | "image/png" | "image/webp";
+    verifiedAt: string;
+    createdAt: string;
+}>;
+export type EditableArtifactMaterializationJobResource = Readonly<{
+    id: string;
+    artifactId: string;
+    versionId: string;
+    inputSnapshotId: string;
+    targetHeadSequence: number;
+    stateHash: string;
+    format: EditableArtifactMaterializationFormat;
+    state: "pending" | "running" | "succeeded" | "failed";
+    attemptCount: number;
+    errorCode: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    result: EditableArtifactMaterializationResultResource | null;
+    replayed?: boolean;
+}>;
+export type CreateEditableArtifactMaterializationRequest = Readonly<{
+    replicaId: string;
+    idempotencyKey: string;
+    versionId: string;
+    format: EditableArtifactMaterializationFormat;
+    options?: Readonly<Record<string, unknown>>;
+}>;
+export type ReadEditableArtifactMaterializationOptions = OpenGeniRequestOptions & Readonly<{
+    replicaId: string;
+}>;

package/dist/editable-artifacts/browser-session.d.ts

@@ -0,0 +1,35 @@
+import type { EditableArtifactCacheAuthority } from "./controller.js";
+import { type CreateEditableArtifactHttpLiveTransportOptions } from "./http-live-transport.js";
+import { type EditableArtifactSession } from "./session.js";
+import type { EditableArtifactStoragePort } from "./storage.js";
+import type { EditableArtifactModality } from "./types.js";
+import { type CreateBrowserEditableArtifactWorkerKernelOptions } from "./worker/browser-client.js";
+export type EditableArtifactBrowserRuntime = Omit<CreateBrowserEditableArtifactWorkerKernelOptions, "modality" | "kernelVersion" | "protocolVersion" | "modelSchemaVersion" | "commandVersion"> & Readonly<{
+    /** Exact native/WASM build identity admitted by the API. */
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    protocolVersion?: number;
+    commandVersion: number;
+}>;
+export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
+    baseUrl: string | URL;
+    workspaceId: string;
+    artifact: Readonly<{
+        id: string;
+        modality: EditableArtifactModality;
+    }>;
+    /** Exact login/grant partition; rotate authorizationEpoch on authority changes. */
+    storageAuthority: EditableArtifactCacheAuthority;
+    runtime: EditableArtifactBrowserRuntime;
+    transport?: Omit<CreateEditableArtifactHttpLiveTransportOptions, "baseUrl" | "workspaceId" | "protocolVersion" | "kernelVersion" | "modelSchemaVersion">;
+    storage?: EditableArtifactStoragePort;
+    /** Reuse the replica used to create the artifact when opening it immediately. */
+    replicaId?: string;
+}>;
+/**
+ * One production browser composition point: verified WASM Worker, durable WAL,
+ * authenticated HTTP/WebSocket transport, replay, and modality projections.
+ */
+export declare function createBrowserEditableArtifactSession(options: CreateBrowserEditableArtifactSessionOptions): EditableArtifactSession;
+/** Generates the portable 64-bit nonzero replica identity used by create/open. */
+export declare function createEditableArtifactReplicaId(): string;

package/dist/editable-artifacts/controller.d.ts

@@ -0,0 +1,60 @@
+import type { EditableArtifactStoragePort } from "./storage.js";
+import type { EditableArtifactId, EditableArtifactModality, EditableArtifactPendingTransaction, EditableArtifactSyncListener, EditableArtifactSyncScheduler, EditableArtifactSyncTransport, EditableArtifactSyncView, EditableArtifactWorkerKernel } from "./types.js";
+export type CreateEditableArtifactSyncControllerOptions = {
+    artifactId: EditableArtifactId;
+    modality: EditableArtifactModality;
+    /** Authenticated cache authority; every field participates in IndexedDB partitioning. */
+    storageAuthority: EditableArtifactCacheAuthority;
+    transport: EditableArtifactSyncTransport;
+    storage: EditableArtifactStoragePort;
+    kernel: EditableArtifactWorkerKernel;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    commandVersion: number;
+    protocolVersion?: number;
+    replayPageSize?: number;
+    maxQueuedMessages?: number;
+    maxQueuedBytes?: number;
+    maxStoredTailTransactions?: number;
+    maxSnapshotBytes?: number;
+    maxCommandBytes?: number;
+    maxCommittedTransactionBytes?: number;
+    maxReplayPageBytes?: number;
+    maxPendingTransactions?: number;
+    maxPendingBytes?: number;
+    minTicketTtlMs?: number;
+    reconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    maxReconnectAttempts?: number;
+    scheduler?: EditableArtifactSyncScheduler;
+    clientTransactionIdFactory?: () => string;
+    /** Tests/embedded runtimes may inject; defaults to a fresh per-controller UUID. */
+    writerReplicaIdFactory?: () => string;
+};
+export type EditableArtifactCacheAuthority = {
+    deploymentOrigin: string;
+    accountId: string;
+    workspaceId: string;
+    principalId: string;
+    /** Host-auth revision/session epoch; rotate on logout, grant change, or account switch. */
+    authorizationEpoch: string;
+};
+export type EditableArtifactQueueCommandsInput = {
+    commandBytes: Uint8Array;
+    selectiveUndoTargets?: readonly string[];
+    /** Optional deterministic ID for host-driven retries before WAL persistence. */
+    clientTransactionId?: string;
+};
+export type EditableArtifactSyncController = {
+    readonly artifactId: EditableArtifactId;
+    readonly modality: EditableArtifactModality;
+    start: () => void;
+    whenLive: () => Promise<void>;
+    close: () => Promise<void>;
+    getView: () => EditableArtifactSyncView;
+    subscribe: (listener: EditableArtifactSyncListener) => () => void;
+    /** Kernel authors/hashes the immutable envelope; SDK WAL persists before delivery. */
+    queueCommands: (input: EditableArtifactQueueCommandsInput) => Promise<EditableArtifactPendingTransaction>;
+};
+export declare function createEditableArtifactSyncController(options: CreateEditableArtifactSyncControllerOptions): EditableArtifactSyncController;
+export declare function editableArtifactCacheNamespace(authority: EditableArtifactCacheAuthority): string;

package/dist/editable-artifacts/errors.d.ts

@@ -0,0 +1,23 @@
+export type EditableArtifactSyncErrorCode = "unsupported_protocol" | "invalid_bootstrap" | "invalid_sequence" | "kernel_diverged" | "queue_overflow" | "resync_required" | "permission_changed" | "storage_failed" | "pending_conflict" | "reconnect_exhausted";
+export declare class EditableArtifactSyncError extends Error {
+    readonly code: EditableArtifactSyncErrorCode;
+    readonly retryable: boolean;
+    readonly requiresSnapshot: boolean;
+    constructor(code: EditableArtifactSyncErrorCode, message: string, options?: {
+        retryable?: boolean;
+        requiresSnapshot?: boolean;
+        cause?: unknown;
+    });
+}
+/** Transport adapters wrap retryable network failures in this typed error. */
+export declare class EditableArtifactTransportError extends Error {
+    readonly code: string | undefined;
+    readonly retryable: boolean;
+    readonly outcomeUnknown: boolean;
+    constructor(message: string, options?: {
+        code?: string;
+        retryable?: boolean;
+        outcomeUnknown?: boolean;
+        cause?: unknown;
+    });
+}

package/dist/editable-artifacts/http-live-transport.d.ts

@@ -0,0 +1,46 @@
+import type { EditableArtifactSyncTransport } from "./types.js";
+export type EditableArtifactWebSocketMessageEvent = Readonly<{
+    data: unknown;
+}>;
+export type EditableArtifactWebSocketCloseEvent = Readonly<{
+    code?: number;
+    reason?: string;
+}>;
+export type EditableArtifactWebSocketLike = {
+    binaryType: string;
+    readonly protocol: string;
+    readonly readyState: number;
+    send(data: Uint8Array | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: EditableArtifactWebSocketMessageEvent) => void): void;
+    addEventListener(type: "error", listener: () => void): void;
+    addEventListener(type: "close", listener: (event: EditableArtifactWebSocketCloseEvent) => void): void;
+    removeEventListener(type: "open", listener: () => void): void;
+    removeEventListener(type: "message", listener: (event: EditableArtifactWebSocketMessageEvent) => void): void;
+    removeEventListener(type: "error", listener: () => void): void;
+    removeEventListener(type: "close", listener: (event: EditableArtifactWebSocketCloseEvent) => void): void;
+};
+export type CreateEditableArtifactHttpLiveTransportOptions = Readonly<{
+    baseUrl: string | URL;
+    workspaceId: string;
+    protocolVersion: number;
+    kernelVersion: string;
+    modelSchemaVersion: number;
+    apiKey?: string;
+    headers?: Readonly<Record<string, string>> | (() => Readonly<Record<string, string>>);
+    credentials?: RequestCredentials;
+    fetch?: typeof fetch;
+    webSocketUrl?: string | URL;
+    webSocketFactory?: (url: string, protocol: string) => EditableArtifactWebSocketLike;
+    allowInsecureDevelopmentTransport?: boolean;
+    maximumServerFrameBytes?: number;
+    maximumSnapshotBytes?: number;
+    handshakeTimeoutMs?: number;
+    submitTimeoutMs?: number;
+}>;
+/**
+ * Production HTTP + authenticated binary WebSocket transport. The one-use
+ * ticket is sent only inside the first OGALV frame, never in the socket URL.
+ */
+export declare function createEditableArtifactHttpLiveTransport(options: CreateEditableArtifactHttpLiveTransportOptions): EditableArtifactSyncTransport;

package/dist/editable-artifacts/index.d.ts

@@ -0,0 +1,19 @@
+export { createEditableArtifactSyncController, editableArtifactCacheNamespace, type CreateEditableArtifactSyncControllerOptions, type EditableArtifactCacheAuthority, type EditableArtifactQueueCommandsInput, type EditableArtifactSyncController, } from "./controller.js";
+export { createBrowserEditableArtifactSession, createEditableArtifactReplicaId, } from "./browser-session.js";
+export type { CreateBrowserEditableArtifactSessionOptions, EditableArtifactBrowserRuntime, } from "./browser-session.js";
+export { EditableArtifactSyncError, EditableArtifactTransportError } from "./errors.js";
+export type { EditableArtifactSyncErrorCode } from "./errors.js";
+export { createEditableArtifactHttpLiveTransport } from "./http-live-transport.js";
+export type { CreateEditableArtifactHttpLiveTransportOptions, EditableArtifactWebSocketCloseEvent, EditableArtifactWebSocketLike, EditableArtifactWebSocketMessageEvent, } from "./http-live-transport.js";
+export { EditableArtifactStorageConflictError, IndexedDbEditableArtifactStorage, MemoryEditableArtifactStorage, } from "./storage.js";
+export type { EditableArtifactAppendCommittedInput, EditableArtifactExpectedStoredHead, EditableArtifactStoragePort, EditableArtifactStorageScope, IndexedDbEditableArtifactStorageOptions, } from "./storage.js";
+export { EditableArtifactSyncPool } from "./pool.js";
+export type { EditableArtifactSyncControllerFactory, EditableArtifactSyncLease } from "./pool.js";
+export { createEditableArtifactSession } from "./session.js";
+export type { CreateEditableArtifactSessionOptions, ApplySerializedArtifactCommandsOptions, ApplySpreadsheetCommandsOptions, CreateDocumentParagraphInput, CreateDocumentParagraphResult, CreatePresentationSlideInput, CreatePresentationSlideResult, CreateSpreadsheetSheetInput, CreateSpreadsheetSheetResult, EditableArtifactSession, EditableSpreadsheetMetadataListener, EditableSpreadsheetViewportListener, EditableSpreadsheetViewportSubscriptionOptions, } from "./session.js";
+export type { EditableArtifactBootstrap, EditableArtifactBlockedPending, EditableArtifactCausalEntry, EditableArtifactCausalFrontier, EditableArtifactCommittedTransaction, EditableArtifactId, EditableArtifactModality, EditableArtifactLiveClose, EditableArtifactLiveConnection, EditableArtifactLiveLimits, EditableArtifactLiveMessage, EditableArtifactPendingTransaction, EditableArtifactSerializedCommittedTransaction, EditableArtifactSerializedModality, EditableArtifactSerializedPendingTransaction, EditableArtifactSerializedSnapshot, EditableArtifactReplayPage, EditableArtifactSnapshot, EditableArtifactSpreadsheetCommittedTransaction, EditableArtifactSpreadsheetPendingTransaction, EditableArtifactSpreadsheetSnapshot, EditableArtifactStoredReplica, EditableArtifactSubmitReceipt, EditableArtifactSyncListener, EditableArtifactSyncScheduler, EditableArtifactSyncState, EditableArtifactSyncTicket, EditableArtifactSyncTransport, EditableArtifactSyncView, EditableArtifactWorkerKernel, EditableDocumentProjection, EditableDocumentQuery, EditablePresentationProjection, EditablePresentationQuery, EditablePresentationEditorSlideProjection, EditablePresentationEditorSlideQuery, EditablePresentationSlideCatalogProjection, EditablePresentationSlideCatalogQuery, EditableSpreadsheetCellValue, EditableSpreadsheetFormulaError, EditableSpreadsheetMetadataProjection, EditableSpreadsheetMetadataQuery, EditableSpreadsheetProjectedCell, EditableSpreadsheetSheetMetadata, EditableSpreadsheetUsedBounds, EditableSpreadsheetViewportProjection, EditableSpreadsheetViewportQuery, } from "./types.js";
+export { ArtifactWorkerClientError, createBrowserEditableArtifactWorkerKernel, } from "./worker/browser-client.js";
+export type { ArtifactWorkerClientEndpoint, ArtifactWorkerClientErrorEvent, ArtifactWorkerClientMessageEvent, BrowserEditableArtifactWorkerKernel, CreateBrowserEditableArtifactWorkerKernelOptions, } from "./worker/browser-client.js";
+export { SPREADSHEET_ARTIFACT_COMMAND_VERSION, editableArtifactStableId, spreadsheetSheetId, type SpreadsheetArtifactCommandBatch, type SpreadsheetCellInput, type SpreadsheetSheetGeneration, } from "@opengeni/contracts/spreadsheet-artifact-commands";
+export { DOCUMENT_ARTIFACT_COMMAND_VERSION, encodeDocumentArtifactCommandBatch, type DocumentArtifactCommand, type DocumentArtifactCommandBatch, type DocumentArtifactCommentReply, type DocumentArtifactId, type DocumentArtifactPageGeometry, type DocumentArtifactPageGeometryProjection, type DocumentArtifactParagraphStyle, type DocumentArtifactProjection, type DocumentArtifactProjectionItem, type DocumentArtifactQuery, type DocumentArtifactQueryLimits, type DocumentArtifactTableStyle, type DocumentArtifactTextRange, type DocumentArtifactTextRun, type DocumentArtifactTextStyle, type DocumentArtifactTextStylePatch, } from "@opengeni/contracts/document-artifact-commands";
+export { PRESENTATION_ARTIFACT_COMMAND_VERSION, PRESENTATION_ARTIFACT_QUERY_MAX_NODES, PRESENTATION_ARTIFACT_QUERY_MAX_SLIDES, PRESENTATION_ARTIFACT_QUERY_MAX_TEXT_BYTES, PRESENTATION_ARTIFACT_QUERY_RESPONSE_MAX_BYTES, encodePresentationArtifactCommandBatch, type PresentationArtifactEditorSceneNode, type PresentationArtifactEditorSlideResponse, type PresentationArtifactFill, type PresentationArtifactLine, type PresentationArtifactNodeKind, type PresentationArtifactOwner, type PresentationArtifactRect, type PresentationArtifactRichText, type PresentationArtifactCommand, type PresentationArtifactCommandBatch, type PresentationArtifactSlideCatalogItem, type PresentationArtifactSlideCatalogResponse, type PresentationArtifactSlideLayoutFacts, type PresentationArtifactTableCell, type PresentationArtifactTextParagraph, type PresentationArtifactTextRun, type PresentationArtifactTextStyle, type PresentationArtifactTransform, } from "@opengeni/contracts/presentation-artifact-commands";

package/dist/editable-artifacts/pool.d.ts

@@ -0,0 +1,15 @@
+import { type CreateEditableArtifactSyncControllerOptions, type EditableArtifactSyncController } from "./controller.js";
+import type { EditableArtifactId } from "./types.js";
+export type EditableArtifactSyncLease = {
+    controller: EditableArtifactSyncController;
+    release: () => void;
+};
+export type EditableArtifactSyncControllerFactory = (artifactId: EditableArtifactId) => CreateEditableArtifactSyncControllerOptions;
+/** Owns one ref-counted controller per exact auth/cache authority + artifact. */
+export declare class EditableArtifactSyncPool {
+    private readonly optionsFor;
+    private readonly entries;
+    constructor(optionsFor: EditableArtifactSyncControllerFactory);
+    acquire(artifactId: EditableArtifactId): EditableArtifactSyncLease;
+    get size(): number;
+}

package/dist/editable-artifacts/session.d.ts

@@ -0,0 +1,96 @@
+import { type SpreadsheetArtifactCommandBatch, type SpreadsheetSheetPrecondition } from "@opengeni/contracts/editable-artifacts";
+import { type DocumentArtifactCommandBatch, type DocumentArtifactParagraphStyle, type DocumentArtifactStoryTarget, type DocumentArtifactTextRun } from "@opengeni/contracts/document-artifact-commands";
+import { type PresentationArtifactCommandBatch, type PresentationArtifactFill } from "@opengeni/contracts/presentation-artifact-commands";
+import { type CreateEditableArtifactSyncControllerOptions, type EditableArtifactQueueCommandsInput } from "./controller.js";
+import type { EditableArtifactPendingTransaction, EditableArtifactModality, EditableDocumentProjection, EditableDocumentQuery, EditablePresentationProjection, EditablePresentationQuery, EditablePresentationEditorSlideProjection, EditablePresentationEditorSlideQuery, EditablePresentationSlideCatalogProjection, EditablePresentationSlideCatalogQuery, EditableArtifactSyncListener, EditableArtifactSyncView, EditableArtifactWorkerKernel, EditableSpreadsheetMetadataProjection, EditableSpreadsheetMetadataQuery, EditableSpreadsheetViewportProjection, EditableSpreadsheetViewportQuery } from "./types.js";
+export type CreateEditableArtifactSessionOptions = Omit<CreateEditableArtifactSyncControllerOptions, "kernel" | "storage"> & Readonly<{
+    /** Dedicated Worker client; canonical artifact state never enters the UI thread. */
+    worker: EditableArtifactWorkerKernel;
+    /** Defaults to the browser IndexedDB WAL/verified-replica store. */
+    storage?: CreateEditableArtifactSyncControllerOptions["storage"];
+    /** Close/dispose the Worker when this session closes. Defaults to true. */
+    ownsWorker?: boolean;
+}>;
+export type EditableSpreadsheetViewportListener = (projection: EditableSpreadsheetViewportProjection) => void;
+export type EditableSpreadsheetViewportSubscriptionOptions = Readonly<{
+    onError?: (error: Error) => void;
+}>;
+export type EditableSpreadsheetMetadataListener = (projection: EditableSpreadsheetMetadataProjection) => void;
+export type ApplySpreadsheetCommandsOptions = Readonly<{
+    selectiveUndoTargets?: readonly string[];
+    clientTransactionId?: string;
+}>;
+export type ApplySerializedArtifactCommandsOptions = Readonly<{
+    clientTransactionId?: string;
+}>;
+export type CreateSpreadsheetSheetInput = Readonly<{
+    name: string;
+    after?: SpreadsheetSheetPrecondition | null;
+    /** Optional stable id for a host retry; normally allocated by the SDK. */
+    sheetId?: string;
+    clientTransactionId?: string;
+}>;
+export type CreateSpreadsheetSheetResult = Readonly<{
+    sheetId: string;
+    pending: EditableArtifactPendingTransaction;
+}>;
+export type CreateDocumentParagraphInput = Readonly<{
+    target?: DocumentArtifactStoryTarget;
+    runs?: readonly DocumentArtifactTextRun[];
+    style?: DocumentArtifactParagraphStyle;
+    /** Optional stable id for a host retry; normally allocated by the SDK. */
+    paragraphId?: string;
+    clientTransactionId?: string;
+}>;
+export type CreateDocumentParagraphResult = Readonly<{
+    paragraphId: string;
+    pending: EditableArtifactPendingTransaction;
+}>;
+export type CreatePresentationSlideInput = Readonly<{
+    index: number;
+    title?: string;
+    layoutId?: string | null;
+    background?: PresentationArtifactFill;
+    /** Optional stable id for a host retry; normally allocated by the SDK. */
+    slideId?: string;
+    clientTransactionId?: string;
+}>;
+export type CreatePresentationSlideResult = Readonly<{
+    slideId: string;
+    pending: EditableArtifactPendingTransaction;
+}>;
+/**
+ * Public browser editing session. It owns sync, WAL recovery, live replay, and
+ * one Worker-resident speculative kernel. The main thread sees only bounded
+ * immutable projections and authored command receipts.
+ */
+export interface EditableArtifactSession {
+    readonly artifactId: string;
+    readonly modality: EditableArtifactModality;
+    start(): void;
+    whenReady(): Promise<void>;
+    close(): Promise<void>;
+    getView(): EditableArtifactSyncView;
+    subscribe(listener: EditableArtifactSyncListener): () => void;
+    queueCommands(input: EditableArtifactQueueCommandsInput): Promise<EditableArtifactPendingTransaction>;
+    /** Pure OGASC encoding followed by the ordinary Worker/WAL authoring path. */
+    applySpreadsheetCommands(batch: SpreadsheetArtifactCommandBatch, options?: ApplySpreadsheetCommandsOptions): Promise<EditableArtifactPendingTransaction>;
+    applyDocumentCommands(batch: DocumentArtifactCommandBatch, options?: ApplySerializedArtifactCommandsOptions): Promise<EditableArtifactPendingTransaction>;
+    applyPresentationCommands(batch: PresentationArtifactCommandBatch, options?: ApplySerializedArtifactCommandsOptions): Promise<EditableArtifactPendingTransaction>;
+    /** Allocates a collision-resistant offline sheet id and submits one OGASC create. */
+    createSpreadsheetSheet(input: CreateSpreadsheetSheetInput): Promise<CreateSpreadsheetSheetResult>;
+    /** Allocates a collision-resistant id in the document namespace and appends one paragraph. */
+    createDocumentParagraph(input?: CreateDocumentParagraphInput): Promise<CreateDocumentParagraphResult>;
+    /** Allocates a collision-resistant stable id and inserts one slide. */
+    createPresentationSlide(input: CreatePresentationSlideInput): Promise<CreatePresentationSlideResult>;
+    querySpreadsheetViewport(query: EditableSpreadsheetViewportQuery): Promise<EditableSpreadsheetViewportProjection>;
+    subscribeSpreadsheetViewport(query: EditableSpreadsheetViewportQuery, listener: EditableSpreadsheetViewportListener, options?: EditableSpreadsheetViewportSubscriptionOptions): () => void;
+    querySpreadsheetMetadata(query?: EditableSpreadsheetMetadataQuery): Promise<EditableSpreadsheetMetadataProjection>;
+    subscribeSpreadsheetMetadata(query: EditableSpreadsheetMetadataQuery, listener: EditableSpreadsheetMetadataListener, options?: EditableSpreadsheetViewportSubscriptionOptions): () => void;
+    queryDocument(query: EditableDocumentQuery): Promise<EditableDocumentProjection>;
+    queryPresentation(query: EditablePresentationQuery): Promise<EditablePresentationProjection>;
+    queryPresentationSlideCatalog(query: EditablePresentationSlideCatalogQuery): Promise<EditablePresentationSlideCatalogProjection>;
+    queryPresentationEditorSlide(query: EditablePresentationEditorSlideQuery): Promise<EditablePresentationEditorSlideProjection>;
+}
+/** Creates and starts one independently durable browser editing session. */
+export declare function createEditableArtifactSession(options: CreateEditableArtifactSessionOptions): EditableArtifactSession;

package/dist/editable-artifacts/storage.d.ts

@@ -0,0 +1,72 @@
+import type { EditableArtifactCommittedTransaction, EditableArtifactId, EditableArtifactModality, EditableArtifactPendingTransaction, EditableArtifactStoredReplica } from "./types.js";
+/** Durable browser state required to resume one artifact without inventing state. */
+export type EditableArtifactStoragePort = {
+    loadReplica: (scope: EditableArtifactStorageScope) => Promise<EditableArtifactStoredReplica | null>;
+    /** Rare full snapshot/resync replacement. Replaces the retained journal atomically. */
+    saveReplica: (scope: EditableArtifactStorageScope, replica: EditableArtifactStoredReplica, expectedHead: EditableArtifactExpectedStoredHead) => Promise<void>;
+    /** Hot path: exact-CAS one verified committed transaction onto the retained journal. */
+    appendCommitted: (scope: EditableArtifactStorageScope, input: EditableArtifactAppendCommittedInput) => Promise<void>;
+    /** Clears the reconstructible server state but deliberately preserves local edits. */
+    clearReplica: (scope: EditableArtifactStorageScope) => Promise<void>;
+    listPending: (scope: EditableArtifactStorageScope) => Promise<EditableArtifactPendingTransaction[]>;
+    putPending: (scope: EditableArtifactStorageScope, transaction: EditableArtifactPendingTransaction) => Promise<void>;
+    deletePending: (scope: EditableArtifactStorageScope, clientTransactionId: string) => Promise<void>;
+};
+/** Stable authorization/cache partition supplied by the authenticated host. */
+export type EditableArtifactStorageScope = {
+    namespace: string;
+    artifactId: EditableArtifactId;
+    modality: EditableArtifactModality;
+};
+export type EditableArtifactAppendCommittedInput = {
+    artifactId: EditableArtifactId;
+    expectedCursor: number;
+    expectedStateHash: string;
+    transaction: EditableArtifactCommittedTransaction;
+    updatedAt: number;
+};
+export type EditableArtifactExpectedStoredHead = Readonly<{
+    cursor: number;
+    stateHash: string;
+}> | null;
+/** A stable id was reused for different content. Retrying cannot resolve this. */
+export declare class EditableArtifactStorageConflictError extends Error {
+    readonly code: "editable_artifact_storage_conflict";
+    constructor(message: string);
+}
+/**
+ * Deterministic in-memory implementation for tests, SSR, and non-persistent
+ * hosts. All values cross the port by copy, matching IndexedDB structured-clone
+ * behavior and preventing callers from mutating retained authority by alias.
+ */
+export declare class MemoryEditableArtifactStorage implements EditableArtifactStoragePort {
+    #private;
+    loadReplica(scope: EditableArtifactStorageScope): Promise<EditableArtifactStoredReplica | null>;
+    saveReplica(scope: EditableArtifactStorageScope, replica: EditableArtifactStoredReplica, expectedHead: EditableArtifactExpectedStoredHead): Promise<void>;
+    appendCommitted(scope: EditableArtifactStorageScope, input: EditableArtifactAppendCommittedInput): Promise<void>;
+    clearReplica(scope: EditableArtifactStorageScope): Promise<void>;
+    listPending(scope: EditableArtifactStorageScope): Promise<EditableArtifactPendingTransaction[]>;
+    putPending(scope: EditableArtifactStorageScope, transaction: EditableArtifactPendingTransaction): Promise<void>;
+    deletePending(scope: EditableArtifactStorageScope, clientTransactionId: string): Promise<void>;
+}
+export type IndexedDbEditableArtifactStorageOptions = {
+    databaseName?: string;
+    indexedDB?: IDBFactory;
+};
+/**
+ * IndexedDB-backed browser storage. Writes that depend on an existing value do
+ * their comparison and mutation in the same IDB transaction, so tabs cannot
+ * silently replace a newer cursor or reuse an idempotency key for other bytes.
+ */
+export declare class IndexedDbEditableArtifactStorage implements EditableArtifactStoragePort {
+    #private;
+    constructor(options?: IndexedDbEditableArtifactStorageOptions);
+    loadReplica(scope: EditableArtifactStorageScope): Promise<EditableArtifactStoredReplica | null>;
+    saveReplica(scope: EditableArtifactStorageScope, replica: EditableArtifactStoredReplica, expectedHead: EditableArtifactExpectedStoredHead): Promise<void>;
+    appendCommitted(scope: EditableArtifactStorageScope, input: EditableArtifactAppendCommittedInput): Promise<void>;
+    clearReplica(scope: EditableArtifactStorageScope): Promise<void>;
+    listPending(scope: EditableArtifactStorageScope): Promise<EditableArtifactPendingTransaction[]>;
+    putPending(scope: EditableArtifactStorageScope, transaction: EditableArtifactPendingTransaction): Promise<void>;
+    deletePending(scope: EditableArtifactStorageScope, clientTransactionId: string): Promise<void>;
+    close(): Promise<void>;
+}