@motion-script/core 0.1.0

package/dist/runtime/playback-controller.js

@@ -0,0 +1,244 @@
+import { AssetManager } from "../assets/manager";
+import { StateEvaluator } from "./state-evaluator";
+import { nodePath } from "../project/tree";
+import { Precomp } from "./precompisition";
+/**
+ * Orchestrates playback of a compiled motion-script project.
+ *
+ * On construction it runs the precomp pass (`Precomp.run()`) to build the
+ * global asset timeline and node lifespans, then wires the master clock to
+ * the audio device and render pipeline so every tick:
+ *
+ * 1. Loads assets required at the current frame (`AssetManager.loadAt`).
+ * 2. Evaluates scene state and lays out nodes (`StateEvaluator`).
+ * 3. Renders the frame to the render context.
+ * 4. Prefetches assets for upcoming frames.
+ *
+ * External callers interact via `play`, `pause`, `seek`, `seekWhilePlaying`,
+ * `screenshot`, `getTreeState`, and `getNodeState`.
+ */
+export class PlaybackController {
+    renderContext;
+    measureScope;
+    storageAdapter;
+    masterClock;
+    stateEvaluator;
+    assetManager;
+    audioDevice;
+    fps;
+    viewport;
+    precomp;
+    /** Per-scene frame counts in timeline order, used to build the track list. */
+    get tracks() {
+        return this.precomp.scenes.map(s => s.frameCount);
+    }
+    /** Total frame count across all scenes. */
+    get totalFrames() {
+        return this.precomp.totalFrames;
+    }
+    /** Total playback duration in seconds. */
+    get totalDuration() {
+        return this.precomp.totalDuration;
+    }
+    /** Errors collected during the precomp pass (one entry per failing scene). */
+    get buildErrors() {
+        return this.precomp.buildErrors;
+    }
+    constructor(params) {
+        this.renderContext = params.renderContext;
+        this.measureScope = params.measureScope;
+        this.masterClock = params.masterClock;
+        this.storageAdapter = params.storageAdapter;
+        this.audioDevice = params.audioDevice;
+        this.fps = params.fps;
+        this.viewport = params.viewport;
+        const catalog = params.assets;
+        this.precomp = new Precomp(params.scenes, this.viewport, this.fps, catalog, this.measureScope).run();
+        this.stateEvaluator = new StateEvaluator(params.scenes, this.viewport, this.fps, catalog, this.tracks);
+        this.assetManager = new AssetManager(this.precomp, this.storageAdapter, this.audioDevice);
+        this.masterClock.setDuration(this.totalDuration);
+        this.masterClock.onPlay((t, speed, reverse) => {
+            this.audioDevice.play(t, speed, reverse);
+        });
+        this.masterClock.onPause(() => {
+            this.audioDevice.stop();
+        });
+        this.masterClock.onTick(async (currentTime) => {
+            const frame = this.fps * currentTime;
+            if (frame >= this.totalFrames) {
+                this.masterClock.pause();
+            }
+            await this.assetManager.loadAt(frame);
+            this.audioDevice.syncTo(currentTime);
+            this.renderAt(frame);
+            this.assetManager.prefetch(frame);
+        });
+    }
+    get isPlaying() {
+        return this.masterClock.isPlaying;
+    }
+    /** Current playback position in seconds. */
+    get currentTime() {
+        return this.masterClock.currentTime;
+    }
+    /** Current playback position in frames (float). */
+    get currentFrame() {
+        return this.masterClock.currentTime * this.fps;
+    }
+    /** Register a callback that fires on every clock tick with the current time. */
+    onTime(cb) {
+        this.masterClock.onTime(cb);
+    }
+    /** Register a callback that fires when playback starts. */
+    onPlay(cb) {
+        this.masterClock.onPlay(() => cb());
+    }
+    /** Register a callback that fires when playback pauses. */
+    onPause(cb) {
+        this.masterClock.onPause(cb);
+    }
+    /**
+     * Evaluate scene state, lay out nodes, and render `frame` to the render
+     * context. Called on every clock tick and also directly by `seek` /
+     * `screenshot` to ensure the surface is up-to-date.
+     */
+    renderAt(frame) {
+        this.stateEvaluator.stateAt(frame);
+        this.stateEvaluator.layout(this.measureScope);
+        this.renderContext.render(() => {
+            this.stateEvaluator.render(this.renderContext);
+        });
+    }
+    /**
+     * Jump to `frame`, pausing playback first. Waits for required assets to
+     * load before rendering, then prefetches upcoming frames.
+     */
+    async seek(frame) {
+        const clamped = Math.max(0, Math.min(frame, this.totalFrames));
+        this.masterClock.pause();
+        this.masterClock.seek(clamped / this.fps);
+        await this.assetManager.loadAt(clamped);
+        this.renderAt(clamped);
+        this.assetManager.prefetch(clamped);
+    }
+    /** Reposition the clock to `frame` without interrupting playback. */
+    seekWhilePlaying(frame) {
+        const clamped = Math.max(0, Math.min(frame, this.totalFrames));
+        this.masterClock.seek(clamped / this.fps);
+    }
+    /**
+     * Capture the current frame as a base-64 PNG data URL. Forces a fresh
+     * render before snapshotting because the WebGL drawing buffer may have
+     * been cleared since the last tick (we don't set `preserveDrawingBuffer`).
+     * Uses `stateEvaluator.currentFrame` (integer) rather than the clock's
+     * float so `stateAt` always hits its early-return and never resets scene state.
+     */
+    screenshot() {
+        this.renderAt(this.stateEvaluator.currentFrame);
+        return this.renderContext.screenshot();
+    }
+    /**
+     * Return the full node tree for the current scene, with lifespan frame
+     * ranges and waveform data attached. Used by the timeline UI.
+     * Returns `null` when no scene is active.
+     */
+    getTreeState() {
+        const scene = this.stateEvaluator.currentScene;
+        if (!scene)
+            return null;
+        const sceneIndex = this.stateEvaluator.currentSceneIndex;
+        const scenePrecomp = sceneIndex >= 0 ? this.precomp.scenes[sceneIndex] : undefined;
+        const audioRequests = scenePrecomp?.audioRequests ?? [];
+        // Bound each node's bar to its lifespan: the precomp records scene-local
+        // frame ranges, which we shift by the scene's global startFrame so bars
+        // land within the scene's slot on the full timeline.
+        const lifespans = scenePrecomp?.lifespans;
+        const sceneStart = scenePrecomp?.startFrame ?? 0;
+        const tree = nodeToTreeState(scene, "", lifespans, sceneStart);
+        // Attach the scene's full audio timeline to its root node so the timeline
+        // can render waveforms covering each clip's start→end span. The precomp
+        // requests are the complete picture (the per-frame node hook only sees
+        // sounds active on the current frame), so they take precedence here.
+        const waveform = waveformFromRequests(audioRequests);
+        if (waveform.length > 0)
+            tree.waveform = waveform;
+        return tree;
+    }
+    getNodeState(nodeId) {
+        const scene = this.stateEvaluator.currentScene;
+        if (!scene)
+            return null;
+        const node = findNode(scene, nodeId);
+        if (!node)
+            return null;
+        return { id: node.id, type: node.name, properties: node.properties };
+    }
+    play(speed = 1, reverse = false) {
+        if (this.currentFrame >= this.totalFrames) {
+            this.seek(0).then(() => this.masterClock.play(speed, reverse)).catch(() => { });
+            return;
+        }
+        this.masterClock.play(speed, reverse);
+    }
+    pause() {
+        this.masterClock.pause();
+    }
+    setMuted(muted) {
+        this.audioDevice.setMuted(muted);
+    }
+    dispose() {
+        this.masterClock.dispose();
+        this.audioDevice.dispose();
+        this.stateEvaluator.dispose();
+    }
+}
+// Every Node is a container (children may be empty); kept for callers that
+// want an explicit "has children" check.
+export function isParentNode(node) {
+    return node.children.length > 0;
+}
+function nodeToTreeState(node, path, lifespans, sceneStart = 0) {
+    const state = {
+        id: node.id,
+        type: node.name,
+        children: node.children.map((c, i) => nodeToTreeState(c, nodePath(path, i), lifespans, sceneStart)),
+    };
+    // Let any node contribute its own audio clips (the base node has none).
+    const waveform = node.waveform();
+    if (waveform && waveform.length > 0)
+        state.waveform = waveform;
+    // Look the lifespan up by structural path (ids are not stable across the
+    // precomp/playback rebuilds) and shift it into absolute timeline frames.
+    const span = lifespans?.get(path);
+    if (span) {
+        state.startFrame = sceneStart + span.startFrame;
+        state.endFrame = sceneStart + span.endFrame;
+    }
+    return state;
+}
+/** Derive timeline waveform entries (one per clip) from a scene's audio requests. */
+function waveformFromRequests(requests) {
+    return requests.map((req) => ({
+        src: req.src,
+        name: fileName(req.src),
+        startTime: req.startAt,
+        endTime: Number.isFinite(req.endAt) ? req.endAt : null,
+    }));
+}
+/** Last path segment of a src, used as the clip's display name. */
+function fileName(src) {
+    const cleaned = src.split(/[?#]/)[0];
+    const segs = cleaned.split(/[/\\]/);
+    return segs[segs.length - 1] || src;
+}
+function findNode(root, id) {
+    if (root.id === id)
+        return root;
+    for (const child of root.children) {
+        const found = findNode(child, id);
+        if (found)
+            return found;
+    }
+    return null;
+}
+//# sourceMappingURL=playback-controller.js.map

package/dist/runtime/playback-controller.js.map

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

package/dist/runtime/playback-controller.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=playback-controller.test.d.ts.map

package/dist/runtime/playback-controller.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playback-controller.test.d.ts","sourceRoot":"","sources":["../../src/runtime/playback-controller.test.ts"],"names":[],"mappings":""}

package/dist/runtime/playback-controller.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from 'vitest';
+import { PlaybackController } from '@/runtime/playback-controller';
+import { FakeScene, FakeNode, FakeClock, FakeAudioDevice, FakeStorageAdapter, FakeRenderContext, FakeMeasureScope, FakeAssetCatalog, asScenes, asCatalog, asStorage, asRenderContext, } from './runtime.fixtures';
+const flush = () => new Promise((r) => setTimeout(r, 0));
+function makeController(yieldCount = 10, fps = 10) {
+    const child = new FakeNode('child', 'Rect');
+    const scene = new FakeScene({ id: 'root', name: 'Scene', yieldCount, children: [child] });
+    const clock = new FakeClock();
+    const audio = new FakeAudioDevice();
+    const storage = new FakeStorageAdapter();
+    const rc = new FakeRenderContext();
+    const controller = new PlaybackController({
+        renderContext: asRenderContext(rc),
+        measureScope: new FakeMeasureScope(),
+        storageAdapter: asStorage(storage),
+        masterClock: clock,
+        audioDevice: audio,
+        assets: asCatalog(new FakeAssetCatalog()),
+        precomposition: undefined,
+        fps,
+        viewport: { width: 100, height: 50 },
+        scenes: asScenes([scene]),
+    });
+    return { controller, scene, clock, audio, storage, rc, child };
+}
+describe('PlaybackController – construction', () => {
+    it('derives tracks, totals, and configures the clock duration', () => {
+        const { controller, clock } = makeController(10, 10);
+        expect(controller.tracks).toEqual([10]);
+        expect(controller.totalFrames).toBe(10);
+        expect(controller.totalDuration).toBeCloseTo(1, 6);
+        expect(clock.duration).toBeCloseTo(1, 6);
+    });
+    it('reports currentFrame as clock time × fps', () => {
+        const { controller, clock } = makeController(10, 10);
+        clock.setTime(0.5);
+        expect(controller.currentFrame).toBe(5);
+    });
+});
+describe('PlaybackController – seek', () => {
+    it('pauses, seeks the clock, and renders the frame', async () => {
+        const { controller, clock, scene, rc } = makeController();
+        await controller.seek(5);
+        expect(clock.isPlaying).toBe(false);
+        expect(clock.seekCalls.at(-1)).toBeCloseTo(0.5, 6); // 5 / 10 fps
+        expect(rc.renderCount).toBeGreaterThanOrEqual(1);
+        expect(scene.renderCount).toBeGreaterThanOrEqual(1);
+    });
+    it('clamps a negative target to frame 0', async () => {
+        const { controller, clock } = makeController();
+        await controller.seek(-3);
+        expect(clock.seekCalls.at(-1)).toBe(0);
+    });
+    it('clamps a target past the end to totalFrames', async () => {
+        const { controller, clock } = makeController(10, 10);
+        await controller.seek(99999);
+        expect(clock.seekCalls.at(-1)).toBeCloseTo(1, 6); // 10 / 10 fps
+    });
+});
+describe('PlaybackController – play / pause wiring', () => {
+    it('starts the clock and forwards play to the audio device', () => {
+        const { controller, clock, audio } = makeController();
+        clock.setTime(0);
+        controller.play(2, true);
+        expect(clock.isPlaying).toBe(true);
+        expect(audio.playCalls.at(-1)).toEqual({ time: 0, speed: 2, reverse: true });
+    });
+    it('stops audio on pause and fires user pause listeners', () => {
+        const { controller, audio } = makeController();
+        const onPause = vi.fn();
+        controller.onPause(onPause);
+        controller.pause();
+        expect(audio.stopCount).toBeGreaterThanOrEqual(1);
+        expect(onPause).toHaveBeenCalled();
+    });
+    it('restarts from the beginning when play() is called at the end', async () => {
+        const { controller, clock } = makeController(10, 10);
+        clock.setTime(1); // currentFrame = 10 = totalFrames
+        controller.play();
+        await flush();
+        expect(clock.seekCalls).toContain(0);
+    });
+    it('forwards time updates to user onTime listeners', () => {
+        const { controller, clock } = makeController();
+        const onTime = vi.fn();
+        controller.onTime(onTime);
+        clock.setTime(0.3);
+        expect(onTime).toHaveBeenCalledWith(0.3);
+    });
+});
+describe('PlaybackController – tick loop', () => {
+    it('syncs audio and renders on each tick within the timeline', async () => {
+        const { controller, clock, audio, rc } = makeController(10, 10);
+        void controller;
+        const before = rc.renderCount;
+        await clock.simulateTick(0.5); // frame 5 (< total)
+        expect(audio.syncToCalls).toContain(0.5);
+        expect(rc.renderCount).toBeGreaterThan(before);
+        expect(clock.isPlaying).toBe(false); // not auto-paused mid-timeline
+    });
+    it('pauses automatically once the tick reaches the final frame', async () => {
+        const { controller, clock, audio } = makeController(10, 10);
+        void controller;
+        await clock.simulateTick(1.0); // frame 10 = totalFrames → pause
+        expect(clock.isPlaying).toBe(false);
+        expect(audio.syncToCalls).toContain(1.0);
+    });
+});
+describe('PlaybackController – screenshot & introspection', () => {
+    it('returns the render context screenshot', () => {
+        const { controller, rc } = makeController();
+        expect(controller.screenshot()).toBe(rc.screenshotValue);
+    });
+    it('builds a nested tree state from the current scene with node lifespans', () => {
+        const { controller } = makeController();
+        // The precomp records each node's scene-local frame span (a 10-frame
+        // scene at global offset 0 → frames 0..9), attached as absolute frames.
+        expect(controller.getTreeState()).toEqual({
+            id: 'root',
+            type: 'Scene',
+            startFrame: 0,
+            endFrame: 9,
+            children: [{ id: 'child', type: 'Rect', startFrame: 0, endFrame: 9, children: [] }],
+        });
+    });
+    it('returns a node state for a known id', () => {
+        const { controller } = makeController();
+        expect(controller.getNodeState('child')).toEqual({
+            id: 'child',
+            type: 'Rect',
+            properties: {},
+        });
+    });
+    it('returns null for an unknown node id', () => {
+        const { controller } = makeController();
+        expect(controller.getNodeState('does-not-exist')).toBeNull();
+    });
+});
+describe('PlaybackController – dispose', () => {
+    it('tears down the clock, audio device, and scenes', () => {
+        const { controller, clock, audio, scene } = makeController();
+        controller.dispose();
+        expect(clock.disposeCount).toBe(1);
+        expect(audio.stopCount).toBeGreaterThanOrEqual(1); // audioDevice.dispose() → stop()
+        expect(scene.disposeCount).toBeGreaterThanOrEqual(1);
+    });
+});
+//# sourceMappingURL=playback-controller.test.js.map

package/dist/runtime/playback-controller.test.js.map

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

package/dist/runtime/precompisition.d.ts

@@ -0,0 +1,107 @@
+import { AudioRequest } from "../attributes/audio/request";
+import { MeasureScope } from "../render/measure-scope";
+import { AssetRecord } from "../assets/record";
+import { Scene } from "../nodes/base/scene-node";
+import { AssetCatalog } from "../assets/catalog";
+import { Size2D } from "../attributes/layout/size";
+/**
+ * A single asset's position on the global frame timeline together with the
+ * load/evict windows the asset manager uses to keep memory bounded.
+ */
+export interface AssetTrack {
+    record: AssetRecord;
+    /**
+     * Frame at which loading should begin. Always <= startFrame.
+     * Derived from decoded memory footprint: larger assets get earlier lead time.
+     */
+    cacheAt: number;
+    /**
+     * Frame at which the asset may be evicted under memory pressure, or null
+     * if it should never be evicted (e.g. fonts). Always >= endFrame when set.
+     */
+    discardAt: number | null;
+}
+export interface BuildError {
+    /** Name of the scene that threw. */
+    sceneName: string;
+    /** Zero-based index of the scene in the scenes array. */
+    sceneIndex: number;
+    message: string;
+    stack?: string;
+}
+/** Scene-local lifespan (inclusive frame range) a node is alive for. */
+export interface NodeLifespan {
+    /** First scene-local frame the node was present in the tree. */
+    startFrame: number;
+    /** Last scene-local frame the node was present in the tree. */
+    endFrame: number;
+}
+export interface ScenePrecomp {
+    /** Frame count for this scene. */
+    frameCount: number;
+    /** Absolute frame offset of this scene in the global timeline. */
+    startFrame: number;
+    /** Audio requests emitted by this scene's nodes, with scene-relative timing. */
+    audioRequests: AudioRequest[];
+    /**
+     * Per-node lifespan within this scene, in scene-local frames. Keyed by the
+     * node's structural path (child-index path from the scene root, e.g.
+     * "0.2.1") rather than its id: ids are per-instance UUIDs that change when a
+     * scene is rebuilt, but the build is deterministic so the structural path is
+     * stable between the precomp pass and playback. A node added or removed
+     * partway through a scene gets a range narrower than the scene's duration.
+     */
+    lifespans: Map<string, NodeLifespan>;
+}
+export interface PrecompResult {
+    fps: number;
+    /** Per-scene durations and audio, in timeline order. */
+    scenes: ScenePrecomp[];
+    /** Total frame count across all scenes. */
+    totalFrames: number;
+    /** Total duration in seconds. */
+    totalDuration: number;
+    /**
+     * Complete asset timeline built from one full generator pass per scene.
+     * Keyed by stable asset key (src for images/videos, "Family@weight" for fonts).
+     */
+    assets: ReadonlyMap<string, AssetTrack>;
+    /** Errors thrown by scene generators during the build pass. */
+    buildErrors: BuildError[];
+}
+/**
+ * Runs a full offline build pass over every scene before playback starts.
+ *
+ * The pass drives each scene's generator frame-by-frame (without rendering)
+ * to collect three things:
+ *
+ * - **Frame counts** — how long each scene lasts, from which the global
+ *   timeline is assembled.
+ * - **Asset timeline** — every image / video / font each scene needs, with
+ *   the global frame range it is visible, so the asset manager knows exactly
+ *   when to load and evict each one.
+ * - **Node lifespans** — which structural path was alive during which frames,
+ *   used by the timeline UI to draw per-node bars.
+ *
+ * Construct and then call `run()` once; the result is a `PrecompResult` that
+ * `PlaybackController` holds onto for the lifetime of the playback session.
+ */
+export declare class Precomp {
+    private readonly scenes;
+    private readonly viewport;
+    private readonly fps;
+    private readonly assets;
+    private readonly measureScope;
+    constructor(scenes: Scene[], viewport: Size2D, fps: number, assets: AssetCatalog, measureScope: MeasureScope);
+    /**
+     * Execute the build pass and return the complete precomp result.
+     *
+     * Each scene is driven through its full generator loop: `build()` yields
+     * once per frame, and each tick calls `layout`, `prepareAssets`, and
+     * `recordLifespans` before advancing the clock. Errors thrown by a scene
+     * generator are caught and recorded in `buildErrors` rather than aborting
+     * the entire pass, so other scenes can still precomp successfully.
+     */
+    run(): PrecompResult;
+}
+//# sourceMappingURL=precompisition.d.ts.map

package/dist/runtime/precompisition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precompisition.d.ts","sourceRoot":"","sources":["../../src/runtime/precompisition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAKlD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACvB,MAAM,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAMD,MAAM,WAAW,UAAU;IACvB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IACzB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IACzB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B;;;;;;;OAOG;IACH,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACxC;AAID,MAAM,WAAW,aAAa;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,+DAA+D;IAC/D,WAAW,EAAE,UAAU,EAAE,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,OAAO;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;gBAGxC,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,YAAY,EACpB,YAAY,EAAE,YAAY;IAS9B;;;;;;;;OAQG;IACH,GAAG,IAAI,aAAa;CAoFvB"}