@pascal-app/core 1.0.3 → 1.0.5

package/dist/store/history-control.d.ts

@@ -1,19 +1,43 @@
 import type { Collection, CollectionId } from '../schema/collections.js';
 import type { SceneMaterial, SceneMaterialId } from '../schema/scene-material.js';
 import type { AnyNode, AnyNodeId } from '../schema/types.js';
+export declare function isRestoringSceneHistory(): boolean;
+export declare function runAsSceneHistoryRestore<T>(run: () => T): T;
+/**
+ * Whether the scene is being written by a collaborator's change (a shared
+ * operation or snapshot applied from the host), not by this client — what a
+ * live session that takes back its own writes must leave alone.
+ */
+export declare function isApplyingRemoteSceneChange(): boolean;
+export declare function runAsRemoteSceneChange<T>(run: () => T): T;
 export type SceneSnapshot = {
     nodes: Record<AnyNodeId, AnyNode>;
     rootNodeIds: AnyNodeId[];
     collections: Record<CollectionId, Collection>;
     materials: Record<SceneMaterialId, SceneMaterial>;
     installedPlugins: string[];
+    hasExplicitPluginInstallState?: boolean;
 };
 export type SceneCommitOrigin = 'local' | 'load' | 'host';
+/**
+ * Who made a local commit when it was not the person at the keyboard: `agent`
+ * is an AI agent's tool write. Presentation reads it (the construction reveal
+ * stages agent writes); the document and its history are the same either way.
+ */
+export type SceneCommitAuthor = 'agent';
 export type SceneCommit = {
     origin: SceneCommitOrigin;
+    /** Absent for the person's own edits. See `runAsSceneCommitAuthor`. */
+    author?: SceneCommitAuthor;
     before: SceneSnapshot;
     current: SceneSnapshot;
     changedNodeIds?: ReadonlySet<AnyNodeId>;
+    /**
+     * What the structure reconciler wrote while this commit was made (plates, ceilings, side
+     * classification): derived from an edit, not authored by it. Each node it wrote, with the fields it
+     * wrote (`'all'` for one it created or deleted). Presentation does not play these as the edit's own.
+     */
+    derivedWrites?: ReadonlyMap<AnyNodeId, ReadonlySet<string> | 'all'>;
 };
 export type SceneCommitListener = (commit: SceneCommit) => void;
 type TemporalStoreLike = {
@@ -37,12 +61,61 @@ type TemporalHistoryStoreLike<TPastState> = {
 export declare function activeSceneCommitNodeIds(): ReadonlySet<AnyNodeId> | undefined;
 export declare function addActiveSceneCommitNodeIds(nodeIds: Iterable<AnyNodeId>): void;
 export declare function runWithSceneCommitNodeIds<TResult>(nodeIds: Iterable<AnyNodeId>, run: () => TResult): TResult;
+/**
+ * Registers something that must let go of the scene before anything writes it: a preview that
+ * shows another state (`scene-preview.ts`) would otherwise swallow the write or have it land on
+ * the wrong state. Returns the unregister.
+ */
+export declare function registerSceneWriteGuard(guard: () => void): () => void;
+export declare function runSceneWriteGuards(): void;
+export declare function activeSceneCommitAuthor(): SceneCommitAuthor | undefined;
+/** Commits made while `run` runs carry `author`. */
+export declare function runAsSceneCommitAuthor<TResult>(author: SceneCommitAuthor, run: () => TResult): TResult;
+/**
+ * The async form of `runAsSceneCommitAuthor`, for work that awaits between its
+ * writes: commits carry `author` until the returned release runs. Every commit
+ * in that window carries it, whoever made it, so hold it only around the
+ * author's own work. Release is idempotent.
+ */
+export declare function acquireSceneCommitAuthor(author: SceneCommitAuthor): () => void;
 export declare function areSceneSnapshotsEqual(left: SceneSnapshot, right: SceneSnapshot): boolean;
 export declare function subscribeSceneCommits(listener: SceneCommitListener): () => void;
+/**
+ * Records what the derived-writer capability writes, for the commit that follows: each node, and the
+ * fields written (none given: the node as a whole).
+ */
+export declare function noteDerivedNodeWrites(writes: Iterable<{
+    id: AnyNodeId;
+    fields?: Iterable<string>;
+}>): void;
 export declare function notifySceneCommit(commit: SceneCommit): void;
 export declare function pauseSceneHistory(sceneStore: TemporalStoreLike): void;
 export declare function resumeSceneHistory(sceneStore: TemporalStoreLike): void;
 export declare function acquireSceneHistoryPause(sceneStore: TemporalStoreLike): () => void;
+export type SceneHistoryPauseSession = {
+    /**
+     * Runs one committing write with this gesture's pauses lifted, then takes them back.
+     * The write lands as tracked history only when no other owner is pausing it.
+     */
+    commitStep<T>(write: () => T): T;
+    /** Releases this session's pause. Idempotent. */
+    end(): void;
+};
+export type SceneHistoryPauseSessionOptions = {
+    /** Sessions with the same key co-own one gesture; see `beginSceneHistoryPauseSession`. */
+    gesture?: string;
+};
+/**
+ * Holds a refcounted pause for a whole gesture (drag). Unlike a raw
+ * `temporal.pause()`, cooperating systems see the gesture through
+ * `getSceneHistoryPauseDepth()`, and their balanced pause/resume pairs cannot
+ * resume history under it.
+ *
+ * Sessions opened with the same `gesture` key co-own the gesture (the 3D mover
+ * and the 2D move overlay of one moving node): either one's `commitStep` lifts
+ * both pauses, so whichever view drops records the one step.
+ */
+export declare function beginSceneHistoryPauseSession(sceneStore: TemporalStoreLike, options?: SceneHistoryPauseSessionOptions): SceneHistoryPauseSession;
 export declare function getSceneHistoryPauseDepth(): number;
 export declare function resetSceneHistoryPauseDepth(): void;
 export declare function runAsSingleSceneHistoryStep<TPastState, TResult>(sceneStore: TemporalHistoryStoreLike<TPastState>, run: () => TResult): TResult;

package/dist/store/history-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"history-control.d.ts","sourceRoot":"","sources":["../../src/store/history-control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAKzD,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IACjC,WAAW,EAAE,SAAS,EAAE,CAAA;IACxB,WAAW,EAAE,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAA;IAC7C,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAA;IACjD,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;AAEzD,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,iBAAiB,CAAA;IACzB,MAAM,EAAE,aAAa,CAAA;IACrB,OAAO,EAAE,aAAa,CAAA;IACtB,cAAc,CAAC,EAAE,WAAW,CAAC,SAAS,CAAC,CAAA;CACxC,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;AAE/D,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE;QACR,QAAQ,IAAI;YACV,KAAK,IAAI,IAAI,CAAA;YACb,MAAM,IAAI,IAAI,CAAA;SACf,CAAA;KACF,CAAA;CACF,CAAA;AAED,KAAK,wBAAwB,CAAC,UAAU,IAAI;IAC1C,QAAQ,EAAE;QACR,QAAQ,IAAI;YACV,UAAU,EAAE,UAAU,EAAE,CAAA;SACzB,CAAA;QACD,QAAQ,CAAC,KAAK,EAAE;YAAE,UAAU,EAAE,UAAU,EAAE,CAAA;SAAE,GAAG,IAAI,CAAA;KACpD,CAAA;CACF,CAAA;AAeD,wBAAgB,wBAAwB,IAAI,WAAW,CAAC,SAAS,CAAC,GAAG,SAAS,CAO7E;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAI9E;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAC/C,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC,EAC5B,GAAG,EAAE,MAAM,OAAO,GACjB,OAAO,CAYT;AA2BD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAQzF;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAK/E;AAYD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAyB3D;AAyBD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAKrE;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI,CAStE;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAelF;AAED,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD;AAkBD,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,OAAO,EAC7D,UAAU,EAAE,wBAAwB,CAAC,UAAU,CAAC,EAChD,GAAG,EAAE,MAAM,OAAO,GACjB,OAAO,CAuBT"}
+{"version":3,"file":"history-control.d.ts","sourceRoot":"","sources":["../../src/store/history-control.ts"],"names":[],"mappings":"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"}

package/dist/store/history-control.js

@@ -1,3 +1,35 @@
+import { withSceneHistoryDraftSuspended } from './history-drafts.js';
+let sceneHistoryRestoreDepth = 0;
+export function isRestoringSceneHistory() {
+    return sceneHistoryRestoreDepth > 0;
+}
+export function runAsSceneHistoryRestore(run) {
+    sceneHistoryRestoreDepth += 1;
+    try {
+        return run();
+    }
+    finally {
+        sceneHistoryRestoreDepth -= 1;
+    }
+}
+let remoteSceneOperationDepth = 0;
+/**
+ * Whether the scene is being written by a collaborator's change (a shared
+ * operation or snapshot applied from the host), not by this client — what a
+ * live session that takes back its own writes must leave alone.
+ */
+export function isApplyingRemoteSceneChange() {
+    return remoteSceneOperationDepth > 0;
+}
+export function runAsRemoteSceneChange(run) {
+    remoteSceneOperationDepth += 1;
+    try {
+        return run();
+    }
+    finally {
+        remoteSceneOperationDepth -= 1;
+    }
+}
 let sceneHistoryPauseDepth = 0;
 const sceneHistoryPauseLeases = new Set();
 const sceneCommitListeners = new Set();
@@ -41,6 +73,57 @@ export function runWithSceneCommitNodeIds(nodeIds, run) {
         }
     }
 }
+const sceneWriteGuards = new Set();
+/**
+ * Registers something that must let go of the scene before anything writes it: a preview that
+ * shows another state (`scene-preview.ts`) would otherwise swallow the write or have it land on
+ * the wrong state. Returns the unregister.
+ */
+export function registerSceneWriteGuard(guard) {
+    sceneWriteGuards.add(guard);
+    return () => {
+        sceneWriteGuards.delete(guard);
+    };
+}
+export function runSceneWriteGuards() {
+    for (const guard of [...sceneWriteGuards])
+        guard();
+}
+const sceneCommitAuthorScopes = [];
+const sceneCommitAuthorLeases = new Map();
+export function activeSceneCommitAuthor() {
+    const scoped = sceneCommitAuthorScopes.at(-1);
+    if (scoped)
+        return scoped;
+    for (const author of sceneCommitAuthorLeases.values())
+        return author;
+    return undefined;
+}
+/** Commits made while `run` runs carry `author`. */
+export function runAsSceneCommitAuthor(author, run) {
+    runSceneWriteGuards();
+    sceneCommitAuthorScopes.push(author);
+    try {
+        return run();
+    }
+    finally {
+        sceneCommitAuthorScopes.pop();
+    }
+}
+/**
+ * The async form of `runAsSceneCommitAuthor`, for work that awaits between its
+ * writes: commits carry `author` until the returned release runs. Every commit
+ * in that window carries it, whoever made it, so hold it only around the
+ * author's own work. Release is idempotent.
+ */
+export function acquireSceneCommitAuthor(author) {
+    runSceneWriteGuards();
+    const lease = Symbol('scene-commit-author');
+    sceneCommitAuthorLeases.set(lease, author);
+    return () => {
+        sceneCommitAuthorLeases.delete(lease);
+    };
+}
 function areSemanticValuesEqual(left, right) {
     if (Object.is(left, right))
         return true;
@@ -71,7 +154,8 @@ export function areSceneSnapshotsEqual(left, right) {
         areSemanticValuesEqual(left.rootNodeIds, right.rootNodeIds) &&
         areSemanticValuesEqual(left.collections, right.collections) &&
         areSemanticValuesEqual(left.materials, right.materials) &&
-        areSemanticValuesEqual(left.installedPlugins, right.installedPlugins));
+        areSemanticValuesEqual(left.installedPlugins, right.installedPlugins) &&
+        (left.hasExplicitPluginInstallState ?? false) === (right.hasExplicitPluginInstallState ?? false));
 }
 export function subscribeSceneCommits(listener) {
     sceneCommitListeners.add(listener);
@@ -79,7 +163,26 @@ export function subscribeSceneCommits(listener) {
         sceneCommitListeners.delete(listener);
     };
 }
-function emitSceneCommit(commit) {
+let derivedWrites = new Map();
+/**
+ * Records what the derived-writer capability writes, for the commit that follows: each node, and the
+ * fields written (none given: the node as a whole).
+ */
+export function noteDerivedNodeWrites(writes) {
+    for (const { id, fields } of writes) {
+        const noted = derivedWrites.get(id);
+        if (noted === 'all')
+            continue;
+        if (!fields)
+            derivedWrites.set(id, 'all');
+        else
+            derivedWrites.set(id, new Set([...(noted ?? []), ...fields]));
+    }
+}
+function emitSceneCommit(authored) {
+    const derived = derivedWrites;
+    derivedWrites = new Map();
+    const commit = derived.size > 0 ? { ...authored, derivedWrites: derived } : authored;
     for (const listener of [...sceneCommitListeners]) {
         try {
             listener(commit);
@@ -90,16 +193,23 @@ function emitSceneCommit(commit) {
     }
 }
 export function notifySceneCommit(commit) {
-    if (areSceneSnapshotsEqual(commit.before, commit.current))
+    if (areSceneSnapshotsEqual(commit.before, commit.current)) {
+        if (sceneCommitTransactionDepth === 0)
+            derivedWrites = new Map();
         return;
+    }
+    const author = commit.author ?? activeSceneCommitAuthor();
     const contextualCommit = {
         ...commit,
+        ...(author ? { author } : {}),
         changedNodeIds: mergedNodeIds(commit.changedNodeIds, activeSceneCommitNodeIds()),
     };
     if (sceneCommitTransactionDepth > 0) {
         if (pendingSceneCommit) {
+            const pendingAuthor = pendingSceneCommit.author ?? contextualCommit.author;
             pendingSceneCommit = {
                 origin: pendingSceneCommit.origin,
+                ...(pendingAuthor ? { author: pendingAuthor } : {}),
                 before: pendingSceneCommit.before,
                 current: contextualCommit.current,
                 changedNodeIds: mergedNodeIds(pendingSceneCommit.changedNodeIds, contextualCommit.changedNodeIds),
@@ -127,9 +237,12 @@ function endSceneCommitTransaction() {
         return;
     const commit = pendingSceneCommit;
     pendingSceneCommit = null;
-    if (commit && !areSceneSnapshotsEqual(commit.before, commit.current)) {
+    if (!commit)
+        return;
+    if (areSceneSnapshotsEqual(commit.before, commit.current))
+        derivedWrites = new Map();
+    else
         emitSceneCommit(commit);
-    }
 }
 export function pauseSceneHistory(sceneStore) {
     if (getSceneHistoryPauseDepth() === 0) {
@@ -163,12 +276,77 @@ export function acquireSceneHistoryPause(sceneStore) {
         }
     };
 }
+const gesturePauseHolders = new Map();
+const livePauseHolders = new Set();
+/** Lifts `holders`' pauses for `write`, then takes back those that have not ended. */
+function runWithHoldersLifted(sceneStore, holders, write) {
+    const lifted = [...holders].filter((holder) => holder.release);
+    for (const holder of lifted) {
+        const release = holder.release;
+        holder.release = null;
+        release();
+    }
+    try {
+        return write();
+    }
+    finally {
+        for (const holder of lifted) {
+            if (!holder.ended)
+                holder.release = acquireSceneHistoryPause(sceneStore);
+        }
+    }
+}
+/**
+ * Holds a refcounted pause for a whole gesture (drag). Unlike a raw
+ * `temporal.pause()`, cooperating systems see the gesture through
+ * `getSceneHistoryPauseDepth()`, and their balanced pause/resume pairs cannot
+ * resume history under it.
+ *
+ * Sessions opened with the same `gesture` key co-own the gesture (the 3D mover
+ * and the 2D move overlay of one moving node): either one's `commitStep` lifts
+ * both pauses, so whichever view drops records the one step.
+ */
+export function beginSceneHistoryPauseSession(sceneStore, options = {}) {
+    const { gesture } = options;
+    const holder = {
+        release: acquireSceneHistoryPause(sceneStore),
+        ended: false,
+    };
+    livePauseHolders.add(holder);
+    let coOwners = new Set([holder]);
+    if (gesture) {
+        coOwners = gesturePauseHolders.get(gesture) ?? new Set();
+        coOwners.add(holder);
+        gesturePauseHolders.set(gesture, coOwners);
+    }
+    return {
+        commitStep(write) {
+            return runWithHoldersLifted(sceneStore, coOwners, () => withSceneHistoryDraftSuspended(gesture, write));
+        },
+        end() {
+            if (holder.ended)
+                return;
+            holder.ended = true;
+            holder.release?.();
+            holder.release = null;
+            livePauseHolders.delete(holder);
+            coOwners.delete(holder);
+            if (gesture && coOwners.size === 0)
+                gesturePauseHolders.delete(gesture);
+        },
+    };
+}
 export function getSceneHistoryPauseDepth() {
     return sceneHistoryPauseDepth + sceneHistoryPauseLeases.size;
 }
 export function resetSceneHistoryPauseDepth() {
     sceneHistoryPauseDepth = 0;
     sceneHistoryPauseLeases.clear();
+    // Open sessions no longer hold anything; a later commitStep must not re-take their pause.
+    for (const holder of livePauseHolders)
+        holder.release = null;
+    livePauseHolders.clear();
+    gesturePauseHolders.clear();
 }
 function retainedPastStateCount(before, after) {
     for (let start = 0; start < before.length; start += 1) {

package/dist/store/history-drafts.d.ts

@@ -0,0 +1,48 @@
+import type { AnyNode, AnyNodeId } from '../schema/types.js';
+type NodeMap = Record<AnyNodeId, AnyNode>;
+/**
+ * Registers `id` as a carried draft; returns the call that ends it. A second holder of a node
+ * already carried (split view) shares its registration, which ends with its last holder.
+ */
+export declare function beginSceneHistoryDraft(id: AnyNodeId, original: AnyNode | null, nodes: NodeMap): () => void;
+/**
+ * Runs a gesture's committing write with `id` visible to history, so whichever co-owner of the
+ * gesture drops it (the 3D mover or the 2D move overlay) records the change.
+ */
+export declare function withSceneHistoryDraftSuspended<T>(id: string | undefined, write: () => T): T;
+export declare function hasSceneHistoryDrafts(): boolean;
+/**
+ * Records a carry's own write: each field it changed on an adopted draft is held with the value
+ * it had before (kept from an earlier carry write while the carry still held it) and the value
+ * the carry wrote. A write back to that earlier value ends the hold.
+ */
+export declare function noteSceneHistoryDraftWrite(before: NodeMap, after: NodeMap): void;
+/**
+ * Updates that put an adopted draft's held fields back to their values before the carry,
+ * leaving everything others wrote. A parent that no longer exists is never restored.
+ */
+export declare function sceneHistoryDraftRevertUpdates(nodes: NodeMap, ids: Iterable<AnyNodeId>): Array<{
+    id: AnyNodeId;
+    data: Record<string, unknown>;
+}>;
+/**
+ * A drop committed these drafts' carried state: nothing the carry wrote is left to revert, so a
+ * co-holder's later cancel or cleanup (the 3D mover after a split-view 2D drop) keeps the drop.
+ */
+export declare function settleSceneHistoryDrafts(ids: Iterable<AnyNodeId>): void;
+export declare function clearSceneHistoryDrafts(): void;
+/** Created drafts: history excludes them (and their subtrees) like fresh-placement nodes. */
+export declare function createdSceneHistoryDraftIds(): AnyNodeId[];
+/**
+ * Records the carry-owned fields of adopted drafts as they were before the carry. The original
+ * parent link is restored only while that parent still exists. `historyNodes` may be `nodes`.
+ */
+export declare function withAdoptedDraftsAsOriginal(nodes: NodeMap, historyNodes: NodeMap): NodeMap;
+/**
+ * After an undo or redo, puts back what the carry holds: a created draft (and its subtree)
+ * whole, and on an adopted draft only its held fields, as they were just before the jump.
+ * Everything else keeps the jumped-to state. Returns null when nothing needs restoring.
+ */
+export declare function withDraftsRestored(before: NodeMap, after: NodeMap): NodeMap | null;
+export {};
+//# sourceMappingURL=history-drafts.d.ts.map

package/dist/store/history-drafts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-drafts.d.ts","sourceRoot":"","sources":["../../src/store/history-drafts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAgDzD,KAAK,OAAO,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;AAWzC;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,SAAS,EACb,QAAQ,EAAE,OAAO,GAAG,IAAI,EACxB,KAAK,EAAE,OAAO,GACb,MAAM,IAAI,CAmBZ;AAcD;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAW3F;AA4BD,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAwChF;AAiCD;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,GACvB,KAAK,CAAC;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAsBzD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAOvE;AAED,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED,6FAA6F;AAC7F,wBAAgB,2BAA2B,IAAI,SAAS,EAAE,CAIzD;AAiDD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,GAAG,OAAO,CAmC1F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAwFlF"}