@bitmagic/world-forger 0.1.0

package/dist/pipeline/persist-level.d.ts

@@ -0,0 +1,82 @@
+import type { WorldJsonModification, WorldJsonShape } from './world-json-types.js';
+/**
+ * Pure builder for the world-forger persist step's world.json modifications —
+ * level-native (multi-level registry) with a legacy fallback, plus the
+ * orphaned-placeholder purge. Extracted from placeAndPersistLevel so the
+ * invariants are unit-testable without the WS/browser machinery:
+ *
+ * - A forge targets a LEVEL. Re-forging the same level asset replaces THAT
+ *   level's instances only; other levels and globals are untouched.
+ * - The registry is created on first forge (conversion moment: the game's
+ *   current baked world becomes level 1 and keeps its content; a procedural
+ *   game's forged level becomes levels[0]). An unconvertible legacy world
+ *   (voxelUrl with no matching vwld asset) falls back to today's legacy
+ *   semantics rather than failing the forge.
+ * - Legacy mirror invariant: voxelUrl/spawn/water globals are written ONLY
+ *   when the forged level is the start level. Dungeon doors/key pickups are
+ *   NOT part of that set — they stay level-native even for the start level
+ *   (frozen game code has no door system, and a global copy would leak one
+ *   level's doors into every other one). Atmosphere overrides ride the level
+ *   entry, except in legacy-fallback mode, where they mirror onto the globals
+ *   because there is no entry to carry them.
+ * - Reused assets (`reused: true` stubs) are never upserted — the existing
+ *   record may be an HQ model.
+ * - Purge: forge placeholders (`placeholder === true`) with zero instances
+ *   anywhere and no active HQ job are removed from assets[] (fixes the
+ *   re-forge pile-up). HQ/user/vwld assets are never purged.
+ */
+export interface PersistLevelInput {
+    existingWorldJson: WorldJsonShape;
+    /** The vwld level asset record (stable id when the orchestrator pre-mints). */
+    levelAsset: Record<string, unknown>;
+    levelName: string;
+    /** Baked archetype asset records; reused stubs carry `reused: true`. */
+    archetypeAssets: Array<Record<string, unknown>>;
+    /** Placed instance records (already reconciled to writable asset ids). */
+    instances: Array<Record<string, unknown>>;
+    spawn: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    spawnPoints: Array<Record<string, unknown>>;
+    playerSpawnRotationY: number | null;
+    /** World-space sea level; null = no water zones. */
+    waterLevelY: number | null;
+    /**
+     * World-space `DoorDefinition` records for THIS level (`levelId` injected
+     * here, `assetId` already injected by the pipeline). Omitted = leave the
+     * world's doors untouched; an empty array clears this level's doors (a
+     * dungeon re-forged as plain terrain). Never mirrored globally.
+     */
+    doors?: Array<Record<string, unknown>>;
+    /** World-space `KeyItemDefinition` records for THIS level; same semantics as `doors`. */
+    keyItems?: Array<Record<string, unknown>>;
+    /**
+     * Atmosphere overrides merged onto the level entry's `overrides` alongside
+     * `waterLevelY` (a dungeon's dark lighting + close fog). Enumerated to match
+     * the engine's `WorldLevelOverrides`.
+     */
+    levelOverrides?: {
+        fogConfig?: unknown;
+        lightingConfig?: unknown;
+        skyboxUrl?: string;
+    };
+    /** Asset ids with an HQ job in flight — never purged. */
+    activeHqAssetIds: Set<string>;
+    /** Explicit user intent for the boot level: true = make the forged level the
+     *  start, false = keep the current start. Omitted = default policy (steal
+     *  only when there is nothing else to boot into — first level / conversion
+     *  moment). */
+    makeStartLevel?: boolean;
+}
+export interface PersistLevelOutput {
+    modifications: WorldJsonModification[];
+    /** Null in legacy-fallback mode (no registry written). */
+    levelId: string | null;
+    isStartLevel: boolean;
+    purgedAssetIds: string[];
+    notes: string[];
+}
+export declare function buildLevelPersistModifications(input: PersistLevelInput): PersistLevelOutput;
+//# sourceMappingURL=persist-level.d.ts.map

package/dist/pipeline/persist-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist-level.d.ts","sourceRoot":"","sources":["../../src/pipeline/persist-level.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,qBAAqB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAU/F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,EAAE,cAAc,CAAC;IAClC,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD,0EAA0E;IAC1E,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,KAAK,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,oDAAoD;IACpD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,cAAc,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,cAAc,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,yDAAyD;IACzD,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B;;;mBAGe;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAuBD,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CA4L3F"}

package/dist/pipeline/persist-level.js

@@ -0,0 +1,201 @@
+import { getLevels, getStartLevel, isLevelsMode, mintLevelId, synthesizeLevel1, tagUntaggedInstances, } from './level-registry.js';
+/**
+ * Replace one level's slice of a level-scoped definition array (doors, key
+ * pickups) — the same rule the instance replace uses. In levels mode the level
+ * tag is authoritative: every entry of THIS level goes, the incoming set
+ * arrives tagged, and other levels are untouched. In legacy-fallback mode
+ * there is no level to tag with, so entries are replaced by id.
+ */
+function replaceLevelScoped(existing, incoming, levelId) {
+    const tagged = levelId === null
+        ? incoming
+        : incoming.map((e) => ({ ...e, levelId }));
+    const kept = levelId === null
+        ? existing.filter((e) => !tagged.some((n) => n.id === e.id))
+        : existing.filter((e) => e.levelId !== levelId);
+    return [...kept, ...tagged];
+}
+export function buildLevelPersistModifications(input) {
+    const notes = [];
+    const world = input.existingWorldJson;
+    const vwldUrl = String(input.levelAsset.url ?? '');
+    const levelAssetId = String(input.levelAsset.id);
+    // ── Resolve the target level entry (levels mode / conversion / legacy) ──
+    let levels = getLevels(world);
+    let baseInstances = world.environmentObjects ?? [];
+    let legacyFallback = false;
+    let converted = false;
+    if (!isLevelsMode(world)) {
+        try {
+            const level1 = synthesizeLevel1(world);
+            if (level1) {
+                levels = [level1];
+                converted = true;
+                baseInstances = tagUntaggedInstances(baseInstances, level1.id);
+                notes.push(`Converted existing world to level "${level1.name}" (${level1.id})`);
+            }
+            else {
+                levels = []; // procedural game — the forged level becomes levels[0]
+            }
+        }
+        catch (err) {
+            // Unconvertible legacy world: keep today's semantics (global voxelUrl
+            // replace, stale instances untouched) rather than failing the forge.
+            legacyFallback = true;
+            notes.push(`Levels registry not created: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const existingEntry = levels.find((l) => l.vwldAssetId === levelAssetId) ?? null;
+    const levelId = legacyFallback ? null : (existingEntry?.id ?? mintLevelId());
+    // ── Instances: replace ONLY this level's set (legacy: full replace-by-add) ──
+    const taggedNew = levelId === null
+        ? input.instances
+        : input.instances.map((o) => ({ ...o, levelId }));
+    const keptInstances = levelId === null
+        ? baseInstances.filter((o) => !taggedNew.some((n) => n.id === o.id))
+        : baseInstances.filter((o) => o.levelId !== levelId);
+    const finalInstances = [...keptInstances, ...taggedNew];
+    // ── Asset upserts: level asset + baked archetypes (never reused stubs) ──
+    const modifications = [
+        {
+            type: 'upsertRoot',
+            path: ['assets'],
+            predicate: (a) => a.id === levelAssetId,
+            value: input.levelAsset,
+        },
+        ...input.archetypeAssets
+            .filter((a) => a.reused !== true)
+            .map((asset) => ({
+            type: 'upsertRoot',
+            path: ['assets'],
+            predicate: (a) => a.id === asset.id,
+            value: asset,
+        })),
+        { type: 'setRoot', path: ['environmentObjects'], value: finalInstances },
+    ];
+    // ── Level-scoped door / key definitions (dungeon forges) ──
+    // Same replace-by-level rule as the instances above, and deliberately NOT
+    // part of the start-level mirror set below. The resulting arrays are computed
+    // even when this forge writes none, because the PURGE below reads them.
+    const finalDefinitions = { doors: [], keyItems: [] };
+    for (const key of ['doors', 'keyItems']) {
+        const existing = (world.worldProfileData?.[key] ?? []);
+        const incoming = input[key];
+        // `undefined` = this forge has none, so the array stays exactly as it is.
+        const next = incoming === undefined ? existing : replaceLevelScoped(existing, incoming, levelId);
+        finalDefinitions[key] = next;
+        if (incoming === undefined)
+            continue;
+        if (existing.length === 0 && next.length === 0)
+            continue; // never introduce an empty array
+        modifications.push({ type: 'set', path: [key], value: next });
+        if (incoming.length > 0)
+            notes.push(`Wrote ${incoming.length} ${key} entr${incoming.length === 1 ? 'y' : 'ies'} scoped to this level`);
+    }
+    // ── Registry + mirrors ──
+    let isStartLevel;
+    if (legacyFallback) {
+        isStartLevel = true; // legacy world IS the (only) world — mirror everything
+        // Atmosphere has no level entry to ride on here, and no other level to
+        // pollute — so it goes onto the globals. Skipping it is how a dungeon
+        // bakes correctly and then renders in full daylight with invisible
+        // fixture lights. (Non-atmosphere forges pass nothing and touch nothing.)
+        for (const key of ['skyboxUrl', 'fogConfig', 'lightingConfig']) {
+            const value = input.levelOverrides?.[key];
+            if (value !== undefined)
+                modifications.push({ type: 'set', path: [key], value });
+        }
+    }
+    else {
+        // Level atmosphere: the forge OWNS this entry's overrides, so a re-forge
+        // replaces them wholesale rather than accumulating stale ones.
+        const overrides = {
+            ...(input.waterLevelY !== null ? { waterLevelY: input.waterLevelY } : {}),
+            ...(input.levelOverrides?.skyboxUrl !== undefined ? { skyboxUrl: input.levelOverrides.skyboxUrl } : {}),
+            ...(input.levelOverrides?.fogConfig !== undefined ? { fogConfig: input.levelOverrides.fogConfig } : {}),
+            ...(input.levelOverrides?.lightingConfig !== undefined ? { lightingConfig: input.levelOverrides.lightingConfig } : {}),
+        };
+        const entry = {
+            id: levelId,
+            name: input.levelName,
+            vwldAssetId: levelAssetId,
+            spawnPoints: input.spawnPoints,
+            ...(Object.keys(overrides).length > 0 ? { overrides } : {}),
+        };
+        const newLevels = existingEntry
+            ? levels.map((l) => (l.id === levelId ? entry : l))
+            : [...levels, entry];
+        modifications.push({ type: 'set', path: ['levels'], value: newLevels });
+        if (existingEntry) {
+            // Re-forge of an existing level keeps the current start — unless the
+            // user explicitly asked for this level to become the boot level.
+            const startId = world.worldProfileData?.startLevelId ?? getStartLevel(world)?.id ?? newLevels[0].id;
+            isStartLevel = startId === levelId || newLevels.length === 1 || input.makeStartLevel === true;
+            if (isStartLevel && startId !== levelId) {
+                modifications.push({ type: 'set', path: ['startLevelId'], value: levelId });
+            }
+        }
+        else {
+            // Start-level policy for a NEW level: explicit user intent wins; by
+            // default steal start only when there is nothing else to boot into —
+            // the game's first level, or the conversion moment (pre-levels forges
+            // replaced the world outright, so landing in the fresh forge preserves
+            // that expectation). Adding a level to a game that already has a
+            // levels registry NEVER moves the start on its own — the creator owns
+            // that via manage-levels setStart / the Levels panel.
+            const onlyLevel = levels.length === 0;
+            isStartLevel = onlyLevel || (input.makeStartLevel ?? converted);
+            if (isStartLevel) {
+                modifications.push({ type: 'set', path: ['startLevelId'], value: levelId });
+            }
+            else if (converted) {
+                // Conversion without stealing start: pin the boot level to the
+                // synthesized level 1 explicitly (matches manage-levels' conversion).
+                modifications.push({ type: 'set', path: ['startLevelId'], value: levels[0].id });
+            }
+        }
+    }
+    if (isStartLevel) {
+        // Exactly the pre-levels write set — frozen boot code reads only these.
+        modifications.push({ type: 'set', path: ['voxelUrl'], value: vwldUrl }, { type: 'set', path: ['playerSpawnPosition'], value: input.spawn }, { type: 'set', path: ['spawnPoints'], value: input.spawnPoints });
+        if (input.playerSpawnRotationY !== null) {
+            modifications.push({ type: 'set', path: ['playerSpawnRotationY'], value: input.playerSpawnRotationY });
+        }
+        if (input.waterLevelY !== null) {
+            modifications.push({ type: 'set', path: ['waterLevelY'], value: input.waterLevelY });
+        }
+    }
+    // ── Purge orphaned forge placeholders (the re-forge pile-up fix) ──
+    // Door leaves and key pickups are ZERO-INSTANCE assets: nothing in
+    // environmentObjects references them, only the door/key definitions do. Purging
+    // on instance count alone stripped them on the NEXT forge and left
+    // `doors[].assetId` / `keyItems[].assetId` dangling — the door silently
+    // degrading to the engine's box fallback. Every SURVIVING definition counts,
+    // across all levels, not just the one being forged.
+    const referencedAssetIds = new Set([
+        ...finalInstances.map((o) => String(o.assetId)),
+        ...finalDefinitions.doors.map((d) => String(d.assetId ?? '')),
+        ...finalDefinitions.keyItems.map((k) => String(k.assetId ?? '')),
+    ]);
+    const upsertedIds = new Set([
+        levelAssetId,
+        ...input.archetypeAssets.map((a) => String(a.id)),
+    ]);
+    const purgedAssetIds = (world.assets ?? [])
+        .filter((a) => a.placeholder === true &&
+        !upsertedIds.has(String(a.id)) &&
+        !referencedAssetIds.has(String(a.id)) &&
+        !input.activeHqAssetIds.has(String(a.id)))
+        .map((a) => String(a.id));
+    if (purgedAssetIds.length > 0) {
+        const purgedSet = new Set(purgedAssetIds);
+        modifications.push({
+            type: 'removeRoot',
+            path: ['assets'],
+            predicate: (a) => purgedSet.has(String(a.id)),
+        });
+        notes.push(`Purged ${purgedAssetIds.length} orphaned placeholder asset(s)`);
+    }
+    return { modifications, levelId, isStartLevel, purgedAssetIds, notes };
+}
+//# sourceMappingURL=persist-level.js.map

package/dist/pipeline/persist-level.js.map

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

package/dist/pipeline/place-and-persist-level.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Step 5 — place the archetype instances in the browser and PLAN the world.json
+ * write (level asset record, archetype assets, instances, level URL, spawn).
+ *
+ * Moved from game-play-agent's `pipeline.ts` verbatim, with three host couplings
+ * turned into seams:
+ *  - the `BATCH_PLACE_VOXEL_OBJECTS` calls go through `deps.transport`,
+ *  - the two world.json READS go through `deps.worldJson` (see
+ *    world-json-source.ts for why there are two of them),
+ *  - the world.json WRITE moves OUT: this step returns the modifications and
+ *    the heightfield sidecar payload, and the HOST applies both. Same boundary
+ *    the earlier phases established, and what lets a CLI project apply the
+ *    result to its own single world.json.
+ *
+ * The `persisted` artifact is written by the HOST too, after the write lands —
+ * it is the job-complete marker a resumed run returns directly, so recording it
+ * before the world.json write would let a failed write resume into "done".
+ */
+import type { ForgedWorkStore } from './forged-work-store.js';
+import type { ForgeDeps } from './deps.js';
+import type { ForgeLevelSummary } from './job-types.js';
+import type { WorldJsonModification } from './world-json-types.js';
+import type { ForgedDungeonView } from '../artifact-types.js';
+import type { ForgedHeightGrid } from '../terrain-height-grid.js';
+/** What step 5 produces for the host to apply. */
+export interface PlaceAndPersistResult {
+    /** The rich tool summary — also the `persisted` artifact the host records. */
+    summary: ForgeLevelSummary;
+    /**
+     * world.json modifications IN ORDER (starter-scatter removals first, then the
+     * level's own upserts/sets). The host applies them in exactly this order.
+     */
+    modifications: WorldJsonModification[];
+    /**
+     * World-space terrain heightfield to persist as a sidecar NEXT TO world.json
+     * (`FORGED_HEIGHTFIELD_FILE`) so post-forge placements can resolve
+     * `placeOnTerrain` Y on the forged surface — a placement raycast can't, since
+     * the new terrain only loads after the session reload. Best-effort for the
+     * host: a missing sidecar just falls back to runtime snapping. Absent on
+     * resumed runs whose `forge` artifact predates the field.
+     */
+    terrainHeightGrid?: ForgedHeightGrid;
+}
+/**
+ * Reconcile placed instances against the assets actually being written, so a dangling `assetId`
+ * can never make the strict validator discard the WHOLE level at session cleanup (which surfaces
+ * as a reported "success" over an empty world). An instance whose `assetId` is not among the
+ * written assets is recovered by archetype name (carried on the instance's `type`) when a
+ * same-named asset exists; otherwise it is dropped. Pure + exported for unit testing.
+ */
+export declare function reconcileInstancesToAssets(placedInstances: Array<Record<string, unknown>>, writableAssetIds: Set<string>, assetIdByName: Map<string, string>): {
+    instances: Array<Record<string, unknown>>;
+    remapped: number;
+    dropped: number;
+};
+/**
+ * The per-level atmosphere a dungeon needs to read as one: without it the
+ * engine keeps every scene at full daylight and the torch lights are invisible.
+ * Fog colour is DERIVED from the plan's own palette (the primary wall material,
+ * darkened) rather than a fixed grey, so an ice crypt and a lava mine recede
+ * into their own stone; a plan whose every material glows falls back to its
+ * first material, which still tracks the theme. Exported for testing.
+ */
+export declare function buildDungeonAtmosphere(plan: ForgedDungeonView): {
+    fogConfig: {
+        enabled: boolean;
+        color: string;
+        near: number;
+        far: number;
+    };
+    lightingConfig: {
+        sunIntensity: number;
+        environmentIntensity: number;
+        skyboxIntensity: number;
+    };
+};
+/**
+ * Place the archetype instances and build the world.json modifications that
+ * install the level (level asset record, archetype assets, instances, level
+ * URL, spawn). The host applies what this returns.
+ */
+export declare function placeAndPersistLevel(store: ForgedWorkStore, deps: ForgeDeps): Promise<PlaceAndPersistResult>;
+//# sourceMappingURL=place-and-persist-level.d.ts.map

package/dist/pipeline/place-and-persist-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"place-and-persist-level.d.ts","sourceRoot":"","sources":["../../src/pipeline/place-and-persist-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAgC,iBAAiB,EAAqB,MAAM,gBAAgB,CAAC;AACzG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AASnE,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAOlE,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;OAGG;IACH,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;CACtC;AA8DD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC/C,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,EAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC;IAAE,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAgBlF;AA+BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,iBAAiB,GAAG;IAC/D,SAAS,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,cAAc,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,oBAAoB,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;CACjG,CAgBA;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,qBAAqB,CAAC,CAuNhC"}