@aphexcms/cms-core 9.6.0 → 9.8.0

package/dist/local-api/collection-api.d.ts

@@ -9,6 +9,7 @@ import type { LocalAPIContext } from './types.js';
 import type { SchemaType } from '../types/schemas.js';
 import { PermissionChecker } from './permissions.js';
 import { type DocumentValidationResult } from '../field-validation/utils.js';
+import type { Job } from '../types/events.js';
 /**
  * Result from create/update operations that includes validation
  */
@@ -158,6 +159,7 @@ export declare class CollectionAPI<T = Document> {
     update(context: LocalAPIContext, id: string, data: Partial<Omit<T, 'id' | '_meta'>>, options?: {
         publish?: boolean;
         skipVersioning?: boolean;
+        expectedRevision?: number;
     }): Promise<DocumentResult<T> | null>;
     /**
      * Delete a document
@@ -182,7 +184,16 @@ export declare class CollectionAPI<T = Document> {
      * );
      * ```
      */
-    publish(context: LocalAPIContext, id: string): Promise<T | null>;
+    /**
+     * Publish without a version snapshot — the branch taken when there's no version service or
+     * the caller passed `skipVersioning`. Still emits `document.published` (and its outbox row)
+     * atomically with the publish, so the domain fact fires on EVERY publish path, not only the
+     * versioned one. The versioned branch emits the same event from `versionService.publishTx`.
+     */
+    private publishWithoutVersion;
+    publish(context: LocalAPIContext, id: string, options?: {
+        expectedRevision?: number;
+    }): Promise<T | null>;
     /**
      * Unpublish a document
      *
@@ -194,6 +205,42 @@ export declare class CollectionAPI<T = Document> {
      * );
      * ```
      */
-    unpublish(context: LocalAPIContext, id: string): Promise<T | null>;
+    unpublish(context: LocalAPIContext, id: string, options?: {
+        expectedRevision?: number;
+    }): Promise<T | null>;
+    /**
+     * Pending scheduled publish/unpublish jobs for one document. Scheduled jobs are few
+     * and `pending` is a small set, so filtering the org's pending jobs by documentId in
+     * memory is cheap and avoids a dialect-specific JSON query on the hot editor path.
+     */
+    private pendingScheduledFor;
+    /**
+     * Cancel any pending schedule of ONE direction for a document — used when a manual
+     * publish/unpublish supersedes a schedule of the same kind. Only same-direction is
+     * cancelled on purpose: "publish now, auto-unpublish Friday" and "unpublish now,
+     * republish Monday" are legitimate future transitions, so a manual publish leaves a
+     * pending unpublish (and vice versa) alone. Without this, the queued job would fire at
+     * `runAt` and re-run the same transition — re-emitting `document.published`/`unpublished`
+     * and firing every consumer a second time (duplicate notifications, webhooks, cache busts).
+     */
+    private cancelPendingScheduleOfType;
+    /**
+     * Schedule a publish for a future `runAt`. Enqueues a `document.publish` job; the
+     * worker runs `publish()` at that time (re-validating, guarding references, emitting
+     * `document.published`). The permission check happens NOW — you must be able to publish
+     * to schedule one — so an unauthorized caller can't queue work to run later as the system.
+     * Actual publish-time validation still runs then, so a doc that goes invalid before
+     * `runAt` simply fails/retries rather than publishing bad content.
+     *
+     * Replace semantics: any existing pending schedule for this document is cancelled first,
+     * so a document has at most one pending schedule (rescheduling can't double-publish).
+     */
+    schedulePublish(context: LocalAPIContext, id: string, runAt: Date): Promise<Job>;
+    /** Schedule an unpublish for a future `runAt`. Permission-checked now; replaces any existing pending schedule. */
+    scheduleUnpublish(context: LocalAPIContext, id: string, runAt: Date): Promise<Job>;
+    /** Pending scheduled publish/unpublish jobs for a document (read-gated) — for the editor's schedule indicator. */
+    getScheduled(context: LocalAPIContext, id: string): Promise<Job[]>;
+    /** Cancel all pending scheduled publish/unpublish jobs for a document. Returns how many were cancelled. */
+    cancelScheduled(context: LocalAPIContext, id: string): Promise<number>;
 }
 //# sourceMappingURL=collection-api.d.ts.map

package/dist/local-api/collection-api.d.ts.map

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

package/dist/local-api/collection-api.js

@@ -5,6 +5,8 @@ import { singletonId } from '../schema-utils/singleton.js';
 import { validateDocumentData } from '../field-validation/utils.js';
 import { runDocumentHooks } from './hooks.js';
 import { collectReferenceIds } from '../utils/reference-walk.js';
+import { emitDocumentPublished } from '../events/emit.js';
+import { DOCUMENT_PUBLISH_JOB, DOCUMENT_UNPUBLISH_JOB } from '../jobs/document-jobs.js';
 import { hiddenReadFields, hiddenWriteFields, dropLockedWrites, stripHiddenFields } from '../field-access.js';
 const EMPTY_SET = new Set();
 /**
@@ -54,7 +56,11 @@ function transformDocument(doc, perspective = 'draft', hiddenFields) {
             createdBy: doc.createdBy,
             updatedBy: doc.updatedBy,
             publishedAt: doc.publishedAt,
-            publishedHash: doc.publishedHash
+            publishedHash: doc.publishedHash,
+            // CAS guard — callers echo this back as `expectedRevision` on their next
+            // write so a stale save (second tab, an agent) surfaces as a conflict
+            // instead of silently overwriting a change made after this read.
+            revision: doc.revision
         }
     };
 }
@@ -346,24 +352,45 @@ export class CollectionAPI {
                 throw new Error(`Cannot publish: validation errors - ${errorMessage}`);
             }
         }
-        // Create document with normalized data (dates in ISO format)
-        const document = await this.databaseAdapter.createDocument({
-            organizationId: context.organizationId,
-            type: this.collectionName,
-            draftData: validationResult.normalizedData,
-            createdBy: context.user?.id,
-            id: options?.id
-        });
-        await this.syncReferences(context.organizationId, document.id, validationResult.normalizedData);
-        // Create initial draft version
-        if (this.versionService && !options?.skipVersioning) {
-            await this.versionService.createVersion(this.databaseAdapter, context.organizationId, document.id, 'draft', validationResult.normalizedData, context.user?.id);
-        }
-        // Publish immediately if requested (validation already done above)
+        // versionService present unless the caller opted out of versioning; capturing it
+        // here narrows the type so the tx callbacks don't need non-null assertions.
+        const versionService = options?.skipVersioning ? undefined : this.versionService;
+        // Publish path: create + draft-version + publish + publish-version must commit
+        // together, or a crash between them leaves an inconsistent document (a draft that
+        // was meant to be published, or a published doc with no version row). Run all of
+        // it in one transaction. Validation already passed the block-check above, so we
+        // never enter the tx with invalid data.
         if (options?.publish) {
-            const published = this.versionService && !options?.skipVersioning
-                ? await this.versionService.publishWithVersion(this.databaseAdapter, context.organizationId, document.id)
-                : await this.databaseAdapter.publishDoc(context.organizationId, document.id);
+            const { document, published } = await this.databaseAdapter.withTransaction(async (tx) => {
+                const document = await tx.createDocument({
+                    organizationId: context.organizationId,
+                    type: this.collectionName,
+                    draftData: validationResult.normalizedData,
+                    createdBy: context.user?.id,
+                    id: options?.id
+                });
+                if (versionService) {
+                    await versionService.snapshotTx(tx, context.organizationId, document.id, 'draft', validationResult.normalizedData, context.user?.id);
+                }
+                // Either branch emits `document.published` in this same tx: the versioned path
+                // from publishTx, the non-versioned path via emitDocumentPublished here.
+                let published;
+                if (versionService) {
+                    published = await versionService.publishTx(tx, context.organizationId, document.id);
+                }
+                else {
+                    published = await tx.publishDoc(context.organizationId, document.id);
+                    if (published)
+                        await emitDocumentPublished(tx, context.organizationId, published);
+                }
+                return { document, published };
+            });
+            // Post-commit side effects: ref index is best-effort, retention is one pass
+            // covering both the draft and publish snapshots written inside the tx.
+            await this.syncReferences(context.organizationId, document.id, validationResult.normalizedData);
+            if (versionService) {
+                await versionService.enforceRetentionFor(this.databaseAdapter, context.organizationId, document.id);
+            }
             if (published) {
                 if (this.documentCache) {
                     await this.documentCache.invalidateDocument(context.organizationId, document.id);
@@ -374,6 +401,27 @@ export class CollectionAPI {
                     validation: validationResult
                 };
             }
+            // publishDoc returned null (unexpected): fall back to returning the draft.
+            if (this.documentCache) {
+                await this.documentCache.invalidateCollection(context.organizationId, this.collectionName);
+            }
+            return {
+                document: transformDocument(document, 'draft'),
+                validation: validationResult
+            };
+        }
+        // Draft-only path.
+        const document = await this.databaseAdapter.createDocument({
+            organizationId: context.organizationId,
+            type: this.collectionName,
+            draftData: validationResult.normalizedData,
+            createdBy: context.user?.id,
+            id: options?.id
+        });
+        await this.syncReferences(context.organizationId, document.id, validationResult.normalizedData);
+        // Create initial draft version
+        if (versionService) {
+            await versionService.createVersion(this.databaseAdapter, context.organizationId, document.id, 'draft', validationResult.normalizedData, context.user?.id);
         }
         if (this.documentCache) {
             await this.documentCache.invalidateCollection(context.organizationId, this.collectionName);
@@ -436,9 +484,12 @@ export class CollectionAPI {
         const validationResult = await validateDocumentData(this._schema, hookedData);
         // Update draft with normalized data (dates in ISO format)
         // Use VersionService for atomic save + version creation if available
+        // RevisionConflictError propagates un-swallowed — a stale caller (a second
+        // tab, an agent that read the doc seconds ago) gets a surfaced conflict
+        // instead of silently overwriting a change made after it read the document.
         const document = this.versionService && !options?.skipVersioning
-            ? await this.versionService.saveWithVersion(this.databaseAdapter, context.organizationId, id, validationResult.normalizedData, context.user?.id)
-            : await this.databaseAdapter.updateDocDraft(context.organizationId, id, validationResult.normalizedData, context.user?.id);
+            ? await this.versionService.saveWithVersion(this.databaseAdapter, context.organizationId, id, validationResult.normalizedData, context.user?.id, options?.expectedRevision)
+            : await this.databaseAdapter.updateDocDraft(context.organizationId, id, validationResult.normalizedData, context.user?.id, options?.expectedRevision);
         if (!document) {
             return null;
         }
@@ -454,7 +505,7 @@ export class CollectionAPI {
             }
             const published = this.versionService && !options?.skipVersioning
                 ? await this.versionService.publishWithVersion(this.databaseAdapter, context.organizationId, document.id)
-                : await this.databaseAdapter.publishDoc(context.organizationId, document.id);
+                : await this.publishWithoutVersion(context.organizationId, document.id);
             if (published) {
                 // Invalidate cache
                 if (this.documentCache) {
@@ -516,7 +567,21 @@ export class CollectionAPI {
      * );
      * ```
      */
-    async publish(context, id) {
+    /**
+     * Publish without a version snapshot — the branch taken when there's no version service or
+     * the caller passed `skipVersioning`. Still emits `document.published` (and its outbox row)
+     * atomically with the publish, so the domain fact fires on EVERY publish path, not only the
+     * versioned one. The versioned branch emits the same event from `versionService.publishTx`.
+     */
+    async publishWithoutVersion(organizationId, id, expectedRevision) {
+        return this.databaseAdapter.withTransaction(async (tx) => {
+            const published = await tx.publishDoc(organizationId, id, expectedRevision);
+            if (published)
+                await emitDocumentPublished(tx, organizationId, published);
+            return published;
+        });
+    }
+    async publish(context, id, options) {
         // Fetch first so policies can inspect the target. Order matters here:
         // 404s beat 403s for missing docs.
         const document = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
@@ -549,10 +614,12 @@ export class CollectionAPI {
                 throw new Error(`Cannot publish — ${unpublished.length} referenced document(s) are not published: ${names}`);
             }
         }
-        // Validation passed - proceed with publish (with version if service available)
+        // Validation passed - proceed with publish (with version if service available). Either
+        // branch emits `document.published`: the versioned path from publishTx, the non-versioned
+        // path from publishWithoutVersion.
         const publishedDocument = this.versionService
-            ? await this.versionService.publishWithVersion(this.databaseAdapter, context.organizationId, id)
-            : await this.databaseAdapter.publishDoc(context.organizationId, id);
+            ? await this.versionService.publishWithVersion(this.databaseAdapter, context.organizationId, id, options?.expectedRevision)
+            : await this.publishWithoutVersion(context.organizationId, id, options?.expectedRevision);
         if (!publishedDocument) {
             return null;
         }
@@ -561,6 +628,9 @@ export class CollectionAPI {
             await this.documentCache.invalidateDocument(context.organizationId, id);
             await this.documentCache.invalidateCollection(context.organizationId, this.collectionName);
         }
+        // This manual publish supersedes any pending scheduled publish — cancel it so the queued
+        // job doesn't fire later and re-emit `document.published` (a pending unpublish is left as-is).
+        await this.cancelPendingScheduleOfType(context.organizationId, id, DOCUMENT_PUBLISH_JOB);
         return transformDocument(publishedDocument, 'published');
     }
     /**
@@ -574,13 +644,13 @@ export class CollectionAPI {
      * );
      * ```
      */
-    async unpublish(context, id) {
+    async unpublish(context, id, options) {
         // Fetch target for policy inspection before mutating.
         const existing = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
         if (!existing)
             return null;
         await this.permissions.canUnpublish(context, this.collectionName, existing);
-        const document = await this.databaseAdapter.unpublishDoc(context.organizationId, id);
+        const document = await this.databaseAdapter.unpublishDoc(context.organizationId, id, options?.expectedRevision);
         if (!document) {
             return null;
         }
@@ -589,6 +659,102 @@ export class CollectionAPI {
             await this.documentCache.invalidateDocument(context.organizationId, id);
             await this.documentCache.invalidateCollection(context.organizationId, this.collectionName);
         }
+        // This manual unpublish supersedes any pending scheduled unpublish — cancel it so the
+        // queued job doesn't fire later (a pending publish is left as-is: "unpublish now,
+        // republish Monday" is a legitimate transition).
+        await this.cancelPendingScheduleOfType(context.organizationId, id, DOCUMENT_UNPUBLISH_JOB);
         return transformDocument(document, 'draft');
     }
+    /**
+     * Pending scheduled publish/unpublish jobs for one document. Scheduled jobs are few
+     * and `pending` is a small set, so filtering the org's pending jobs by documentId in
+     * memory is cheap and avoids a dialect-specific JSON query on the hot editor path.
+     */
+    async pendingScheduledFor(organizationId, documentId) {
+        const page = await this.databaseAdapter.listJobs({
+            organizationId,
+            status: 'pending',
+            limit: 200
+        });
+        return page.items.filter((j) => (j.type === DOCUMENT_PUBLISH_JOB || j.type === DOCUMENT_UNPUBLISH_JOB) &&
+            j.payload.documentId === documentId);
+    }
+    /**
+     * Cancel any pending schedule of ONE direction for a document — used when a manual
+     * publish/unpublish supersedes a schedule of the same kind. Only same-direction is
+     * cancelled on purpose: "publish now, auto-unpublish Friday" and "unpublish now,
+     * republish Monday" are legitimate future transitions, so a manual publish leaves a
+     * pending unpublish (and vice versa) alone. Without this, the queued job would fire at
+     * `runAt` and re-run the same transition — re-emitting `document.published`/`unpublished`
+     * and firing every consumer a second time (duplicate notifications, webhooks, cache busts).
+     */
+    async cancelPendingScheduleOfType(organizationId, documentId, jobType) {
+        const pending = await this.pendingScheduledFor(organizationId, documentId);
+        for (const job of pending) {
+            if (job.type === jobType) {
+                await this.databaseAdapter.cancelJob(organizationId, job.id);
+            }
+        }
+    }
+    /**
+     * Schedule a publish for a future `runAt`. Enqueues a `document.publish` job; the
+     * worker runs `publish()` at that time (re-validating, guarding references, emitting
+     * `document.published`). The permission check happens NOW — you must be able to publish
+     * to schedule one — so an unauthorized caller can't queue work to run later as the system.
+     * Actual publish-time validation still runs then, so a doc that goes invalid before
+     * `runAt` simply fails/retries rather than publishing bad content.
+     *
+     * Replace semantics: any existing pending schedule for this document is cancelled first,
+     * so a document has at most one pending schedule (rescheduling can't double-publish).
+     */
+    async schedulePublish(context, id, runAt) {
+        const document = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
+        if (!document)
+            throw new Error('Document not found');
+        await this.permissions.canPublish(context, this.collectionName, document);
+        for (const existing of await this.pendingScheduledFor(context.organizationId, id)) {
+            await this.databaseAdapter.cancelJob(context.organizationId, existing.id);
+        }
+        return this.databaseAdapter.scheduleJob({
+            organizationId: context.organizationId,
+            type: DOCUMENT_PUBLISH_JOB,
+            payload: { documentId: id, documentType: this.collectionName },
+            runAt,
+            createdBy: context.user?.id ?? null
+        });
+    }
+    /** Schedule an unpublish for a future `runAt`. Permission-checked now; replaces any existing pending schedule. */
+    async scheduleUnpublish(context, id, runAt) {
+        const document = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
+        if (!document)
+            throw new Error('Document not found');
+        await this.permissions.canUnpublish(context, this.collectionName, document);
+        for (const existing of await this.pendingScheduledFor(context.organizationId, id)) {
+            await this.databaseAdapter.cancelJob(context.organizationId, existing.id);
+        }
+        return this.databaseAdapter.scheduleJob({
+            organizationId: context.organizationId,
+            type: DOCUMENT_UNPUBLISH_JOB,
+            payload: { documentId: id, documentType: this.collectionName },
+            runAt,
+            createdBy: context.user?.id ?? null
+        });
+    }
+    /** Pending scheduled publish/unpublish jobs for a document (read-gated) — for the editor's schedule indicator. */
+    async getScheduled(context, id) {
+        await this.permissions.canRead(context, this.collectionName);
+        return this.pendingScheduledFor(context.organizationId, id);
+    }
+    /** Cancel all pending scheduled publish/unpublish jobs for a document. Returns how many were cancelled. */
+    async cancelScheduled(context, id) {
+        const document = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, id);
+        if (!document)
+            throw new Error('Document not found');
+        await this.permissions.canPublish(context, this.collectionName, document);
+        const pending = await this.pendingScheduledFor(context.organizationId, id);
+        for (const job of pending) {
+            await this.databaseAdapter.cancelJob(context.organizationId, job.id);
+        }
+        return pending.length;
+    }
 }

package/dist/mcp/tools.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { CMSInstances } from '../hooks.js';
 import type { LocalAPIContext } from '../local-api/index.js';
+import type { AgentToolDefinition, AgentToolExecutor } from '../types/agent-tools.js';
 export interface McpToolResult {
     content: Array<{
         type: 'text';
@@ -19,10 +20,44 @@ export interface McpToolDeps {
     aphexCMS: CMSInstances;
     context: LocalAPIContext;
 }
+/** One content tool: its serializable definition plus the function that runs it. */
+export interface ContentAgentTool {
+    definition: AgentToolDefinition<any>;
+    execute: AgentToolExecutor<any>;
+}
+/**
+ * The content-plane tools, safe to expose against a live instance: all writes go through
+ * LocalAPI, so a read-only API key is rejected by the permission layer, not by this
+ * registry. `requiredCapabilities` here is the advertisement/execution gate for the new
+ * agent-tool contract; document tools additionally get real enforcement downstream from
+ * `CollectionAPI`'s own `PermissionChecker` (unchanged) — `asset.read`/`asset.upload` have no
+ * such downstream check, so `list_assets`/`upload_asset` enforce it directly in `execute`.
+ */
+export declare const contentAgentTools: ContentAgentTool[];
+export interface ResolveAgentToolsOptions {
+    /** Set when the caller has a live document editor tab to bridge into — see
+     * `document-workspace-registry.svelte.ts` and `types/document-workspace.ts`. Only when
+     * this is present are the `execution: 'workspace'` tools (`content-workspace-tools.ts`)
+     * advertised at all; MCP and any request with no matching open document never see them,
+     * since there's no live draft on the other end to round-trip into. */
+    documentContext?: {
+        collection: string;
+        id: string;
+    };
+}
+/**
+ * The full set of tools this caller can see: core built-ins plus any
+ * plugin-contributed `aphex/agent/tool` parts their capabilities unlock
+ * (`partResolver.agentToolsForCapabilities`), plus the workspace-bridge tools when
+ * `documentContext` is given — the one shared list MCP, the in-admin agent runtime
+ * (`ai/run-agent-turn.ts`), and any other future tool-calling transport all resolve from.
+ * Core built-ins always win a name collision, since they're the platform's own contract.
+ */
+export declare function resolveAgentTools({ aphexCMS, context }: McpToolDeps, opts?: ResolveAgentToolsOptions): ContentAgentTool[];
 /**
- * Build the content-plane tools for one authenticated request.
- * Safe to expose against a live instance: all writes go through LocalAPI, so a
- * read-only API key is rejected by the permission layer, not by this registry.
+ * Adapt `resolveAgentTools` into the MCP SDK's expected shape for one authenticated
+ * request. All the actual tool logic lives in `contentAgentTools`/plugin parts above —
+ * this is purely a transport-shape + result-shape conversion.
  */
-export declare function buildContentTools({ aphexCMS, context }: McpToolDeps): McpTool[];
+export declare function buildContentTools(deps: McpToolDeps): McpTool[];
 //# sourceMappingURL=tools.d.ts.map

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/lib/mcp/tools.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAiB1D,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;CACzB;AAkID;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,WAAW,GAAG,OAAO,EAAE,CA6a/E"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/lib/mcp/tools.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EACX,mBAAmB,EACnB,iBAAiB,EAGjB,MAAM,sBAAsB,CAAC;AAoB9B,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,EAAE,CAAC,CAAC,WAAW,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,WAAW;IAC3B,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;CACzB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;CAChC;AA6HD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAAgB,EA0kB/C,CAAC;AASF,MAAM,WAAW,wBAAwB;IACxC;;;;0EAIsE;IACtE,eAAe,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,WAAW,EAClC,IAAI,CAAC,EAAE,wBAAwB,GAC7B,gBAAgB,EAAE,CAuBpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,EAAE,CAS9D"}