@web-ppt/collab 0.5.0-beta.2

package/dist/evaluate.d.ts

@@ -0,0 +1,16 @@
+import type { EditDoc, Patch } from '@web-ppt/edit-core';
+import type { CollaborationSession } from './state';
+import type { CollabMessage } from './types';
+export interface PatchAvailability {
+    readonly elements: Set<string>;
+    readonly slides: Set<string>;
+}
+export interface EvaluatedMessage {
+    readonly accepted: Patch[];
+    readonly recorded: Patch[];
+    readonly missingDependency: boolean;
+    readonly availability: PatchAvailability;
+}
+export declare function patchAvailability(patches: readonly Patch[], seed?: PatchAvailability): PatchAvailability;
+/** 纯读求值；任一依赖缺失时调用方必须延迟整条消息，不能提交其中的结构子集。 */
+export declare function evaluateRemoteMessage(doc: EditDoc, session: CollaborationSession, raw: CollabMessage, seed?: PatchAvailability): EvaluatedMessage;

package/dist/hierarchy-conflict.d.ts

@@ -0,0 +1,16 @@
+import type { EditDoc, ElementHierarchyPatch, ElementRecord, ElementTreePatch, Patch } from '@web-ppt/edit-core';
+declare const XFRM_FIELDS: readonly ["x", "y", "w", "h", "rot", "flipH", "flipV"];
+type HierarchyField = 'order' | typeof XFRM_FIELDS[number];
+export declare const hierarchyRecords: (patch: Patch) => Readonly<Record<string, ElementRecord | null>> | null;
+/** 删除成员不应被并发组合/解组复活；其 tombstone 同步迁到层级意图的目标父链。 */
+export declare function hierarchyWithoutRemovedMembers(doc: EditDoc, patch: ElementHierarchyPatch, removedIds: ReadonlySet<string>): ElementHierarchyPatch | null;
+/** 重叠结构意图只裁掉已被更新 stamp 接管的成员；不相交成员仍可交换合并。 */
+export declare function hierarchyWithoutNewerMembers(patch: ElementHierarchyPatch, newerIds: ReadonlySet<string>): ElementHierarchyPatch | null;
+/**
+ * 层级 patch 是命令时快照，不能直接覆盖并发后的整棵树：成员字段从当前模型重基，
+ * 同父级的不相交组合按 order 合并；重叠组合中落败的新组只保留未被赢家接管的孩子。
+ */
+export declare function rebaseElementHierarchy(doc: EditDoc, patch: ElementHierarchyPatch, applyField: (id: string, field: HierarchyField) => boolean): ElementHierarchyPatch;
+/** 层级并发已拆散原树时，转换成可删除多个现存分支的自包含层级 patch。 */
+export declare function rebaseElementRemoval(doc: EditDoc, patch: ElementTreePatch): ElementTreePatch | ElementHierarchyPatch | null;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** @web-ppt/collab —— 基于 EditDoc 补丁的无服务端协同适配层。 */
+export { bindCollaboration } from './binding';
+export { BroadcastChannelCollabProvider } from './broadcast-channel';
+export type { CollabDeferredCheckpoint, CollabLifecycleCheckpoint, CollabMessage, CollabMessageListener, CollabRegisterCheckpoint, CollabProvider, CollabSeenCheckpoint, CollabSlideMoveCheckpoint, CollabStamp, CollaborationBinding, CollaborationCheckpoint, CollaborationOptions, } from './types';

package/dist/message.d.ts

@@ -0,0 +1,6 @@
+import type { Patch } from '@web-ppt/edit-core';
+import type { CollabMessage, CollabStamp } from './types';
+export declare function compareStamp(left: CollabStamp, right: CollabStamp): number;
+export declare function assertCollabMessage(value: unknown): asserts value is CollabMessage;
+export declare const pathKey: (patch: Patch) => string;
+export declare const messageKey: (message: CollabMessage) => string;

package/dist/seen.d.ts

@@ -0,0 +1,15 @@
+import type { CollabMessage, CollabSeenCheckpoint } from './types';
+export declare const MAX_SEEN_REPLICAS = 4096;
+export declare const MAX_SEEN_GAPS = 10000;
+export interface SeenState {
+    contiguous: number;
+    readonly sparse: Set<number>;
+}
+export type SeenMap = Map<string, SeenState>;
+export declare function restoreSeen(entries?: readonly CollabSeenCheckpoint[]): SeenMap;
+export declare function cloneSeen(seen: SeenMap): SeenMap;
+export declare function checkpointSeen(seen: SeenMap): CollabSeenCheckpoint[];
+export declare function hasSeen(seen: SeenMap, message: CollabMessage): boolean;
+/** 高水位只代表连续收到；高于下一序号的消息必须先等缺口，不能越过同副本因果链落模。 */
+export declare function hasSequenceGap(seen: SeenMap, message: CollabMessage): boolean;
+export declare function markSeen(seen: SeenMap, message: CollabMessage): void;

package/dist/slide-conflict.d.ts

@@ -0,0 +1,3 @@
+import type { EditDoc, SlideTreePatch } from '@web-ppt/edit-core';
+/** 远端删页必须以接收端当前整页闭包落模，否则并发新增元素会变成孤儿。 */
+export declare function rebaseSlideRemoval(doc: EditDoc, patch: SlideTreePatch): SlideTreePatch | null;

package/dist/slide-order.d.ts

@@ -0,0 +1,5 @@
+import type { Patch } from '@web-ppt/edit-core';
+import type { SlideMove } from './state';
+export declare function desiredSlideOrder(base: readonly string[], members: ReadonlySet<string>, moves: ReadonlyMap<string, SlideMove>): string[];
+/** 把页序 intent 与本消息的增删页一起物化，确保一次 external recovery 就是最终顺序。 */
+export declare function materializeSlideOrder(currentOrder: readonly string[], desired: readonly string[], patches: readonly Patch[]): Patch[];

package/dist/state.d.ts

@@ -0,0 +1,57 @@
+import type { EditDoc, Patch } from '@web-ppt/edit-core';
+import type { SeenMap } from './seen';
+import type { CollabMessage, CollabStamp } from './types';
+export declare const hierarchyKey: (id: string) => string;
+export type Register = {
+    readonly stamp: CollabStamp;
+    readonly kind: 'field' | 'hierarchy';
+};
+export type Lifecycle = {
+    readonly stamp: CollabStamp;
+    readonly state: 'present' | 'removed';
+};
+export type SlideMove = {
+    readonly stamp: CollabStamp;
+    readonly after: string | null;
+    readonly ordinal: number;
+};
+export interface DeferredPatch {
+    readonly message: CollabMessage;
+    readonly patch: Patch;
+    readonly ordinal: number;
+}
+export interface CollaborationSession {
+    readonly documentId: string;
+    readonly replicaId: string;
+    readonly replicaSlot: number;
+    readonly registers: Map<string, Register>;
+    readonly elementLifecycles: Map<string, Lifecycle>;
+    readonly slideLifecycles: Map<string, Lifecycle>;
+    readonly slideMoves: Map<string, SlideMove>;
+    readonly seen: SeenMap;
+    readonly baseSlideOrder: readonly string[];
+    deferred: DeferredPatch[];
+    clock: number;
+    sequence: number;
+    active: boolean;
+}
+export declare const elementLifecycle: (patch: Patch) => {
+    id: string;
+    state: Lifecycle["state"];
+} | null;
+export declare const slideLifecycle: (patch: Patch) => {
+    id: string;
+    state: Lifecycle["state"];
+} | null;
+export declare const slideMove: (patch: Patch) => {
+    id: string;
+    after: string | null;
+} | null;
+export declare const elementHierarchy: (patch: Patch) => Readonly<Record<string, unknown>> | null;
+export declare const newer: (stamp: CollabStamp, current?: {
+    stamp: CollabStamp;
+}) => boolean;
+export declare function patchNewer(session: CollaborationSession, patch: Patch, stamp: CollabStamp): boolean;
+/** 同一原子消息共用 stamp；先按 ordinal 折叠末次意图，再与先前消息做严格 LWW。 */
+export declare function recordPatches(session: CollaborationSession, patches: readonly Patch[], stamp: CollabStamp): void;
+export declare function targetExists(doc: EditDoc, patch: Patch): boolean;

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import type { EditIdentity, Editor, EditorPatchEvent, Patch } from '@web-ppt/edit-core';
+export interface CollabStamp {
+    readonly clock: number;
+    readonly replicaId: string;
+}
+export interface CollabLifecycleCheckpoint {
+    readonly stamp: CollabStamp;
+    readonly state: 'present' | 'removed';
+}
+export interface CollabRegisterCheckpoint {
+    readonly stamp: CollabStamp;
+    readonly kind: 'field' | 'hierarchy';
+}
+export interface CollabSlideMoveCheckpoint {
+    readonly stamp: CollabStamp;
+    readonly after: string | null;
+    /** 同一消息内多次页序意图共用 stamp，以原 Patch 次序补足全序。 */
+    readonly ordinal: number;
+}
+export interface CollabDeferredCheckpoint {
+    readonly message: CollabMessage;
+    readonly patch: Patch;
+    readonly ordinal: number;
+}
+export interface CollabSeenCheckpoint {
+    readonly replicaId: string;
+    /** 已连续接收的最大消息序号；之前的消息无需逐条常驻。 */
+    readonly contiguous: number;
+    /** 高水位之后已收到的乱序消息；缺口闭合时会自动压缩。 */
+    readonly sparse: readonly number[];
+}
+/** 与 Editor recovery frames 同步持久化；模型快照本身无法重建 LWW 裁决元数据。 */
+export interface CollaborationCheckpoint {
+    readonly version: 1;
+    readonly documentId: string;
+    readonly replicaId: string;
+    readonly replicaSlot: number;
+    readonly clock: number;
+    readonly sequence: number;
+    readonly baseSlideOrder: readonly string[];
+    readonly registers: readonly (readonly [string, CollabRegisterCheckpoint])[];
+    readonly elementLifecycles: readonly (readonly [string, CollabLifecycleCheckpoint])[];
+    readonly slideLifecycles: readonly (readonly [string, CollabLifecycleCheckpoint])[];
+    readonly slideMoves: readonly (readonly [string, CollabSlideMoveCheckpoint])[];
+    readonly seen: readonly CollabSeenCheckpoint[];
+    readonly deferred: readonly CollabDeferredCheckpoint[];
+}
+/** 一条消息对应一个已经原子落模的 Editor 补丁批次。 */
+export interface CollabMessage {
+    readonly version: 1;
+    readonly documentId: string;
+    readonly replicaId: string;
+    readonly sequence: number;
+    readonly stamp: CollabStamp;
+    readonly patches: readonly Patch[];
+    readonly identity: EditIdentity;
+    readonly label: string;
+    readonly time: number;
+}
+export type CollabMessageListener = (message: CollabMessage) => void;
+/** provider 只搬运可结构化克隆的消息；鉴权、持久化和拓扑不进入模型层。 */
+export interface CollabProvider {
+    send(message: CollabMessage): void | Promise<void>;
+    subscribe(listener: CollabMessageListener): () => void;
+}
+export interface CollaborationOptions {
+    readonly documentId: string;
+    readonly replicaId: string;
+    /** provider 在同一文档内分配的唯一整数；隔离逻辑 id 与全部 OOXML 数值身份，范围 0–4095。 */
+    readonly replicaSlot: number;
+    readonly provider: CollabProvider;
+    /** 恢复过的 EditDoc 必须同时提供；新文档与同一 Editor 的 dispose/rebind 不需要。 */
+    readonly checkpoint?: CollaborationCheckpoint;
+    readonly onError?: (error: unknown) => void;
+}
+export interface CollaborationBinding {
+    readonly documentId: string;
+    readonly replicaId: string;
+    readonly editor: Editor;
+    checkpoint(): CollaborationCheckpoint;
+    dispose(): void;
+}
+export type LocalPatchEvent = EditorPatchEvent;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@web-ppt/collab",
+  "version": "0.5.0-beta.2",
+  "description": "Optional field-level LWW collaboration adapter for @web-ppt/edit-core with pluggable providers.",
+  "keywords": ["pptx", "powerpoint", "collaboration", "offline", "lww", "browser", "typescript"],
+  "license": "MIT",
+  "author": "unStone",
+  "homepage": "https://github.com/unStone/web-ppt#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unStone/web-ppt.git",
+    "directory": "packages/collab"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/collab.js",
+  "module": "./dist/collab.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/collab.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "prepack": "node ../../tooling/sync-package-docs.mjs"
+  },
+  "peerDependencies": {
+    "@web-ppt/edit-core": "^0.5.0-beta.2"
+  },
+  "publishConfig": { "access": "public" }
+}