@adonis-agora/collaboration 0.12.0 → 0.13.0

package/dist/src/auth/token.js

@@ -1,6 +1,31 @@
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { resolveTokenSecret } from './secret.js';
+/**
+ * Lifetime of a collaboration token, in seconds.
+ *
+ * Named rather than inlined because three places need the same number: the
+ * signature's `exp`, the `expiresAt` the issuer reports back so a caller
+ * holding the token ahead of time can tell it is already dead, and the
+ * client's decision to discard a page-prop token instead of opening a socket
+ * with it.
+ *
+ * Five minutes is what the edge format has always used, and the self-hosted
+ * one now matches it deliberately: the token is spent within milliseconds of
+ * being issued (the browser fetches it and connects), and a long-lived one
+ * would only widen the window in which a leaked URL still opens a document.
+ * The socket it opens is not cut short by expiry — `authorize` runs once at
+ * the handshake and the connection then lives on its own.
+ */
+export const COLLAB_TOKEN_TTL_SECONDS = 300;
+/**
+ * The old name of {@link COLLAB_TOKEN_TTL_SECONDS}, kept because it is public
+ * API that apps and the worker template already read. One number, because one
+ * wire format: a second constant would eventually drift from this one and the
+ * drift would show up as tokens that expire earlier than the client thinks.
+ */
+export const PARTYKIT_TOKEN_TTL_SECONDS = COLLAB_TOKEN_TTL_SECONDS;
 /** Signs a minimal HS256 JWT — no external dependency. */
-export function signPartyKitToken(payload, secret, expiresInSeconds = 300) {
+export function signCollabToken(payload, secret, expiresInSeconds = COLLAB_TOKEN_TTL_SECONDS) {
     const header = { alg: 'HS256', typ: 'JWT' };
     const now = Math.floor(Date.now() / 1000);
     const body = { ...payload, iat: now, exp: now + expiresInSeconds };
@@ -9,20 +34,43 @@ export function signPartyKitToken(payload, secret, expiresInSeconds = 300) {
     const signature = createHmac('sha256', secret).update(unsigned).digest('base64url');
     return `${unsigned}.${signature}`;
 }
-/** Verifies signature + expiry of a token issued by {@link signPartyKitToken}. */
-export function verifyPartyKitToken(token, secret) {
+/**
+ * Verifies signature, expiry and document binding of a token issued by
+ * {@link signCollabToken}. Returns `null` for every failure — a verifier that
+ * distinguishes "bad signature" from "wrong document" in its return value
+ * invites a caller to treat one of them as recoverable.
+ *
+ * `expectedDocName` is required rather than optional on purpose: every caller
+ * knows which document is being opened, and an optional argument is one a
+ * caller forgets — which is exactly the bug this parameter exists to prevent.
+ */
+export function verifyCollabToken(token, secret, expectedDocName) {
     const parts = token.split('.');
     if (parts.length !== 3)
         return null;
     const [header, body, signature] = parts;
     const expected = createHmac('sha256', secret).update(`${header}.${body}`).digest();
     const received = Buffer.from(signature, 'base64url');
+    // Constant time, and length-checked first because timingSafeEqual throws on
+    // a length mismatch instead of answering false.
     if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
         return null;
     }
     try {
         const parsed = JSON.parse(Buffer.from(body, 'base64url').toString());
-        if (!parsed.userId || !parsed.docName || parsed.exp * 1000 < Date.now())
+        // `exp` is checked for presence before being compared: an absent one makes
+        // `parsed.exp * 1000` NaN, and `NaN < Date.now()` is false — so a token
+        // with no expiry read as "not expired" and lived forever. Nothing this
+        // module signs omits it, so that needed the signing key to reach; a
+        // credential that never expires is still exactly the property this format
+        // exists to remove, and it must not be representable.
+        if (!parsed.userId || !parsed.docName)
+            return null;
+        if (typeof parsed.exp !== 'number' || !Number.isFinite(parsed.exp))
+            return null;
+        if (parsed.exp * 1000 < Date.now())
+            return null;
+        if (parsed.docName !== expectedDocName)
             return null;
         return parsed;
     }
@@ -30,16 +78,42 @@ export function verifyPartyKitToken(token, secret) {
         return null;
     }
 }
-/** Parses the legacy base64 payload used by self-hosted driver handshakes. */
-export function parseLegacyToken(token) {
-    try {
-        const parsed = JSON.parse(Buffer.from(token, 'base64').toString());
-        return parsed.userId ? parsed : null;
-    }
-    catch {
-        return null;
-    }
+/** The connection context a verified token stands for. */
+export function tokenContext(payload) {
+    return {
+        userId: payload.userId,
+        ...(payload.user ? { user: payload.user } : {}),
+    };
+}
+/**
+ * Verifies a self-hosted token against the key resolved from the app —
+ * what a driver's handshake calls.
+ *
+ * Throws (rather than returning `null`) when there is no key to verify
+ * against: a missing secret is a misconfiguration of the server, not a bad
+ * token from the client, and the two must not produce the same message in the
+ * logs. Either way nothing is authenticated.
+ */
+export async function verifySelfHostedToken(token, docName, source) {
+    const secret = await resolveTokenSecret(source);
+    const payload = verifyCollabToken(token, secret, docName);
+    return payload ? tokenContext(payload) : null;
 }
+/**
+ * Signs the edge JWT. Same format and same TTL as every other collaboration
+ * token; the difference is the key, which the PartyKit worker holds
+ * (`COLLAB_JWT_SECRET`) and this process only shares with it.
+ */
+export const signPartyKitToken = signCollabToken;
+/**
+ * Verifies an edge JWT, including its document binding.
+ *
+ * The worker template runs the same three checks in WebCrypto — signature,
+ * `exp`, and `docName` against the room being connected to. Keep them in
+ * step: the room is the document, so a token that opens a room it was not
+ * issued for is the same hole on the edge that it is here.
+ */
+export const verifyPartyKitToken = verifyCollabToken;
 /** Builds the browser-facing WebSocket URL for an engine. */
 export function buildWsUrl(config, docName) {
     if (config.engine === 'partykit') {
@@ -103,12 +177,19 @@ export async function issueToken(config, user, docName, authorize) {
             token: signPartyKitToken({ userId: user.id, docName }, config.partykit.jwtSecret),
             wsUrl: buildWsUrl(config, docName),
             engine: config.engine,
+            expiresAt: Date.now() + COLLAB_TOKEN_TTL_SECONDS * 1000,
         };
     }
+    // Self-hosted. Signed with the app's key, bound to this document and dead
+    // in five minutes — resolved before anything is returned, so a server with
+    // no key configured refuses to issue rather than handing out a credential
+    // its own handshake will reject.
+    const secret = await resolveTokenSecret(config.tokenSecret);
     return {
-        token: Buffer.from(JSON.stringify(ctx)).toString('base64'),
+        token: signCollabToken({ userId: user.id, docName, ...(ctx.user ? { user: ctx.user } : {}) }, secret),
         wsUrl: buildWsUrl(config, docName),
         engine: config.engine,
+        expiresAt: Date.now() + COLLAB_TOKEN_TTL_SECONDS * 1000,
     };
 }
 //# sourceMappingURL=token.js.map

package/dist/src/auth/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../src/auth/token.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../../src/auth/token.ts"],"names":[],"mappings":"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"}

package/dist/src/collaboration_manager.d.ts

@@ -4,10 +4,11 @@ import { PartyKitDriver } from './drivers/partykit/partykit_driver.js';
 import { YjsDriver } from './drivers/yjs/yjs_driver.js';
 import { CommentService } from './services/comment_service.js';
 import { type PresenceMember, PresenceService, type PresenceStore } from './services/presence_service.js';
-import type { CollabConnectionContext, CollabDiffSummary, CollaborationConfig, CollaborationEngine, CollabPermission, CollabVersion, PruneVersionsOptions } from './types.js';
+import type { CollabConnectionContext, CollabDiffSummary, CollaborationConfig, CollaborationEngine, CollabPermission, CollabVersion, LiveDocumentResult, PruneVersionsOptions } from './types.js';
 export declare class CollaborationManager {
     #private;
     private readonly config;
+    private tokenSecretPromise;
     private readonly drivers;
     private server?;
     comments: CommentService;
@@ -27,6 +28,20 @@ export declare class CollaborationManager {
      */
     authorize(ctx: CollabConnectionContext, docName: string): Promise<CollabPermission>;
     get engine(): string;
+    /**
+     * The key that signs and verifies this app's collaboration tokens.
+     *
+     * Public for the same reason `authorize` is: the credential has two ends —
+     * the REST route that issues it and the WebSocket handshake that checks it
+     * — and they must resolve it identically. The routes ask the manager rather
+     * than repeating the resolution order, so `tokenSecret` in
+     * `config/collaboration.ts` (or on this constructor) applies to both, and
+     * neither can silently fall back to a different key.
+     *
+     * Memoized on the promise rather than the value, so two documents opening
+     * at once share one read of the app config instead of racing it.
+     */
+    tokenSecret(): Promise<string>;
     /** Attaches the WebSocket(s) to the Adonis HTTP server. No-op on edge. */
     attach(server: import('node:http').Server): Promise<void>;
     getDocumentState({ docName }: {
@@ -35,6 +50,52 @@ export declare class CollaborationManager {
     getDocumentText({ docName }: {
         docName: string;
     }): Promise<string>;
+    /**
+     * Runs `run` against the **live** document — the in-process CRDT instance
+     * the connected clients are syncing with — and says whether there was one.
+     *
+     * `getDocumentState` answers with a copy, which is enough to export a
+     * document and not enough to change one: an external edit (a Drive webhook,
+     * a cron) has to land in the instance people are typing into, or it either
+     * loses the keystrokes since the last flush or is lost by them. So this is
+     * scoped rather than a getter — the document is only borrowed for the
+     * duration of `run`, and a caller cannot stash a `Y.Doc` that Hocuspocus
+     * will unload out from under it.
+     *
+     * The callback gets the engine's real document, deliberately. The manager
+     * is engine-agnostic everywhere it routes; here it hands over the one thing
+     * a wrapper could not replace (`transact()` that fans out to clients), and
+     * keeps its agnosticism by *asking* whether the engine has such a document
+     * instead of assuming it: a PartyKit document lives on the edge and comes
+     * back `{ live: false, reason: 'engine-has-no-live-document' }` with the
+     * callback never run, not a cast that explodes.
+     *
+     * @example
+     * const result = await collaboration.current.withLiveDocument({
+     *   docName,
+     *   run: (doc) => {
+     *     doc.transact(() => applyExternalChange(doc))
+     *     return doc.getXmlFragment('default').toString()
+     *   },
+     * })
+     * if (!result.live) await mergeIntoStorageInstead()
+     */
+    withLiveDocument<T>({ docName, run, }: {
+        docName: string;
+        run: (document: import('yjs').Doc) => T | Promise<T>;
+    }): Promise<LiveDocumentResult<T>>;
+    /**
+     * Whether this process is holding the document open right now.
+     *
+     * The cheap question on its own, for callers deciding *where* to write
+     * before they know what to write. It is a snapshot of a live fact — the
+     * last client can disconnect a millisecond later — so anything that then
+     * touches the document should go through {@link withLiveDocument} and read
+     * its `live` flag rather than trusting this answer.
+     */
+    hasLiveDocument({ docName }: {
+        docName: string;
+    }): Promise<boolean>;
     createVersion({ docName, createdBy, label, }: {
         docName: string;
         createdBy: string | null;
@@ -43,6 +104,16 @@ export declare class CollaborationManager {
     listVersions({ docName }: {
         docName: string;
     }): Promise<CollabVersion[]>;
+    /**
+     * Binary state stored for one version — `getDocumentState` for a point in
+     * the history. Extracting the text of a version, diffing it against
+     * something the library does not know about, exporting it: all of that
+     * needs the bytes, and `listVersions` only hands out metadata.
+     */
+    getVersionState({ docName, versionId, }: {
+        docName: string;
+        versionId: string;
+    }): Promise<Uint8Array>;
     restoreVersion({ docName, versionId, restoredBy, }: {
         docName: string;
         versionId: string;

package/dist/src/collaboration_manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collaboration_manager.d.ts","sourceRoot":"","sources":["../../src/collaboration_manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collaboration_manager.d.ts","sourceRoot":"","sources":["../../src/collaboration_manager.ts"],"names":[],"mappings":"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"}

package/dist/src/collaboration_manager.js

@@ -1,4 +1,6 @@
+import { resolveTokenSecret } from './auth/secret.js';
 import { documentPatternParams, matchDocumentPattern } from './documents.js';
+import { supportsLiveDocuments } from './driver.js';
 import { AutomergeDriver } from './drivers/automerge/automerge_driver.js';
 import { PartyKitDriver } from './drivers/partykit/partykit_driver.js';
 import { resolveStorage } from './drivers/shared.js';
@@ -27,6 +29,7 @@ function warnAboutSingleDocumentPatterns(documents) {
 }
 export class CollaborationManager {
     config;
+    tokenSecretPromise;
     drivers = new Map();
     server;
     comments;
@@ -79,9 +82,52 @@ export class CollaborationManager {
             return this.config.authorize(ctx, docName);
         return { canRead: false, canWrite: false, canComment: false };
     }
+    /**
+     * Initial content for a document nothing has stored yet: the matched
+     * declaration's `load`, or nothing.
+     *
+     * Resolved here, next to `authorize`, because both answers come from the
+     * same declaration and the same pattern match — a driver that had to find
+     * the declaration itself would be a second matcher to keep in step with the
+     * first. Private: the drivers ask, at the one moment the answer is usable.
+     */
+    async #seedFor(docName) {
+        const declared = this.#documentFor(docName);
+        if (!declared?.declaration.load)
+            return undefined;
+        return declared.declaration.load({ docName, params: declared.params });
+    }
     get engine() {
         return this.config.engine ?? 'yjs';
     }
+    /**
+     * The key that signs and verifies this app's collaboration tokens.
+     *
+     * Public for the same reason `authorize` is: the credential has two ends —
+     * the REST route that issues it and the WebSocket handshake that checks it
+     * — and they must resolve it identically. The routes ask the manager rather
+     * than repeating the resolution order, so `tokenSecret` in
+     * `config/collaboration.ts` (or on this constructor) applies to both, and
+     * neither can silently fall back to a different key.
+     *
+     * Memoized on the promise rather than the value, so two documents opening
+     * at once share one read of the app config instead of racing it.
+     */
+    tokenSecret() {
+        if (!this.tokenSecretPromise) {
+            const resolving = resolveTokenSecret(this.config.tokenSecret);
+            this.tokenSecretPromise = resolving;
+            // The failure is never memoized — a manager built before the app
+            // finished booting has no app key to read yet, and remembering that as
+            // "there is no key" would outlive the condition that caused it. The
+            // handler also keeps the rejection from surfacing as unhandled; every
+            // caller still sees it through the promise this returns.
+            void resolving.catch(() => {
+                this.tokenSecretPromise = undefined;
+            });
+        }
+        return this.tokenSecretPromise;
+    }
     #buildDriver(engine) {
         const storage = this.config.storage;
         if (engine === 'partykit' || engine === 'partyserver') {
@@ -92,6 +138,13 @@ export class CollaborationManager {
         }
         const shared = {
             authorize: (ctx, docName) => this.authorize(ctx, docName),
+            // Deferred, not resolved here: the default key is the app's `appKey`,
+            // and drivers are built before the app is necessarily booted. Passing
+            // the same accessor the token route uses is what keeps the two ends of
+            // the credential on one source — sign with one key and verify with
+            // another and every handshake fails with nothing to point at.
+            tokenSecret: () => this.tokenSecret(),
+            seedDocument: (docName) => this.#seedFor(docName),
             ...(storage ? { storage } : {}),
             // Without this the presence store the provider builds from `redisUrl`
             // is never reached: the drivers' join/leave both guard on
@@ -135,12 +188,74 @@ export class CollaborationManager {
     getDocumentText({ docName }) {
         return this.#driverFor(docName).then((driver) => driver.getDocumentText(docName));
     }
+    /**
+     * Runs `run` against the **live** document — the in-process CRDT instance
+     * the connected clients are syncing with — and says whether there was one.
+     *
+     * `getDocumentState` answers with a copy, which is enough to export a
+     * document and not enough to change one: an external edit (a Drive webhook,
+     * a cron) has to land in the instance people are typing into, or it either
+     * loses the keystrokes since the last flush or is lost by them. So this is
+     * scoped rather than a getter — the document is only borrowed for the
+     * duration of `run`, and a caller cannot stash a `Y.Doc` that Hocuspocus
+     * will unload out from under it.
+     *
+     * The callback gets the engine's real document, deliberately. The manager
+     * is engine-agnostic everywhere it routes; here it hands over the one thing
+     * a wrapper could not replace (`transact()` that fans out to clients), and
+     * keeps its agnosticism by *asking* whether the engine has such a document
+     * instead of assuming it: a PartyKit document lives on the edge and comes
+     * back `{ live: false, reason: 'engine-has-no-live-document' }` with the
+     * callback never run, not a cast that explodes.
+     *
+     * @example
+     * const result = await collaboration.current.withLiveDocument({
+     *   docName,
+     *   run: (doc) => {
+     *     doc.transact(() => applyExternalChange(doc))
+     *     return doc.getXmlFragment('default').toString()
+     *   },
+     * })
+     * if (!result.live) await mergeIntoStorageInstead()
+     */
+    async withLiveDocument({ docName, run, }) {
+        const driver = await this.#driverFor(docName);
+        if (!supportsLiveDocuments(driver)) {
+            return { live: false, reason: 'engine-has-no-live-document' };
+        }
+        const document = driver.liveDocument(docName);
+        if (!document)
+            return { live: false, reason: 'not-loaded' };
+        return { live: true, value: await run(document) };
+    }
+    /**
+     * Whether this process is holding the document open right now.
+     *
+     * The cheap question on its own, for callers deciding *where* to write
+     * before they know what to write. It is a snapshot of a live fact — the
+     * last client can disconnect a millisecond later — so anything that then
+     * touches the document should go through {@link withLiveDocument} and read
+     * its `live` flag rather than trusting this answer.
+     */
+    async hasLiveDocument({ docName }) {
+        const driver = await this.#driverFor(docName);
+        return supportsLiveDocuments(driver) && driver.liveDocument(docName) !== undefined;
+    }
     createVersion({ docName, createdBy, label = null, }) {
         return this.#driverFor(docName).then((driver) => driver.createVersion(docName, createdBy, label));
     }
     listVersions({ docName }) {
         return this.#driverFor(docName).then((driver) => driver.listVersions(docName));
     }
+    /**
+     * Binary state stored for one version — `getDocumentState` for a point in
+     * the history. Extracting the text of a version, diffing it against
+     * something the library does not know about, exporting it: all of that
+     * needs the bytes, and `listVersions` only hands out metadata.
+     */
+    getVersionState({ docName, versionId, }) {
+        return this.#driverFor(docName).then((driver) => driver.getVersionState(docName, versionId));
+    }
     restoreVersion({ docName, versionId, restoredBy, }) {
         return this.#driverFor(docName).then((driver) => driver.restoreVersion(docName, versionId, restoredBy));
     }

package/dist/src/collaboration_manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"collaboration_manager.js","sourceRoot":"","sources":["../../src/collaboration_manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collaboration_manager.js","sourceRoot":"","sources":["../../src/collaboration_manager.ts"],"names":[],"mappings":"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"}

package/dist/src/define_config.d.ts

@@ -13,6 +13,11 @@ export type CollaborationAppConfig = {
     path?: string;
     redisUrl?: string;
     debounce?: number;
+    /**
+     * Signing key for collaboration tokens. Defaults to a key derived from the
+     * app's `appKey` — set this only for a dedicated secret.
+     */
+    tokenSecret?: string;
     authorize?: CollaborationConfig['authorize'];
     /** Omitted = in-memory (dev only). Production passes a persistent storage. */
     storage?: CollaborationConfig['storage'];

package/dist/src/define_config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvC,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACP,qBAAqB;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,iCAAiC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,qEAAqE;QACrE,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;QACvB,8DAA8D;QAC9D,WAAW,CAAC,EAAE,aAAa,CAAC;KAC7B,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,MAAM,IAAI;KACnD,CAAC,IAAI,OAAO,GAAG,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,IAAI,IAAI,CAClE,sBAAsB,EACtB,WAAW,CACZ,GAAG;IACF,SAAS,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,KAAK,EACzD,MAAM,EAAE,yBAAyB,CAAC,OAAO,CAAC,GACzC,yBAAyB,CAAC,OAAO,CAAC,CAEpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GACvE,OAAO,CAAC,MAAM,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GACrC,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,IACtD,OAAO,SAAS,GAAG,MAAM,IAAI,KAAK,MAAM,IAAI,EAAE,GAC1C,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,EAAE,GACpC,GAAG,IAAI,IAAI,MAAM,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,GAClD,GAAG,IAAI,IAAI,MAAM,EAAE,GACrB,OAAO,CAAC"}
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACvC,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACP,qBAAqB;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,iCAAiC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,qEAAqE;QACrE,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC;QACvB,8DAA8D;QAC9D,WAAW,CAAC,EAAE,aAAa,CAAC;KAC7B,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,SAAS,MAAM,IAAI;KACnD,CAAC,IAAI,OAAO,GAAG,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,IAAI,IAAI,CAClE,sBAAsB,EACtB,WAAW,CACZ,GAAG;IACF,SAAS,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;CACtC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,KAAK,EACzD,MAAM,EAAE,yBAAyB,CAAC,OAAO,CAAC,GACzC,yBAAyB,CAAC,OAAO,CAAC,CAEpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GACvE,OAAO,CAAC,MAAM,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,GACrC,KAAK,CAAC;AAEV;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,IACtD,OAAO,SAAS,GAAG,MAAM,IAAI,KAAK,MAAM,IAAI,EAAE,GAC1C,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,EAAE,GACpC,GAAG,IAAI,IAAI,MAAM,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,GAClD,GAAG,IAAI,IAAI,MAAM,EAAE,GACrB,OAAO,CAAC"}

package/dist/src/define_config.js.map

@@ -1 +1 @@
-{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AA0DA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA0C;IAE1C,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../src/define_config.ts"],"names":[],"mappings":"AA+DA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA0C;IAE1C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/src/documents.d.ts

@@ -1,3 +1,4 @@
+import type { Doc as YDoc } from 'yjs';
 import type { CollabConnectionContext, CollaborationEngine, CollabPermission } from './types.js';
 /**
  * The `:name` segments of a document pattern, as the object
@@ -12,6 +13,27 @@ export type DocumentParams<Pattern extends string> = string extends Pattern ? Re
     [Name in DocumentParamNames<Pattern>]: string;
 };
 type DocumentParamNames<Pattern extends string> = Pattern extends `${infer Head}/${infer Rest}` ? DocumentParamNames<Head> | DocumentParamNames<Rest> : Pattern extends `:${infer Name}` ? Name : never;
+/**
+ * What {@link CollabDocumentDeclaration.load} may hand back.
+ *
+ * A `Uint8Array` is the document's state in its **engine's own** binary format
+ * — a Yjs update (`Y.encodeStateAsUpdate(doc)`), an Automerge save
+ * (`A.save(doc)`). It is the only form every engine understands, so it is the
+ * one to reach for.
+ *
+ * A `Y.Doc` is accepted as a shortcut for the Yjs engine, because building a
+ * seed there usually means running the app's own content through a transformer
+ * that already returns one (`TiptapTransformer.toYdoc(json, 'default')`), and
+ * encoding it by hand is a line of ceremony with nothing to decide in it. The
+ * type is Yjs's because the convenience is Yjs's: an Automerge seed arrives as
+ * `A.save(doc)`, and a `Y.Doc` handed to a non-Yjs document is reported and
+ * ignored instead of guessed at. Nothing here mentions Tiptap — the editor is
+ * the app's business, the bytes are ours.
+ *
+ * `null`/`undefined` means "nothing to seed": the document opens empty and the
+ * hook is asked again the next time it is opened.
+ */
+export type CollabDocumentSeed = Uint8Array | YDoc | null | undefined;
 /**
  * Declaração declarativa de um documento colaborativo.
  *
@@ -35,6 +57,11 @@ type DocumentParamNames<Pattern extends string> = Pattern extends `${infer Head}
  *         ? { canRead: true, canWrite: true, canComment: true }
  *         : { canRead: false, canWrite: false, canComment: false }
  *     },
+ *     async load({ params }) {
+ *       const research = await Research.find(params.id)
+ *       if (!research?.body) return null
+ *       return TiptapTransformer.toYdoc(research.body, 'default')
+ *     },
  *   },
  * }
  */
@@ -51,6 +78,38 @@ export interface CollabDocumentDeclaration<P extends Record<string, string> = Re
         docName: string;
         params: P;
     }) => Promise<CollabPermission>;
+    /**
+     * Initial content for a document the storage has **never** stored — the
+     * `params` are typed from the key, exactly like `authorize`'s.
+     *
+     * Called when the document is opened and the storage has nothing under its
+     * name; the result is persisted right away, so the next connection loads it
+     * from storage and the hook is never asked about that document again. It is
+     * how a document whose real content lives elsewhere (a `researches.body`
+     * column, an imported file) is born holding that content instead of empty.
+     *
+     * Without it, seeding is the app's problem, and the app can only solve it
+     * from a request it *knows* precedes the WebSocket — which is a race
+     * dressed up as an ordering. Losing that race is not merely wrong, it is
+     * destructive: the editor mounts against an empty CRDT document, the CRDT
+     * is what the editor shows, and the first autosave writes that emptiness
+     * over the text in the database. That is a real dissertation, lost on
+     * 2026-08-28.
+     *
+     * It receives the document, not the connection. The first client to open a
+     * new document decides what every later one sees, so a seed that varied
+     * with `ctx` would freeze whoever arrived first into everyone else's
+     * document — a per-user document is a different document, with a different
+     * name.
+     *
+     * A `load` that throws is reported on the observability seam and the
+     * document opens empty: a broken seed must not become a failed
+     * handshake that the client then retries forever.
+     */
+    load?: (info: {
+        docName: string;
+        params: P;
+    }) => Promise<CollabDocumentSeed>;
 }
 /**
  * Identity helper for declaring a document **outside** `config/collaboration.ts`

package/dist/src/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjG;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,MAAM,IAAI,MAAM,SAAS,OAAO,GACvE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB;KAAG,IAAI,IAAI,kBAAkB,CAAC,OAAO,CAAC,GAAG,MAAM;CAAE,CAAC;AAEtD,KAAK,kBAAkB,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC3F,kBAAkB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,GACnD,OAAO,SAAS,IAAI,MAAM,IAAI,EAAE,GAC9B,IAAI,GACJ,KAAK,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,yBAAyB,CACxC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzD,iEAAiE;IACjE,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CACV,GAAG,EAAE,uBAAuB,EAC5B,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,KACjC,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtF,WAAW,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACxC,yBAAyB,CAAC,CAAC,CAAC,CAE9B;AAED,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,EACpD,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,yBAAyB,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAM,GAC1D;KAAG,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,GAAG,yBAAyB,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE,CAiBjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAe/B"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,IAAI,IAAI,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjG;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,OAAO,SAAS,MAAM,IAAI,MAAM,SAAS,OAAO,GACvE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB;KAAG,IAAI,IAAI,kBAAkB,CAAC,OAAO,CAAC,GAAG,MAAM;CAAE,CAAC;AAEtD,KAAK,kBAAkB,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC3F,kBAAkB,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,GACnD,OAAO,SAAS,IAAI,MAAM,IAAI,EAAE,GAC9B,IAAI,GACJ,KAAK,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,yBAAyB,CACxC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAEzD,iEAAiE;IACjE,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CACV,GAAG,EAAE,uBAAuB,EAC5B,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,KACjC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACtF,WAAW,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACxC,yBAAyB,CAAC,CAAC,CAAC,CAE9B;AAED,kEAAkE;AAClE,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,SAAS,MAAM,EACpD,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,yBAAyB,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAM,GAC1D;KAAG,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,GAAG,yBAAyB,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAAE,CAiBjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAK/D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAe/B"}

package/dist/src/documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAyC;IAEzC,OAAO,WAAW,CAAC;AACrB,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,WAAW,GAA8C,EAAE;IAE3D,IACE,MAAM,KAAK,EAAE;QACb,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;QACtB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EACrB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,kDAAkD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,mBAAmB;YACzF,oFAAoF;YACpF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,GAAG,MAAM,MAAM,CAAC,EAAE,WAAW,EAEtC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,OAAO;SACX,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAe;IAEf,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAE,CAAC;QACzC,CAAC;aAAM,IAAI,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../src/documents.ts"],"names":[],"mappings":"AAyHA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,WAAyC;IAEzC,OAAO,WAAW,CAAC;AACrB,CAAC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAc,EACd,WAAW,GAA8C,EAAE;IAE3D,IACE,MAAM,KAAK,EAAE;QACb,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;QACtB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EACrB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,kDAAkD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,mBAAmB;YACzF,oFAAoF;YACpF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC,GAAG,MAAM,MAAM,CAAC,EAAE,WAAW,EAEtC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe;IACnD,OAAO,OAAO;SACX,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAe;IAEf,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEhD,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,KAAK,CAAE,CAAC;QACzC,CAAC;aAAM,IAAI,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}