```
### shared/types.ts
```ts
/** Example host language; independent of the documentation router. */
export type ExampleLocale = "zh-CN" | "en";
```
### collaboration/room.ts
```ts
import { createCollaborationSession, type CollaborationProviderFactory, type CollaborationProviderContext, type CollaborationPresenceTransport } from "@quirekit/msfe-collaboration";
import * as Y from "yjs";
import type { CollaborationDemoRoom } from "./types";
import { createPresenceRelay } from "./presence";
import { createCommentRelay } from "./comments";
import { createDemoActivity, type DemoMember } from "./activity";
/**
* Creates a same-page relay using the public provider contract. No network or durable storage is installed.
* @param source - Seed inserted exactly once by the room authority.
* @param members - Identities of the two participants, used as their authenticated connection contexts.
* @returns Two independent sessions and their shared disposable room.
*/
export function createDemoRoom(source: string, members: readonly [DemoMember, DemoMember] = [{ id: "a", name: "A" }, { id: "b", name: "B" }]): CollaborationDemoRoom {
const document = new Y.Doc();
document.getText("source").insert(0, source);
const clients = new Map();
const remote = Symbol("documentation-relay");
const presenceRelay = createPresenceRelay();
const activity = createDemoActivity("documentation-example", document);
// Only binary updates cross the relay. Editor presentation, selection and undo stacks stay local.
document.on("update", (update: Uint8Array, origin: unknown) => {
for (const [client] of clients) if (client !== origin) Y.applyUpdate(client, update, remote);
});
const provider = (member: DemoMember): CollaborationProviderFactory => context => {
let presence: CollaborationPresenceTransport | undefined;
const socketId = `${member.id}:${context.document.clientID}`;
/** @param update - Accepted local delta, including deletes. @param origin - Transport loop marker. */
function send(update: Uint8Array, origin: unknown): void {
if (origin === remote) return;
context.report({ synced: false });
Y.applyUpdate(document, update, context.document);
activity.changed(socketId, member);
// This acknowledges only delivery to this in-memory room; it is never a save receipt.
context.report({ synced: true });
}
/** Removes this connection only; the session keeps its document and local history. */
function disconnect(): void {
presence?.release(); presence = undefined;
context.document.off("update", send);
if (clients.delete(context.document)) activity.disconnected(socketId);
context.report({ connection: "disconnected", synced: false });
}
return {
/** @returns Ephemeral state channel only when an editor explicitly installs presence. */
acquirePresence() { presence?.release(); return presence = presenceRelay.acquire(String(context.document.clientID)); },
/** @param payload - Text for server-side extensions, here the activity extension's hints. @returns Whether it was delivered. */
sendStateless(payload) { if (!clients.has(context.document)) return false; activity.stateless(socketId, payload); return true; },
/** @param signal - Cancellable admission. @returns Fixed identity for this disposable room. */
async open(signal) {
signal.throwIfAborted();
return { documentId: context.documentId, epoch: "demo-1", permission: "write", sourceFormat: { bom: false, lineEnding: "\n" } };
},
/** @param _manifest - Validated admission. @param signal - Cancellable initial synchronization. @returns Completion after both branches merge. */
async connect(_manifest, signal) {
signal.throwIfAborted();
// Reconnection merges both offline branches with their original CRDT identities.
Y.applyUpdate(context.document, Y.encodeStateAsUpdate(document, Y.encodeStateVector(context.document)), remote);
activity.connected(socketId, member);
Y.applyUpdate(document, Y.encodeStateAsUpdate(context.document, Y.encodeStateVector(document)), context.document);
// Offline edits merged on reconnect are recorded for the member who made them.
activity.changed(socketId, member);
clients.set(context.document, context);
context.document.on("update", send);
context.report({ connection: "connected", synced: true });
},
disconnect,
destroy: disconnect,
};
};
const sessions = [
createCollaborationSession({ documentId: "documentation-example", provider: provider(members[0]) }),
createCollaborationSession({ documentId: "documentation-example", provider: provider(members[1]) }),
] as const;
// Comments travel through a separate room that follows each session's connection, as a host would wire it.
const comments = createCommentRelay(sessions, members, activity.comments);
let preparation: Promise | undefined;
let disposal: Promise | undefined;
return {
sessions, comments: comments.rooms,
activity: { store: activity.store, documentId: activity.documentId, versions: [activity.versionsFor(members[0]), activity.versionsFor(members[1])] },
/** @param signal - Page lifetime. @returns Both sessions ready for synchronous editor mounting. */
prepare(signal) {
return preparation ??= Promise.allSettled(sessions.map(session => session.prepare({ signal }))).then(results => {
const failure = results.find(result => result.status === "rejected");
if (failure?.status === "rejected") throw failure.reason;
});
},
/** @returns Completion after cancellation settles and all example resources are released. */
destroy() {
return disposal ??= (async () => {
// Capture an in-flight reconnect before disconnect cancels it; close requires preparation to settle.
const pending = sessions.filter(session => session.state.connection === "connecting").map(session => session.prepare());
sessions.forEach(session => session.disconnect());
await Promise.allSettled([...(preparation ? [preparation] : []), ...pending]);
// The page explicitly advertises disposable data. A real host must choose persist or checkpoint.
await Promise.all(sessions.map(session => session.close({ mode: "discard" })));
clients.clear(); activity.destroy(); document.destroy(); comments.destroy();
})();
},
};
}
```
### collaboration/types.ts
```ts
import type { Doc } from "yjs";
import type { CollaborationSession } from "@quirekit/msfe-collaboration";
import type { ActivityStore, VersionStore } from "@quirekit/edit-history";
/** Ephemeral room owned by this documentation example, with two independent clients. */
export interface CollaborationDemoRoom {
/** Prepared separately; neither editor shares the other's Y.Doc or history. */
readonly sessions: readonly [CollaborationSession, CollaborationSession];
/** Each client's replica of the comment room, synchronized only while its session is connected. */
readonly comments: readonly [Doc, Doc];
/** Server-confirmed activity records of the room, bounded in memory, and each member's view of the version API. */
readonly activity: { readonly store: ActivityStore; readonly documentId: string; readonly versions: readonly [VersionStore, VersionStore] };
/** @param signal - Page lifetime. @returns Completion after both clients receive the single seed. */
prepare(signal: AbortSignal): Promise;
/** @returns Completion after explicitly discarding the example; call after editors release their leases. */
destroy(): Promise;
}
```
### collaboration/presence.ts
```ts
import type { CollaborationPresenceTransport } from "@quirekit/msfe-collaboration";
/** @returns A disposable same-page presence channel; production transports must supply authenticated leases and timeouts. */
export function createPresenceRelay() {
const states = new Map(), listeners = new Set<() => void>();
/** Publishes the current in-memory snapshot without touching shared source or history. */
function notify(): void { for (const listener of listeners) listener(); }
return {
/** @param clientId - This room's unique document replica id. @returns One explicit ephemeral lease. */
acquire(clientId: string): CollaborationPresenceTransport {
let disposed = false;
const subscriptions = new Set<() => void>();
return {
clientId,
/** @returns Current room members; receivers exclude themselves and validate payloads. */
getStates() { return disposed ? new Map() : states; },
/** @param value - JSON-compatible display/selection state, or null to withdraw. */
publish(value) {
if (disposed) return;
if (value === null) states.delete(clientId); else states.set(clientId, JSON.parse(JSON.stringify(value)));
notify();
},
/** @param listener - Display state observer. @returns Unsubscribe callback. */
subscribe(listener) {
if (!disposed) { listeners.add(listener); subscriptions.add(listener); }
return () => { listeners.delete(listener); subscriptions.delete(listener); };
},
/** Immediately removes this member, since the in-process relay knows when its connection leaves. */
release() {
if (disposed) return; disposed = true;
for (const listener of subscriptions) listeners.delete(listener);
subscriptions.clear(); states.delete(clientId); notify();
},
};
},
};
}
```
### collaboration/comments.ts
```ts
import * as Y from "yjs";
import { Extension } from "@quirekit/msfe-core";
import { commentsState } from "@quirekit/msfe-comments";
import type { CollaborationSession } from "@quirekit/msfe-collaboration";
import type { DemoMember } from "./activity";
/** Server-side observers of the comment room, here the activity extension. */
export interface CommentRelayHooks {
/** @param room - Authority document. */ loaded(room: Y.Doc): void;
/** @param socketId - Replica connection. @param member - Its identity. */ connected(socketId: string, member: DemoMember): void;
/** @param room - Authority after the update. @param socketId - Sending replica. @param member - Its identity. */ changed(room: Y.Doc, socketId: string, member: DemoMember): void;
/** @param socketId - Closed replica connection. */ disconnected(socketId: string): void;
}
/**
* Same-page comment room: one authority document and a replica per session. A replica relays only while its
* session is connected, so disconnecting one side also keeps its comments offline until it reconnects.
* @param sessions - Example sessions, in replica order.
* @param members - Replica identities, in the same order.
* @param hooks - Optional server-side observers.
* @returns Replicas and a disposer.
*/
export function createCommentRelay(sessions: readonly CollaborationSession[], members?: readonly DemoMember[], hooks?: CommentRelayHooks) {
const authority = new Y.Doc(), remote = Symbol("comment-relay");
hooks?.loaded(authority);
const rooms = sessions.map(() => new Y.Doc()) as unknown as readonly [Y.Doc, Y.Doc];
const forwards = new Map void>();
authority.on("update", (update: Uint8Array, origin: unknown) => {
for (const room of forwards.keys()) if (room !== origin) Y.applyUpdate(room, update, remote);
});
/** @param room - Replica to connect; both offline branches merge first. */
const link = (room: Y.Doc, index: number) => {
if (forwards.has(room)) return;
const member = members?.[index], socketId = member ? `${member.id}:comments` : "";
Y.applyUpdate(room, Y.encodeStateAsUpdate(authority, Y.encodeStateVector(room)), remote);
if (member) hooks?.connected(socketId, member);
Y.applyUpdate(authority, Y.encodeStateAsUpdate(room, Y.encodeStateVector(authority)), room);
if (member) hooks?.changed(authority, socketId, member);
const forward = (update: Uint8Array, origin: unknown) => {
if (origin === remote) return;
Y.applyUpdate(authority, update, room);
if (member) hooks?.changed(authority, socketId, member);
};
forwards.set(room, forward); room.on("update", forward);
};
/** @param room - Replica to take offline. */
const unlink = (room: Y.Doc, index: number) => {
const forward = forwards.get(room);
if (!forward) return;
room.off("update", forward); forwards.delete(room);
const member = members?.[index];
if (member) hooks?.disconnected(`${member.id}:comments`);
};
const unsubscribe = sessions.map((session, index) => session.subscribe(state => {
if (state.connection === "connected") link(rooms[index]!, index); else unlink(rooms[index]!, index);
}));
return {
rooms,
/** Releases the relay and every replica. */
destroy(): void { unsubscribe.forEach(stop => stop()); rooms.forEach((room, index) => { unlink(room, index); room.destroy(); }); authority.destroy(); },
};
}
/**
* @param changed - Called after a transaction that changed comment state, including remote merges.
* @returns Editor extension feeding the example's comment panel.
*/
export function watchComments(changed: () => void) {
return Extension.create({
name: "exampleCommentsWatch",
/** @param event - Accepted transaction. */
onTransaction(event) { if (commentsState.read(event.transaction.startState) !== commentsState.read(event.transaction.state)) changed(); },
});
}
```
### collaboration/activity.ts
```ts
import { v4 as uuidv4 } from "uuid";
import type * as Y from "yjs";
import type { VersionStore } from "@quirekit/edit-history";
import { createMemoryActivityStore, createMemoryVersionStore } from "@quirekit/edit-history/memory";
import { createMsfeActivityExtension } from "@quirekit/msfe-collaboration-hocuspocus/server";
/** Participant identity the relay treats as an authenticated connection context. */
export interface DemoMember {
/** Stable member identity. */ readonly id: string;
/** Display name. */ readonly name: string;
}
/**
* Runs the real server-side activity extension inside the same-page relay. Records are bounded on every append
* (newest 200, content for one day), the way a production store should cap growth. Versions are checkpoints the
* host takes while storing the document, at most one per `checkpointMs`, plus named versions saved by members.
* @param documentName - Source room name; its comment room is `${documentName}:comments`.
* @param document - Relay authority document of the source room.
* @returns Hook feeds for both relays, the bounded store and a disposer.
*/
export function createDemoActivity(documentName: string, document: Y.Doc) {
const commentsName = `${documentName}:comments`;
const store = createMemoryActivityStore({ retention: { fullDays: 1, maxEvents: 200 } }), versions = createMemoryVersionStore();
const checkpointMs = 20_000, epoch = "demo-1";
let checkpointAt = 0, sequence = 0;
void versions.create({ documentId: documentName, epoch, sequence, trigger: "import" }, { format: "markdown", value: document.getText("source").toString() });
const extension = createMsfeActivityExtension({ mergeMs: 2000,
resolveActor: member => ({ id: member.id, name: member.name, trust: "verified" }),
commentsRoom: name => name === commentsName,
resolveDocument: name => name === documentName || name === commentsName ? { documentId: documentName, epoch: "demo-1" } : null });
void extension.afterLoadDocument({ documentName, document });
// Stands in for Hocuspocus's debounced document store: pending events are written together, failures retried.
const timer = setInterval(() => {
for (const name of [documentName, commentsName]) {
const events = extension.takeActivity(name);
if (!events.length) continue;
store.append(events).then(receipts => {
sequence = Math.max(sequence, ...receipts.map(receipt => receipt.sequence));
// The stored source becomes an automatic version; unchanged content reuses the latest one.
if (name !== documentName || Date.now() - checkpointAt < checkpointMs) return;
checkpointAt = Date.now();
void versions.create({ documentId: documentName, epoch, sequence, trigger: "auto" }, { format: "markdown", value: document.getText("source").toString() });
}, () => extension.restoreActivity(name, events));
}
}, 1000);
// In Node (documentation tests) the timer must not keep the process alive.
(timer as { unref?: () => void }).unref?.();
/**
* Stands in for the host's authenticated version API: the actor comes from the caller's identity, never from the
* request, and saving a named version is recorded as server-confirmed activity.
* @param member - Authenticated caller.
* @returns Version store bound to that caller.
*/
const versionsFor = (member: DemoMember): VersionStore => ({
list: query => versions.list(query),
read: id => versions.read(id),
async create(version, content) {
const actor = { id: member.id, name: member.name, trust: "verified" as const };
const record = await versions.create({ ...version, sequence, actor }, content);
// An automatic save may reuse an identical named version; only an explicit named save is recorded.
if (version.trigger === "named" && record.name) await store.append([{ documentId: documentName, epoch, operationId: uuidv4(), actor,
source: "human", kind: "version.create", kindVersion: 1, facts: { versionId: record.id, name: record.name } }]);
return record;
},
});
return { store, documentId: documentName, versionsFor,
/** @param socketId - Connection. @param member - Its identity. */
connected: (socketId: string, member: DemoMember) => void extension.connected({ documentName, socketId, context: member }),
/** @param socketId - Connection whose update was just applied to the authority. @param member - Its identity. */
changed: (socketId: string, member: DemoMember) => void extension.onChange({ documentName, document, socketId, context: member }),
/** @param socketId - Connection. @param payload - Stateless text, such as an activity hint. */
stateless: (socketId: string, payload: string) => void extension.onStateless({ documentName, payload, connection: { socketId } }),
/** @param socketId - Closed connection. */
disconnected: (socketId: string) => void extension.onDisconnect({ documentName, socketId }),
/** Comment room feeds: the room shares the source session, so it records comment actions but no joins. */
comments: {
/** @param room - Comment room authority document. */
loaded: (room: Y.Doc) => void extension.afterLoadDocument({ documentName: commentsName, document: room }),
/** @param socketId - Replica connection. @param member - Its identity. */
connected: (socketId: string, member: DemoMember) => void extension.connected({ documentName: commentsName, socketId, context: member }),
/** @param room - Comment room authority after the update. @param socketId - Sending replica. @param member - Its identity. */
changed: (room: Y.Doc, socketId: string, member: DemoMember) => void extension.onChange({ documentName: commentsName, document: room, socketId, context: member }),
/** @param socketId - Closed replica connection. */
disconnected: (socketId: string) => void extension.onDisconnect({ documentName: commentsName, socketId }),
},
/** Stops the store timer. */
destroy: () => clearInterval(timer),
};
}
```
### collaboration/messages.ts
```ts
/** Complete host copy; document language is selected once when the example is created. */
export const collaborationMessages = {
"zh-CN": {
title: "一起编辑同一份 Markdown",
note: "同页协同模拟 · 仅保存在内存，离开页面或刷新后清空。",
hint: "在任意一侧输入或拖选，另一侧会显示姓名光标与选区。虚线光标表示隐藏源码所在块；失焦后仍保留在线成员。选中文字后可添加评论，评论经独立房间同步，不写入 Markdown。",
comments: "评论", addComment: "评论选中内容", noComments: "选中文字后添加评论，另一侧会同步显示。",
collaborators: "协作者", waiting: "等待其他协作者加入", presenceOffline: "离线 · 协作者暂不可见", editing: "正在编辑", viewing: "在线",
left: "参与者 A", right: "参与者 B", leftEditor: "参与者 A 的 Markdown", rightEditor: "参与者 B 的 Markdown",
connected: "已同步", offline: "已断开", connecting: "正在连接", pending: "正在同步",
live: "实时预览", source: "源码", modes: "编辑模式", undo: "撤销", redo: "重做",
disconnect: "断开连接", reconnect: "重新连接", readOnly: "只读", readOnlyHint: "禁止本地修改，继续接收另一侧的更新。",
activity: "协作记录", activityNote: "由同页中继里的服务端扩展确认后写入，作者来自连接身份；只保留最近 200 条，改动片段保留 1 天，刷新即清空。",
versions: "历史版本", versionsNote: "服务端存档时每 20 秒最多生成一个自动版本，也可以保存命名版本；以参与者 A 的身份预览、对比和恢复，恢复会同步给 B 并记入协作记录。",
loading: "正在准备两个独立会话…", failed: "示例加载失败，请刷新页面重试。", connectionFailed: "连接失败，修改仍在当前页面，可重新连接。",
initial: "# 一起写作\n\n这是一份共享的 **Markdown** 文档。\n\n- 在左侧写下想法\n- 在右侧补充细节\n- 试试独立撤销和断线重连\n",
},
en: {
title: "Write the same Markdown together",
note: "Same-page simulation · Kept in memory; leaving or refreshing clears this example.",
hint: "Type or select on either side to see a named cursor and selection in the other. Dashed cursors mark hidden-source blocks. Members stay online after blur. Select text to comment; comments sync through a separate room and never enter the Markdown.",
comments: "Comments", addComment: "Comment on selection", noComments: "Select text and add a comment; it appears on the other side too.",
collaborators: "Collaborators", waiting: "Waiting for collaborators", presenceOffline: "Offline · Collaborators unavailable", editing: "Editing", viewing: "Online",
left: "Participant A", right: "Participant B", leftEditor: "Participant A Markdown", rightEditor: "Participant B Markdown",
connected: "Synced", offline: "Offline", connecting: "Connecting", pending: "Syncing",
live: "Live", source: "Source", modes: "Editor mode", undo: "Undo", redo: "Redo",
disconnect: "Disconnect", reconnect: "Reconnect", readOnly: "Read only", readOnlyHint: "Block local edits while receiving changes from the other side.",
activity: "Activity", activityNote: "Confirmed by the server extension in the same-page relay, with authors taken from the connection; only the newest 200 entries are kept, with changes for one day, and a refresh clears them.",
versions: "Versions", versionsNote: "The server takes at most one automatic version every 20 seconds while storing, and members can save named versions. Preview, compare and restore act as participant A; a restore reaches B and appears in the activity.",
loading: "Preparing two independent sessions…", failed: "The example could not load. Refresh the page to try again.", connectionFailed: "Connection failed. Your edits remain on this page; try reconnecting.",
initial: "# Write together\n\nThis is one shared **Markdown** document.\n\n- Add an idea on the left\n- Add details on the right\n- Try local undo and reconnecting\n",
},
} as const;
```
### collaboration/peer.vue
```vue
{{ text.noComments }}