@p10node/office-engine 0.0.0 → 0.1.1

package/dist/types/collab/codec.d.ts

@@ -0,0 +1,3 @@
+/** JSON encoding that survives binary payloads (images inserted while collaborating). */
+export declare function encode(value: unknown): string;
+export declare function decode<T = unknown>(text: string): T;

package/dist/types/collab/docx.d.ts

@@ -0,0 +1,166 @@
+/**
+ * DOCX collaboration: operations on the main-thread paragraph model (DocxEditor),
+ * which mirrors every change to the worker itself.
+ *
+ *  - `text`   splice inside one paragraph (typing, deleting, inline formatting) — merges
+ *             character-wise with concurrent edits of the same paragraph
+ *  - `paras`  contiguous paragraphs replaced (Enter, join, paste, paragraph formatting…) — last writer wins
+ *  - `blocks` top-level blocks replaced (tables)
+ *  - `image` / `link`  package resources, shared by key (relationship ids differ per client)
+ *  - `call`   other document-level worker calls (e.g. adding a built-in style), run in hub order
+ */
+import type { Block, Inline, Paragraph } from '../core/docx/types';
+import type { DocumentClient } from '../core/worker/client';
+import type { Methods } from '../core/worker/protocol';
+import type { DocState, DocxEditor } from '../react/docx/DocxEditor';
+import type { Adapter, ApplyResult } from './session';
+export interface DocxHost {
+    editor: DocxEditor;
+    st: DocState;
+}
+/** top-level block identity: paragraph id, or table (regenerated id / original body item) */
+export type BKey = {
+    p: number;
+} | {
+    tid?: number;
+    item?: number;
+};
+export type DocxOp = {
+    t: 'text';
+    pid: number;
+    at: number;
+    del: number;
+    ins: Inline[];
+} | {
+    t: 'paras';
+    before: number[];
+    next: Paragraph[];
+} | {
+    t: 'blocks';
+    before: BKey[];
+    prev: BKey | null;
+    next: Block[];
+} | {
+    t: 'image';
+    key: string;
+    bytes: Uint8Array;
+    ext: string;
+} | {
+    t: 'link';
+    key: string;
+    url: string;
+} | {
+    t: 'call';
+    method: string;
+    args: unknown[];
+};
+/** a point in the document that survives structural edits: paragraph id, page-break part, offset */
+export interface DPos {
+    pid: number;
+    k: number;
+    o: number;
+}
+export interface DocxPresence {
+    k: 'docx';
+    a: DPos;
+    f: DPos;
+}
+/** how to undo one model change; `paras` with an empty `next` re-inserts `before` next to a neighbour */
+type Step = {
+    t: 'paras';
+    before: Paragraph[];
+    next: Paragraph[];
+    prev?: {
+        pid: number;
+        k: number;
+    };
+    after?: {
+        pid: number;
+        k: number;
+    };
+} | {
+    t: 'blocks';
+    before: Block[];
+    next: Block[];
+    prev: BKey | null;
+};
+/** the steps of an op, undone in reverse order */
+type Undo = Step[] | null;
+/** single replaced range between two run lists (common prefix / suffix, formatting included) */
+export declare function diffRuns(a: Inline[], b: Inline[]): {
+    at: number;
+    del: number;
+    ins: Inline[];
+} | null;
+export declare function spliceRuns(runs: Inline[], at: number, del: number, ins: Inline[]): Inline[];
+export declare class DocxCollab implements Adapter<DocxOp> {
+    private client;
+    private host?;
+    /** > 0 while this adapter drives the editor (its commits are not local ops) */
+    private suppress;
+    /** resource key → this client's value ({ rid, path } for images, link key for links) */
+    private res;
+    /** this client's rid / link key → resource key */
+    private resKey;
+    private results;
+    private snap;
+    /** the model was changed since the last `settled` */
+    private touchedModel;
+    private site;
+    private counter;
+    private offHost?;
+    /** sends presence (set by the session owner) */
+    onPresence?: (p: DocxPresence) => void;
+    private lastPresence;
+    private raf;
+    /** registers a local op the editor already applied */
+    push?: (op: DocxOp, undo: Undo) => void;
+    /** shares a local op through the session (applied by `apply`) */
+    submit?: (op: DocxOp) => Promise<unknown>;
+    constructor(client: DocumentClient);
+    ready(): Promise<void>;
+    /** gives this client its own range of paragraph / table ids */
+    setSite(site: number): void;
+    private allocPids;
+    dispose(): void;
+    captures(method: keyof Methods): boolean;
+    /** client.call interceptor: package resources and document-level calls become ops */
+    intercept(method: keyof Methods, args: unknown[]): Promise<unknown> | undefined;
+    private key;
+    private get st();
+    private get ed();
+    /** every block of paragraph `pid` (page-break parts) with its address */
+    private locate;
+    private topIndex;
+    /** contiguous paragraph addresses from the first block of pids[0], following `pids` */
+    private region;
+    private remap;
+    /** tags runs referring to resources this client created, so others can map them */
+    private tag;
+    private fetchRes;
+    private onCommit;
+    transform(op: DocxOp, prior: DocxOp): DocxOp | null;
+    private touched;
+    conflicts(pending: DocxOp[], remote: DocxOp[]): boolean;
+    pessimistic(op: DocxOp): boolean;
+    prepare(ops: DocxOp[]): Promise<void>;
+    apply(op: DocxOp, kind: 'local' | 'replay' | 'remote'): Promise<ApplyResult>;
+    /** applies a model op through the editor; returns how to revert it */
+    private run;
+    revert(undo: unknown): void;
+    private undoStep;
+    private toD;
+    private fromD;
+    /** remembers the selection (by paragraph id + text) before the model changes */
+    private capture;
+    /** the remembered selection in the current model */
+    private sel;
+    settled(): void;
+    private onSel;
+    /** screen rectangles of a collaborator's selection (caret = last rect) inside `root` */
+    rects(root: HTMLElement, p: DocxPresence): {
+        caret: DOMRect | null;
+        sel: DOMRect[];
+    };
+}
+export {};

package/dist/types/collab/hosts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Views register their live editing objects here so a collaboration session
+ * (created independently, e.g. by DocViewer) can reach them. Tiny on purpose:
+ * views import only this file.
+ */
+/** registers `host` for (client, kind); returns the unregister function */
+export declare function registerHost<T>(client: object, kind: string, host: T): () => void;
+export declare function getHost<T>(client: object, kind: string): T | undefined;
+/** calls `fn` with the current host and every host registered later */
+export declare function watchHost<T>(client: object, kind: string, fn: (host: T) => void): () => void;
+export interface PeerView {
+    site: number;
+    name: string;
+    color: string;
+    presence?: unknown;
+}
+/** session → views: collaborators and where they are */
+export declare function setPeers(client: object, peers: PeerView[]): void;
+/** stable between changes (usable as a useSyncExternalStore snapshot) */
+export declare function getPeers(client: object): PeerView[];
+export declare function subscribePeers(client: object, fn: () => void): () => void;
+/** views → session: the local user's position (selection, active slide…) */
+export declare function publishLocal(client: object, data: unknown): void;
+export declare function onLocal(client: object, fn: (data: unknown) => void): () => void;

package/dist/types/collab/hub.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Runtime-agnostic collaboration hub: one sequencer + op log per room.
+ * Wire it to any socket server (see scripts/collab-server.ts for Bun):
+ *
+ *   const conn = hub.connect((msg) => socket.send(encode(msg)))
+ *   socket.onmessage = (e) => conn.receive(decode(e.data))
+ *   socket.onclose = () => conn.close()
+ */
+import { type Batch, type ClientMsg, type HubMsg, type PeerInfo } from './protocol';
+export interface RoomState {
+    id: string;
+    seq: number;
+    log: Batch[];
+    ids: Set<string>;
+    peers: Map<number, {
+        info: PeerInfo;
+        send: (m: HubMsg) => void;
+    }>;
+    nextSite: number;
+}
+export interface HubOptions {
+    /** called for every sequenced batch (persist it to rebuild rooms after a restart) */
+    onBatch?: (room: string, batch: Batch) => void;
+    /** rebuilds a room log (e.g. from storage) the first time the room is used */
+    loadLog?: (room: string) => Batch[] | undefined;
+    /** called when the last peer left a room */
+    onIdle?: (room: string) => void;
+}
+export interface HubConnection {
+    receive(msg: ClientMsg): void;
+    close(): void;
+}
+export declare class CollabHub {
+    private opts;
+    readonly rooms: Map<string, RoomState>;
+    constructor(opts?: HubOptions);
+    room(id: string): RoomState;
+    /** forgets a room (its log and peers) — e.g. when a new base file is uploaded */
+    reset(id: string): void;
+    connect(send: (m: HubMsg) => void): HubConnection;
+}

package/dist/types/collab/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Real-time collaboration for office-engine documents.
+ *
+ *   const collab = startCollab(client, { transport: 'wss://host/collab', room: 'doc-42', user: { name: 'Ann' } })
+ *   collab.on('status', console.log)
+ *   collab.close()
+ *
+ * Every participant must open the same base file; the hub keeps the operation log on top of it.
+ * DocViewer does all of this through its `collab` prop.
+ */
+import type { DocumentClient } from '../core/worker/client';
+import { type PeerView } from './hosts';
+import type { PeerInfo, UserInfo } from './protocol';
+import { CollabSession, type CollabStatus, type SessionEvents } from './session';
+import { type Transport } from './transport';
+export interface CollabOptions {
+    /** hub connection: a WebSocket URL or any Transport */
+    transport: Transport | string;
+    /** shared document id */
+    room: string;
+    user: UserInfo;
+}
+export interface Collab {
+    readonly session: CollabSession<unknown>;
+    readonly status: CollabStatus;
+    /** collaborators currently connected (without the local user) */
+    readonly peers: PeerInfo[];
+    /** local operations not yet confirmed by the hub */
+    readonly pending: number;
+    on<K extends keyof SessionEvents>(event: K, fn: (d: SessionEvents[K]) => void): () => void;
+    /** screen rectangles of a collaborator's DOCX selection (for custom overlays) */
+    rects(root: HTMLElement, peer: PeerView): {
+        caret: DOMRect | null;
+        sel: DOMRect[];
+    } | null;
+    close(): void;
+}
+export declare function startCollab(client: DocumentClient, opts: CollabOptions): Collab;
+export { CollabHub, type HubOptions, type HubConnection } from './hub';
+export { CollabSession, type Adapter, type CollabStatus } from './session';
+export { MemoryTransport, WebSocketTransport, type Transport, type TransportStatus } from './transport';
+export type { Batch, ClientMsg, HubMsg, PeerInfo, UserInfo } from './protocol';
+export { encode, decode } from './codec';

package/dist/types/collab/pptx-ops.d.ts

@@ -0,0 +1,60 @@
+/** PPTX collaboration operations. Slides are addressed by part path (indexes move), shapes by element id. */
+import type { PParaSpec, ShapeOp } from '../core/pptx/types';
+export type PSlideOp = {
+    op: 'add';
+    after: string | null;
+    layout?: 'title' | 'content' | 'blank';
+} | {
+    op: 'duplicate';
+    path: string;
+} | {
+    op: 'delete';
+    path: string;
+} | {
+    op: 'move';
+    path: string;
+    to: number;
+} | {
+    op: 'hide';
+    path: string;
+    hidden: boolean;
+};
+export type POp = 
+/** whole text of shape `sid` (last writer wins per shape) */
+{
+    t: 'text';
+    id: string;
+    slide: string;
+    sid: number;
+    paras: PParaSpec[];
+}
+/** shape edits; an inserted picture refers to its image by `key` */
+ | {
+    t: 'shapes';
+    id: string;
+    slide: string;
+    ops: (ShapeOp & {
+        key?: string;
+    })[];
+} | {
+    t: 'image';
+    id: string;
+    key: string;
+    slide: string;
+    bytes: Uint8Array;
+    ext: string;
+} | {
+    t: 'slides';
+    id: string;
+    op: PSlideOp;
+}
+/** puts the slide touched by op `target` back to its state before (`prev`) / after (`next`) it */
+ | {
+    t: 'revert';
+    id: string;
+    target: string;
+    which: 'prev' | 'next';
+};
+export declare function transformP(op: POp, prior: POp): POp | null;
+/** whether remote ops interact with pending local ones (→ rebase) */
+export declare function conflictsP(pending: POp[], remote: POp[]): boolean;

package/dist/types/collab/pptx-worker.d.ts

@@ -0,0 +1,35 @@
+import type { PptxPresentation } from '../core/pptx/parser';
+import type { PresentationMeta, SlideModel } from '../core/pptx/types';
+import type { POp } from './pptx-ops';
+export interface PptxCollabResult {
+    /** slide index + its new model */
+    slide?: number;
+    model?: SlideModel;
+    /** slide list changed */
+    meta?: PresentationMeta;
+    /** image relationship id (image ops) */
+    rid?: string;
+}
+export declare class PptxCollabWorker {
+    private pres;
+    private recs;
+    private byOp;
+    private seq;
+    /** image key → relationship id, per slide */
+    private images;
+    constructor(pres: PptxPresentation);
+    /** text templates of every slide, taken in the shared state (before any op / right after slide-list changes) */
+    private originals;
+    private ready?;
+    private index;
+    private get genMaps();
+    private snap;
+    private restore;
+    private model;
+    apply(op: POp): Promise<{
+        res: PptxCollabResult;
+        rec: number | null;
+    }>;
+    /** exactly undoes an applied operation (rebase) */
+    revert(id: number): Promise<PptxCollabResult>;
+}

package/dist/types/collab/pptx.d.ts

@@ -0,0 +1,47 @@
+import type { DocumentClient } from '../core/worker/client';
+import type { Methods } from '../core/worker/protocol';
+import { type POp } from './pptx-ops';
+import type { Adapter, ApplyResult } from './session';
+export interface PptxPresence {
+    k: 'pptx';
+    /** slide part path */
+    slide: string;
+    /** selected element id */
+    top?: number;
+}
+/** what PptxView publishes about the local selection */
+export interface PptxLocalSel {
+    slide: number;
+    top?: number;
+}
+/** PptxView registers this so remote slide-list changes can close its text editing first */
+export interface PptxHost {
+    endEditing(): void;
+}
+export declare class PptxCollab implements Adapter<POp> {
+    private client;
+    submit?: (op: POp) => Promise<unknown>;
+    nextId?: () => string;
+    onPresence?: (p: PptxPresence) => void;
+    private undoStack;
+    private redoStack;
+    /** this client's image relationship id → image key */
+    private ridKey;
+    private offLocal;
+    constructor(client: DocumentClient);
+    dispose(): void;
+    private get meta();
+    private path;
+    private id;
+    captures(method: keyof Methods): boolean;
+    intercept(method: keyof Methods, args: unknown[]): Promise<unknown> | undefined;
+    private pslide;
+    private local;
+    private history;
+    transform(op: POp, prior: POp): POp | null;
+    conflicts(pending: POp[], remote: POp[]): boolean;
+    pessimistic(op: POp): boolean;
+    prepare(ops: POp[]): void;
+    apply(op: POp, kind: 'local' | 'replay' | 'remote'): Promise<ApplyResult>;
+    revert(undo: unknown): Promise<void>;
+}

package/dist/types/collab/protocol.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Wire protocol between collaboration clients and a hub (sequencer).
+ *
+ * The hub is format-agnostic: it assigns a global sequence number to every
+ * batch of operations, stores the log and relays presence. All transformation
+ * and conflict handling happens in the clients, deterministically, so every
+ * client that applies the log ends up with the same document.
+ */
+export interface UserInfo {
+    /** stable user id (optional, for the host app) */
+    id?: string;
+    name: string;
+    /** CSS color; the hub assigns one when missing */
+    color?: string;
+}
+export interface PeerInfo extends UserInfo {
+    /** per-room connection id, assigned by the hub */
+    site: number;
+    color: string;
+    presence?: unknown;
+}
+/** A batch of operations as stored in the hub log. */
+export interface Batch<Op = unknown> {
+    seq: number;
+    site: number;
+    /** last seq the author had applied when creating the batch */
+    base: number;
+    /** client generated id (dedupes resends after reconnects) */
+    id: string;
+    ops: Op[];
+}
+export type ClientMsg = 
+/** join a room; `have`/`site` on reconnect */
+{
+    t: 'hello';
+    room: string;
+    user: UserInfo;
+    have?: number;
+    site?: number;
+} | {
+    t: 'ops';
+    id: string;
+    base: number;
+    ops: unknown[];
+} | {
+    t: 'presence';
+    data: unknown;
+};
+export type HubMsg = 
+/** `log` holds every batch with seq > `from`; `reset` when the hub lost history newer than `have` */
+{
+    t: 'welcome';
+    site: number;
+    seq: number;
+    from: number;
+    log: Batch[];
+    peers: PeerInfo[];
+    reset?: boolean;
+} | {
+    t: 'batch';
+    b: Batch;
+} | {
+    t: 'presence';
+    site: number;
+    data: unknown;
+} | {
+    t: 'join';
+    peer: PeerInfo;
+} | {
+    t: 'leave';
+    site: number;
+} | {
+    t: 'error';
+    message: string;
+};
+export declare const PEER_COLORS: string[];

package/dist/types/collab/react.d.ts

@@ -0,0 +1,23 @@
+import type { DocumentClient } from '../core/worker/client';
+import { type Collab, type CollabOptions } from './index';
+import type { CollabStatus } from './session';
+export interface CollabState {
+    collab: Collab | null;
+    status: CollabStatus | null;
+    error?: string;
+}
+/** runs a collaboration session for `client` while `opts` is set */
+export declare function useCollab(client: DocumentClient | null | undefined, opts: CollabOptions | undefined): CollabState;
+/** status chip + collaborators' avatars (top bar) */
+export declare function CollabBar({ client, state }: {
+    client: DocumentClient;
+    state: CollabState;
+}): import("react").JSX.Element | null;
+/**
+ * Collaborators' cursors drawn over the document (DOCX carets / selections, PPTX selected shapes).
+ * Spreadsheets draw their own (in-grid) selection boxes. Render inside a positioned container.
+ */
+export declare function PeerOverlay({ client, collab }: {
+    client: DocumentClient;
+    collab: Collab | null;
+}): import("react").JSX.Element;

package/dist/types/collab/session.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Client side of the collaboration protocol (format-agnostic).
+ *
+ * Model: the hub totally orders batches of operations. Every client applies
+ * the log in that order, each batch first transformed (deterministically)
+ * against the concurrent batches sequenced before it — so all clients reach
+ * the same state. Local operations are applied optimistically; when a remote
+ * batch arrives while local ones are still unconfirmed, the client rebases:
+ * reverts its pending ops, applies the remote batch, then replays the pending
+ * ops transformed against it. Convergence therefore only needs `transform` and
+ * `apply` to be deterministic (not the classic OT TP1/TP2 properties).
+ *
+ * Operations an adapter flags as `pessimistic` (structural ones that are hard
+ * to rebase, like deleting a sheet) are not applied locally until the hub has
+ * sequenced them.
+ */
+import type { PeerInfo, UserInfo } from './protocol';
+import type { Transport } from './transport';
+export interface ApplyResult {
+    /** whatever `revert` needs to undo the op exactly (local ops only) */
+    undo?: unknown;
+    /** returned to the caller of `submit` */
+    result?: unknown;
+}
+export type ApplyKind = 'local' | 'replay' | 'remote';
+export interface Adapter<Op> {
+    /** resolves when the document can take operations (e.g. fully loaded) */
+    ready?(): Promise<void>;
+    /**
+     * `op` adjusted to apply after `prior`, a concurrent op of another site that was sequenced first.
+     * Must be deterministic; return `op` itself when unaffected, null to drop it.
+     */
+    transform(op: Op, prior: Op): Op | null;
+    /**
+     * Async work before ops get applied (fetching resources, waiting for IME composition to end…),
+     * so that `revert` / `apply` during a rebase can run without yielding to user input.
+     */
+    prepare?(ops: Op[]): Promise<void> | void;
+    /** applies `op` to the local document */
+    apply(op: Op, kind: ApplyKind): Promise<ApplyResult> | ApplyResult;
+    /** exactly undoes a pending local op (given its `undo` token) */
+    revert(undo: unknown): Promise<void> | void;
+    /** op must be sequenced by the hub before it is applied */
+    pessimistic?(op: Op): boolean;
+    /** whether remote ops interact with pending local ones (default: true → rebase) */
+    conflicts?(pending: Op[], remote: Op[]): boolean;
+    /** after a remote batch / rebase was applied (views refresh here) */
+    settled?(): void;
+}
+export type CollabStatus = 'connecting' | 'syncing' | 'live' | 'offline' | 'error';
+export interface SessionEvents {
+    status: CollabStatus;
+    peers: PeerInfo[];
+    /** remote changes were applied */
+    change: void;
+    error: Error;
+}
+export interface SessionOptions {
+    room: string;
+    user: UserInfo;
+    /** canonical batches kept to transform late batches (default 5000) */
+    logWindow?: number;
+}
+export declare class CollabSession<Op = unknown> {
+    private transport;
+    private adapter;
+    private opts;
+    site: number;
+    /** last applied sequence number */
+    rev: number;
+    status: CollabStatus;
+    error?: string;
+    readonly peers: Map<number, PeerInfo>;
+    private log;
+    private inflight;
+    private buffer;
+    private queue;
+    private joined;
+    private online;
+    private counter;
+    private listeners;
+    private presence;
+    private presenceTimer?;
+    private presenceAt;
+    private closed;
+    constructor(transport: Transport, adapter: Adapter<Op>, opts: SessionOptions);
+    /** local ops not yet confirmed by the hub */
+    get pending(): number;
+    /** a unique id for ops created by this client */
+    nextId(): string;
+    /** applies a local op (through the adapter) and shares it; resolves with the adapter's result */
+    submit(op: Op): Promise<unknown>;
+    /** registers a local op the caller already applied (synchronously); `undo` reverts it */
+    push(op: Op, undo: unknown): void;
+    setPresence(data: unknown): void;
+    on<K extends keyof SessionEvents>(event: K, fn: (d: SessionEvents[K]) => void): () => void;
+    /** resolves once everything queued so far was processed */
+    idle(): Promise<void>;
+    close(): void;
+    private emit;
+    private setStatus;
+    private fail;
+    private enqueue;
+    private onMessage;
+    private onBatch;
+    /** batch ops transformed against the concurrent batches sequenced before it */
+    private canonical;
+    private revertAll;
+    private replay;
+    private remote;
+    private applyRemote;
+    /** our in-flight batch was sequenced */
+    private ack;
+    private flush;
+}

package/dist/types/collab/transport.d.ts

@@ -0,0 +1,47 @@
+import type { CollabHub } from './hub';
+import type { ClientMsg, HubMsg } from './protocol';
+export type TransportStatus = 'connecting' | 'open' | 'closed';
+/** Message pipe to a hub. Implement it to plug collaboration into your own backend. */
+export interface Transport {
+    connect(): void;
+    send(msg: ClientMsg): void;
+    close(): void;
+    onMessage?: (msg: HubMsg) => void;
+    onStatus?: (s: TransportStatus) => void;
+}
+/** WebSocket transport with automatic reconnection (exponential backoff). */
+export declare class WebSocketTransport implements Transport {
+    private url;
+    private protocols?;
+    onMessage?: (msg: HubMsg) => void;
+    onStatus?: (s: TransportStatus) => void;
+    private ws?;
+    private closed;
+    private retry;
+    private timer?;
+    constructor(url: string, protocols?: string | string[] | undefined);
+    connect(): void;
+    private open;
+    send(msg: ClientMsg): void;
+    close(): void;
+}
+/**
+ * In-process transport to a `CollabHub` (tests, demos with several viewers on one page).
+ * Messages go through the JSON codec and are delivered asynchronously, optionally with latency.
+ */
+export declare class MemoryTransport implements Transport {
+    private hub;
+    private latency;
+    onMessage?: (msg: HubMsg) => void;
+    onStatus?: (s: TransportStatus) => void;
+    private conn?;
+    private up;
+    private down;
+    constructor(hub: CollabHub, latency?: number | (() => number));
+    private delay;
+    connect(): void;
+    send(msg: ClientMsg): void;
+    /** simulates a dropped connection (messages in flight are lost) */
+    drop(): void;
+    close(): void;
+}