@prenta/core 0.118.0

package/dist/realtime/comments.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Document comments — anchored, threaded discussion attached to documents.
+ *
+ * This module owns the *pure* comment logic: validation, normalization, and
+ * the storage-agnostic CRUD entry points. The HTTP layer in `api/handlers.ts`
+ * is a thin wrapper that handles auth + JSON envelope; everything else lives
+ * here so the unit tests don't need a Request loop.
+ *
+ * Storage shape — see `packages/cms-core/schema-fragments/cms-schema.prisma`,
+ * model `DocumentComment`. We require only a minimal Prisma surface so the
+ * helpers can be tested against an in-memory fake.
+ *
+ * Anchors are Yjs *relative positions* serialised as Base64. Storing them in
+ * a JSON column (rather than Bytes) keeps the REST contract trivial: the
+ * client posts `{ from: "AQ...", to: "AQ..." }`, we round-trip the strings.
+ * Slice 5 reconstitutes them with `Y.createAbsolutePositionFromRelativePosition`
+ * to paint anchored highlights in the editor; nothing in the API layer needs
+ * to interpret the bytes.
+ */
+/** Maximum length we accept for a comment body (markdown source). */
+export declare const MAX_COMMENT_BODY_LENGTH = 10000;
+/** Cap on returned comments per `listComments` call. */
+export declare const MAX_COMMENT_LIST_PAGE_SIZE = 200;
+/** Default page size when the caller does not request one. */
+export declare const DEFAULT_COMMENT_LIST_PAGE_SIZE = 100;
+/**
+ * Yjs relative-position anchor. The two ends are Base64-encoded
+ * `Y.encodeRelativePosition` bytes; slice 5 turns them back into absolute
+ * positions for rendering.
+ *
+ * Slice 4 (this module) treats the anchor as opaque: we only validate that
+ * each side is a reasonably short string so we don't store arbitrary blobs.
+ */
+export interface CommentAnchor {
+    from: string;
+    to: string;
+}
+/**
+ * Public REST shape of a comment. Mirrors the Prisma row plus a derived
+ * `isResolved` flag so the client doesn't have to repeat the null check.
+ */
+export interface CommentDTO {
+    id: string;
+    documentId: string;
+    parentId: string | null;
+    userId: string | null;
+    body: string;
+    anchor: CommentAnchor | null;
+    resolvedAt: string | null;
+    resolvedById: string | null;
+    deletedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    isResolved: boolean;
+}
+/** Input for creating a new comment. */
+export interface CreateCommentInput {
+    documentId: string;
+    userId: string;
+    body: string;
+    anchor?: CommentAnchor | null;
+    parentId?: string | null;
+}
+/** Input for updating an existing comment. Only the body is editable. */
+export interface UpdateCommentInput {
+    body: string;
+}
+/** Filter passed to `listComments`. */
+export interface ListCommentsFilter {
+    documentId: string;
+    /** Include resolved threads. Default: `false`. */
+    includeResolved?: boolean;
+    /** Include soft-deleted comments. Default: `false`. */
+    includeDeleted?: boolean;
+    /** Page size (1..`MAX_COMMENT_LIST_PAGE_SIZE`). */
+    pageSize?: number;
+}
+/**
+ * Minimal Prisma surface we depend on. The real `PrismaClient` satisfies it,
+ * but tests inject a small in-memory fake.
+ */
+export interface CommentsDB {
+    documentComment: {
+        findUnique: (args: {
+            where: {
+                id: string;
+            };
+            [key: string]: unknown;
+        }) => Promise<DocumentCommentRow | null>;
+        findMany: (args: {
+            where: Record<string, unknown>;
+            orderBy?: Record<string, 'asc' | 'desc'>;
+            take?: number;
+        }) => Promise<DocumentCommentRow[]>;
+        create: (args: {
+            data: {
+                documentId: string;
+                userId: string | null;
+                body: string;
+                anchor: CommentAnchor | null;
+                parentId: string | null;
+            };
+        }) => Promise<DocumentCommentRow>;
+        update: (args: {
+            where: {
+                id: string;
+            };
+            data: Partial<{
+                body: string;
+                resolvedAt: Date | null;
+                resolvedById: string | null;
+                deletedAt: Date | null;
+            }>;
+        }) => Promise<DocumentCommentRow>;
+    };
+}
+/** Row shape returned by Prisma. We accept Date or ISO strings so fakes are cheap. */
+export interface DocumentCommentRow {
+    id: string;
+    documentId: string;
+    parentId: string | null;
+    userId: string | null;
+    body: string;
+    anchor: CommentAnchor | null;
+    resolvedAt: Date | string | null;
+    resolvedById: string | null;
+    deletedAt: Date | string | null;
+    createdAt: Date | string;
+    updatedAt: Date | string;
+}
+/** Discriminated result type used by the service entry points. */
+export type CommentsResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: CommentsError;
+};
+export interface CommentsError {
+    /**
+     * Stable machine-readable code. The HTTP layer maps each to a status:
+     * - validation → 400
+     * - not_found  → 404
+     * - forbidden  → 403
+     * - conflict   → 409 (e.g. resolving an already-resolved thread)
+     */
+    code: 'validation' | 'not_found' | 'forbidden' | 'conflict';
+    message: string;
+}
+/**
+ * Strip a comment row down to the public DTO. Centralised so the response
+ * shape stays consistent between create / list / update / resolve.
+ */
+export declare function toCommentDTO(row: DocumentCommentRow): CommentDTO;
+/**
+ * Parse + validate an anchor blob coming from an untrusted client. Returns
+ * `null` when the caller did not provide one (document-level comments).
+ */
+export declare function parseAnchor(input: unknown): CommentsResult<CommentAnchor | null>;
+/** Normalize whitespace + enforce length limits on a posted body. */
+export declare function normaliseBody(input: unknown): CommentsResult<string>;
+/**
+ * Create a comment. Enforces:
+ *   - body validation (non-empty, length-capped)
+ *   - anchor shape validation
+ *   - single-level threading: a `parentId` must reference an existing,
+ *     non-deleted, non-reply comment under the same document.
+ *
+ * The caller (HTTP handler) is responsible for auth — once we reach here we
+ * trust the supplied `userId`.
+ */
+export declare function createComment(db: CommentsDB, input: CreateCommentInput): Promise<CommentsResult<CommentDTO>>;
+/**
+ * List comments for a document. Returns the rows ordered oldest-first so a
+ * naive client can render threads top-down. Pagination is "show the first
+ * N"; the higher-level UI in slice 5 will switch to cursor pagination once
+ * volume justifies it.
+ */
+export declare function listComments(db: CommentsDB, filter: ListCommentsFilter): Promise<CommentsResult<CommentDTO[]>>;
+/**
+ * Edit a comment body. Only the author can edit, and only if the comment is
+ * not soft-deleted. Resolved threads remain editable so a moderator can
+ * append context.
+ */
+export declare function updateComment(db: CommentsDB, id: string, input: UpdateCommentInput, actor: {
+    userId: string;
+    isAdmin: boolean;
+}): Promise<CommentsResult<CommentDTO>>;
+/**
+ * Mark a comment thread as resolved. Either the comment's author or any
+ * admin / write-role caller can resolve. Resolving an already-resolved
+ * comment is a no-op (returns the existing row) so a duplicate click in the
+ * UI does not surface as an error.
+ */
+export declare function resolveComment(db: CommentsDB, id: string, actor: {
+    userId: string;
+    canResolve: boolean;
+}): Promise<CommentsResult<CommentDTO>>;
+/**
+ * Re-open a resolved thread. Same permission as `resolveComment`.
+ */
+export declare function reopenComment(db: CommentsDB, id: string, actor: {
+    userId: string;
+    canResolve: boolean;
+}): Promise<CommentsResult<CommentDTO>>;
+/**
+ * Soft-delete a comment. The row is preserved (so replies don't lose their
+ * thread root) but stops being returned by `listComments` unless explicitly
+ * requested with `includeDeleted: true`.
+ *
+ * Only the author or an admin may delete.
+ */
+export declare function deleteComment(db: CommentsDB, id: string, actor: {
+    userId: string;
+    isAdmin: boolean;
+}): Promise<CommentsResult<CommentDTO>>;
+//# sourceMappingURL=comments.d.ts.map

package/dist/realtime/comments.d.ts.map

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

package/dist/realtime/comments.js

@@ -0,0 +1,282 @@
+/**
+ * Document comments — anchored, threaded discussion attached to documents.
+ *
+ * This module owns the *pure* comment logic: validation, normalization, and
+ * the storage-agnostic CRUD entry points. The HTTP layer in `api/handlers.ts`
+ * is a thin wrapper that handles auth + JSON envelope; everything else lives
+ * here so the unit tests don't need a Request loop.
+ *
+ * Storage shape — see `packages/cms-core/schema-fragments/cms-schema.prisma`,
+ * model `DocumentComment`. We require only a minimal Prisma surface so the
+ * helpers can be tested against an in-memory fake.
+ *
+ * Anchors are Yjs *relative positions* serialised as Base64. Storing them in
+ * a JSON column (rather than Bytes) keeps the REST contract trivial: the
+ * client posts `{ from: "AQ...", to: "AQ..." }`, we round-trip the strings.
+ * Slice 5 reconstitutes them with `Y.createAbsolutePositionFromRelativePosition`
+ * to paint anchored highlights in the editor; nothing in the API layer needs
+ * to interpret the bytes.
+ */
+/** Maximum length we accept for a comment body (markdown source). */
+export const MAX_COMMENT_BODY_LENGTH = 10_000;
+/** Cap on returned comments per `listComments` call. */
+export const MAX_COMMENT_LIST_PAGE_SIZE = 200;
+/** Default page size when the caller does not request one. */
+export const DEFAULT_COMMENT_LIST_PAGE_SIZE = 100;
+const MAX_ANCHOR_FIELD_LENGTH = 4_096;
+function err(code, message) {
+    return { code, message };
+}
+function toIso(value) {
+    if (value === null)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString();
+    // Tolerate fakes that already store ISO strings.
+    return value;
+}
+function toIsoRequired(value) {
+    return value instanceof Date ? value.toISOString() : value;
+}
+/**
+ * Strip a comment row down to the public DTO. Centralised so the response
+ * shape stays consistent between create / list / update / resolve.
+ */
+export function toCommentDTO(row) {
+    return {
+        id: row.id,
+        documentId: row.documentId,
+        parentId: row.parentId,
+        userId: row.userId,
+        body: row.body,
+        anchor: row.anchor,
+        resolvedAt: toIso(row.resolvedAt),
+        resolvedById: row.resolvedById,
+        deletedAt: toIso(row.deletedAt),
+        createdAt: toIsoRequired(row.createdAt),
+        updatedAt: toIsoRequired(row.updatedAt),
+        isResolved: row.resolvedAt !== null,
+    };
+}
+/**
+ * Parse + validate an anchor blob coming from an untrusted client. Returns
+ * `null` when the caller did not provide one (document-level comments).
+ */
+export function parseAnchor(input) {
+    if (input === undefined || input === null) {
+        return { ok: true, value: null };
+    }
+    if (typeof input !== 'object' || Array.isArray(input)) {
+        return { ok: false, error: err('validation', 'anchor must be an object with `from` and `to`') };
+    }
+    const obj = input;
+    if (typeof obj.from !== 'string' || typeof obj.to !== 'string') {
+        return { ok: false, error: err('validation', 'anchor.from and anchor.to must be strings') };
+    }
+    if (obj.from.length === 0 ||
+        obj.from.length > MAX_ANCHOR_FIELD_LENGTH ||
+        obj.to.length === 0 ||
+        obj.to.length > MAX_ANCHOR_FIELD_LENGTH) {
+        return {
+            ok: false,
+            error: err('validation', `anchor fields must be 1..${MAX_ANCHOR_FIELD_LENGTH} chars`),
+        };
+    }
+    return { ok: true, value: { from: obj.from, to: obj.to } };
+}
+/** Normalize whitespace + enforce length limits on a posted body. */
+export function normaliseBody(input) {
+    if (typeof input !== 'string') {
+        return { ok: false, error: err('validation', 'body must be a string') };
+    }
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, error: err('validation', 'body cannot be empty') };
+    }
+    if (trimmed.length > MAX_COMMENT_BODY_LENGTH) {
+        return {
+            ok: false,
+            error: err('validation', `body cannot exceed ${MAX_COMMENT_BODY_LENGTH} characters`),
+        };
+    }
+    return { ok: true, value: trimmed };
+}
+/**
+ * Create a comment. Enforces:
+ *   - body validation (non-empty, length-capped)
+ *   - anchor shape validation
+ *   - single-level threading: a `parentId` must reference an existing,
+ *     non-deleted, non-reply comment under the same document.
+ *
+ * The caller (HTTP handler) is responsible for auth — once we reach here we
+ * trust the supplied `userId`.
+ */
+export async function createComment(db, input) {
+    if (typeof input.documentId !== 'string' || input.documentId.length === 0) {
+        return { ok: false, error: err('validation', 'documentId is required') };
+    }
+    if (typeof input.userId !== 'string' || input.userId.length === 0) {
+        return { ok: false, error: err('validation', 'userId is required') };
+    }
+    const body = normaliseBody(input.body);
+    if (!body.ok)
+        return body;
+    const anchor = parseAnchor(input.anchor);
+    if (!anchor.ok)
+        return anchor;
+    let parentId = null;
+    if (input.parentId != null && input.parentId !== '') {
+        if (typeof input.parentId !== 'string') {
+            return { ok: false, error: err('validation', 'parentId must be a string') };
+        }
+        const parent = await db.documentComment.findUnique({ where: { id: input.parentId } });
+        if (!parent) {
+            return { ok: false, error: err('not_found', 'parent comment not found') };
+        }
+        if (parent.documentId !== input.documentId) {
+            return { ok: false, error: err('validation', 'parent comment is on a different document') };
+        }
+        if (parent.parentId !== null) {
+            return {
+                ok: false,
+                error: err('validation', 'replies cannot themselves be replied to (one level only)'),
+            };
+        }
+        if (parent.deletedAt !== null) {
+            return { ok: false, error: err('not_found', 'parent comment has been deleted') };
+        }
+        parentId = parent.id;
+    }
+    const row = await db.documentComment.create({
+        data: {
+            documentId: input.documentId,
+            userId: input.userId,
+            body: body.value,
+            anchor: anchor.value,
+            parentId,
+        },
+    });
+    return { ok: true, value: toCommentDTO(row) };
+}
+/**
+ * List comments for a document. Returns the rows ordered oldest-first so a
+ * naive client can render threads top-down. Pagination is "show the first
+ * N"; the higher-level UI in slice 5 will switch to cursor pagination once
+ * volume justifies it.
+ */
+export async function listComments(db, filter) {
+    if (typeof filter.documentId !== 'string' || filter.documentId.length === 0) {
+        return { ok: false, error: err('validation', 'documentId is required') };
+    }
+    const where = { documentId: filter.documentId };
+    if (!filter.includeResolved)
+        where.resolvedAt = null;
+    if (!filter.includeDeleted)
+        where.deletedAt = null;
+    const pageSize = clampPageSize(filter.pageSize);
+    const rows = await db.documentComment.findMany({
+        where,
+        orderBy: { createdAt: 'asc' },
+        take: pageSize,
+    });
+    return { ok: true, value: rows.map(toCommentDTO) };
+}
+function clampPageSize(n) {
+    if (n === undefined || Number.isNaN(n))
+        return DEFAULT_COMMENT_LIST_PAGE_SIZE;
+    if (n < 1)
+        return 1;
+    if (n > MAX_COMMENT_LIST_PAGE_SIZE)
+        return MAX_COMMENT_LIST_PAGE_SIZE;
+    return Math.floor(n);
+}
+/**
+ * Edit a comment body. Only the author can edit, and only if the comment is
+ * not soft-deleted. Resolved threads remain editable so a moderator can
+ * append context.
+ */
+export async function updateComment(db, id, input, actor) {
+    const existing = await db.documentComment.findUnique({ where: { id } });
+    if (!existing || existing.deletedAt !== null) {
+        return { ok: false, error: err('not_found', 'comment not found') };
+    }
+    if (!actor.isAdmin && existing.userId !== actor.userId) {
+        return { ok: false, error: err('forbidden', 'only the author can edit this comment') };
+    }
+    const body = normaliseBody(input.body);
+    if (!body.ok)
+        return body;
+    const row = await db.documentComment.update({
+        where: { id },
+        data: { body: body.value },
+    });
+    return { ok: true, value: toCommentDTO(row) };
+}
+/**
+ * Mark a comment thread as resolved. Either the comment's author or any
+ * admin / write-role caller can resolve. Resolving an already-resolved
+ * comment is a no-op (returns the existing row) so a duplicate click in the
+ * UI does not surface as an error.
+ */
+export async function resolveComment(db, id, actor) {
+    const existing = await db.documentComment.findUnique({ where: { id } });
+    if (!existing || existing.deletedAt !== null) {
+        return { ok: false, error: err('not_found', 'comment not found') };
+    }
+    if (!actor.canResolve && existing.userId !== actor.userId) {
+        return { ok: false, error: err('forbidden', 'not allowed to resolve this comment') };
+    }
+    if (existing.resolvedAt !== null) {
+        return { ok: true, value: toCommentDTO(existing) };
+    }
+    const row = await db.documentComment.update({
+        where: { id },
+        data: { resolvedAt: new Date(), resolvedById: actor.userId },
+    });
+    return { ok: true, value: toCommentDTO(row) };
+}
+/**
+ * Re-open a resolved thread. Same permission as `resolveComment`.
+ */
+export async function reopenComment(db, id, actor) {
+    const existing = await db.documentComment.findUnique({ where: { id } });
+    if (!existing || existing.deletedAt !== null) {
+        return { ok: false, error: err('not_found', 'comment not found') };
+    }
+    if (!actor.canResolve && existing.userId !== actor.userId) {
+        return { ok: false, error: err('forbidden', 'not allowed to re-open this comment') };
+    }
+    if (existing.resolvedAt === null) {
+        return { ok: true, value: toCommentDTO(existing) };
+    }
+    const row = await db.documentComment.update({
+        where: { id },
+        data: { resolvedAt: null, resolvedById: null },
+    });
+    return { ok: true, value: toCommentDTO(row) };
+}
+/**
+ * Soft-delete a comment. The row is preserved (so replies don't lose their
+ * thread root) but stops being returned by `listComments` unless explicitly
+ * requested with `includeDeleted: true`.
+ *
+ * Only the author or an admin may delete.
+ */
+export async function deleteComment(db, id, actor) {
+    const existing = await db.documentComment.findUnique({ where: { id } });
+    if (!existing) {
+        return { ok: false, error: err('not_found', 'comment not found') };
+    }
+    if (!actor.isAdmin && existing.userId !== actor.userId) {
+        return { ok: false, error: err('forbidden', 'only the author can delete this comment') };
+    }
+    if (existing.deletedAt !== null) {
+        return { ok: true, value: toCommentDTO(existing) };
+    }
+    const row = await db.documentComment.update({
+        where: { id },
+        data: { deletedAt: new Date() },
+    });
+    return { ok: true, value: toCommentDTO(row) };
+}
+//# sourceMappingURL=comments.js.map

package/dist/realtime/comments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../src/realtime/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAA;AAE7C,wDAAwD;AACxD,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAA;AAE7C,8DAA8D;AAC9D,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAA;AAejD,MAAM,uBAAuB,GAAG,KAAK,CAAA;AAiHrC,SAAS,GAAG,CAAC,IAA2B,EAAE,OAAe;IACvD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAA;AAC1B,CAAC;AAED,SAAS,KAAK,CAAC,KAA2B;IACxC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IAC/B,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,WAAW,EAAE,CAAA;IACrD,iDAAiD;IACjD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,aAAa,CAAC,KAAoB;IACzC,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,GAAuB;IAClD,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;QACjC,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;QAC/B,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC;QACvC,SAAS,EAAE,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC;QACvC,UAAU,EAAE,GAAG,CAAC,UAAU,KAAK,IAAI;KACpC,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,+CAA+C,CAAC,EAAE,CAAA;IACjG,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAA;IAC5C,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,2CAA2C,CAAC,EAAE,CAAA;IAC7F,CAAC;IACD,IACE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,uBAAuB;QACzC,GAAG,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;QACnB,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,uBAAuB,EACvC,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,4BAA4B,uBAAuB,QAAQ,CAAC;SACtF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAA;AAC5D,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,uBAAuB,CAAC,EAAE,CAAA;IACzE,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,sBAAsB,CAAC,EAAE,CAAA;IACxE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,uBAAuB,EAAE,CAAC;QAC7C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,sBAAsB,uBAAuB,aAAa,CAAC;SACrF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAc,EACd,KAAyB;IAEzB,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,wBAAwB,CAAC,EAAE,CAAA;IAC1E,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,oBAAoB,CAAC,EAAE,CAAA;IACtE,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IAEzB,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACxC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAA;IAE7B,IAAI,QAAQ,GAAkB,IAAI,CAAA;IAClC,IAAI,KAAK,CAAC,QAAQ,IAAI,IAAI,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QACpD,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,2BAA2B,CAAC,EAAE,CAAA;QAC7E,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;QACrF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,0BAA0B,CAAC,EAAE,CAAA;QAC3E,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,EAAE,CAAC;YAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,2CAA2C,CAAC,EAAE,CAAA;QAC7F,CAAC;QACD,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,0DAA0D,CAAC;aACrF,CAAA;QACH,CAAC;QACD,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,iCAAiC,CAAC,EAAE,CAAA;QAClF,CAAC;QACD,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAA;IACtB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QAC1C,IAAI,EAAE;YACJ,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,MAAM,EAAE,MAAM,CAAC,KAAK;YACpB,QAAQ;SACT;KACF,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,EAAc,EACd,MAA0B;IAE1B,IAAI,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5E,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,YAAY,EAAE,wBAAwB,CAAC,EAAE,CAAA;IAC1E,CAAC;IACD,MAAM,KAAK,GAA4B,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAA;IACxE,IAAI,CAAC,MAAM,CAAC,eAAe;QAAE,KAAK,CAAC,UAAU,GAAG,IAAI,CAAA;IACpD,IAAI,CAAC,MAAM,CAAC,cAAc;QAAE,KAAK,CAAC,SAAS,GAAG,IAAI,CAAA;IAElD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAC/C,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC;QAC7C,KAAK;QACL,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE;QAC7B,IAAI,EAAE,QAAQ;KACf,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAA;AACpD,CAAC;AAED,SAAS,aAAa,CAAC,CAAqB;IAC1C,IAAI,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,8BAA8B,CAAA;IAC7E,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAA;IACnB,IAAI,CAAC,GAAG,0BAA0B;QAAE,OAAO,0BAA0B,CAAA;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAc,EACd,EAAU,EACV,KAAyB,EACzB,KAA2C;IAE3C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC7C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,mBAAmB,CAAC,EAAE,CAAA;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,uCAAuC,CAAC,EAAE,CAAA;IACxF,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACtC,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IAEzB,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QAC1C,KAAK,EAAE,EAAE,EAAE,EAAE;QACb,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE;KAC3B,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAc,EACd,EAAU,EACV,KAA8C;IAE9C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC7C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,mBAAmB,CAAC,EAAE,CAAA;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,qCAAqC,CAAC,EAAE,CAAA;IACtF,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAA;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QAC1C,KAAK,EAAE,EAAE,EAAE,EAAE;QACb,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,YAAY,EAAE,KAAK,CAAC,MAAM,EAAE;KAC7D,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAc,EACd,EAAU,EACV,KAA8C;IAE9C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAC7C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,mBAAmB,CAAC,EAAE,CAAA;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,qCAAqC,CAAC,EAAE,CAAA;IACtF,CAAC;IACD,IAAI,QAAQ,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAA;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QAC1C,KAAK,EAAE,EAAE,EAAE,EAAE;QACb,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE;KAC/C,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;AAC/C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAc,EACd,EAAU,EACV,KAA2C;IAE3C,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,mBAAmB,CAAC,EAAE,CAAA;IACpE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACvD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,EAAE,yCAAyC,CAAC,EAAE,CAAA;IAC1F,CAAC;IACD,IAAI,QAAQ,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAA;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC;QAC1C,KAAK,EAAE,EAAE,EAAE,EAAE;QACb,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE;KAChC,CAAC,CAAA;IACF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,CAAA;AAC/C,CAAC"}

package/dist/realtime/gateway.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Realtime gateway for `@prenta/realtime` rooms.
+ *
+ * The gateway is **transport-agnostic by design**: it does not depend on
+ * `ws`, `uWebSockets.js`, Cloudflare Workers, or any specific framework.
+ * Consumers create a `WebSocketLike` adapter around their server's socket
+ * primitive and pass it to `gateway.handleConnection(socket, req)`.
+ *
+ * Responsibilities:
+ *   1. Authenticate the connection (delegated to `options.authenticate`).
+ *   2. Look up (or lazily create) the `Room` for the document.
+ *   3. Pump bytes between the socket and the room.
+ *   4. Persist edits via the configured `DocumentPersistence`.
+ *   5. Reap idle rooms (no connections + no pending writes) to bound memory.
+ *
+ * The companion file `persistence.ts` provides
+ * `createPrismaDocumentPersistence(db)` which the gateway uses by default
+ * when callers don't supply their own.
+ */
+import { type DocumentPersistence } from '@prenta/realtime';
+/**
+ * Minimal contract the gateway needs from a real WebSocket implementation.
+ * Compatible with `ws.WebSocket`, browser-native `WebSocket`, the
+ * Cloudflare Workers `WebSocket` Hibernation API, and Bun's WebSocket.
+ *
+ * Adapter authors typically just wrap their library's socket in a thin
+ * shim that conforms to this shape.
+ */
+export interface WebSocketLike {
+    /** Send a binary frame. */
+    send(data: Uint8Array): void;
+    /** Close the socket. Idempotent. */
+    close(code?: number, reason?: string): void;
+    /** Subscribe to inbound binary frames. */
+    on(event: 'message', handler: (data: Uint8Array) => void): void;
+    /** Subscribe to close events. */
+    on(event: 'close', handler: () => void): void;
+    /** Subscribe to error events. */
+    on(event: 'error', handler: (err: Error) => void): void;
+}
+/** Information about the inbound HTTP upgrade request. */
+export interface UpgradeRequestInfo {
+    /** Path + query, e.g. `/api/cms/realtime/sync?documentId=doc_1`. */
+    url: string;
+    /** Lowercased header bag. Authentication usually reads `cookie` or `authorization`. */
+    headers: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Outcome of the authentication / routing decision. Return `null` to reject
+ * the connection (the gateway will close it with code 4401).
+ *
+ * `connectionId` should be globally unique within the gateway instance —
+ * usually a `crypto.randomUUID()` or `req.headers['sec-websocket-key']`.
+ */
+export interface AuthenticatedConnection {
+    documentId: string;
+    connectionId: string;
+    /** Tag returned via `room.onUpdate` so applications can audit edits. */
+    userId?: string;
+}
+export interface AttachRealtimeGatewayOptions {
+    /**
+     * Validate the upgrade request and map it to a documentId. Return `null`
+     * to reject. Throws are treated as 401 and the connection is closed.
+     */
+    authenticate: (req: UpgradeRequestInfo) => Promise<AuthenticatedConnection | null>;
+    /** Storage adapter. Defaults to a noop in-memory persistence (rooms are not durable). */
+    persistence?: DocumentPersistence;
+    /**
+     * Reap a room after it has had zero connections for this many ms. Default 60000.
+     * Set to `Infinity` to disable reaping.
+     */
+    idleTimeoutMs?: number;
+    /** Debounce window for persistence writes (ms). Forwarded to `bindPersistence`. */
+    persistenceDebounceMs?: number;
+    /** Maximum time between writes (ms). Forwarded to `bindPersistence`. */
+    persistenceMaxIdleMs?: number;
+    /** Called whenever a room is created. Useful for metrics. */
+    onRoomOpen?: (documentId: string) => void;
+    /** Called whenever a room is destroyed. Useful for metrics. */
+    onRoomClose?: (documentId: string) => void;
+    /** Called when a persistence save fails. Defaults to console.error. */
+    onPersistenceError?: (documentId: string, err: unknown) => void;
+}
+export interface RealtimeGateway {
+    /** Number of currently active rooms. Useful for /health endpoints. */
+    readonly roomCount: number;
+    /** Number of currently connected sockets across all rooms. */
+    readonly connectionCount: number;
+    /**
+     * Bind an authenticated socket to its room. Call this from your HTTP
+     * upgrade handler after `wss.handleUpgrade(...)` has produced a socket.
+     */
+    handleConnection(socket: WebSocketLike, req: UpgradeRequestInfo): Promise<void>;
+    /**
+     * Force-close every connection, flush every room, and tear everything
+     * down. Call from your process's SIGTERM handler.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a realtime gateway. The returned object is intended to live for the
+ * lifetime of the server process — one per node. Calling
+ * `shutdown()` is mandatory for graceful exit (it flushes pending writes).
+ */
+export declare function createRealtimeGateway(opts: AttachRealtimeGatewayOptions): RealtimeGateway;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/realtime/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../src/realtime/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAA;IAC5B,oCAAoC;IACpC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,0CAA0C;IAC1C,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAA;IAC/D,iCAAiC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IAC7C,iCAAiC;IACjC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;CACxD;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX,uFAAuF;IACvF,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;CACtD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;IAClF,yFAAyF;IACzF,WAAW,CAAC,EAAE,mBAAmB,CAAA;IACjC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,6DAA6D;IAC7D,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAA;IAC1C,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAA;CAChE;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/E;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,eAAe,CAuLzF"}