@oasys/oecs 0.3.1 → 0.4.0

package/dist/core/ecs/command_log.d.ts

@@ -0,0 +1,113 @@
+import { ECS } from './ecs';
+import { HostCommand, HostCommandQueue, HostCommandSink } from './host_commands';
+/** One recorded update tick: the commands the apply system drained at this
+ * tick's update-phase head, plus the `dt` passed to `world.update(dt)`. Replay
+ * MUST re-issue `update(dt)` for every recorded tick — even an empty one — since
+ * `dt` itself drives the sim (movement, timers), not just the commands. */
+export interface RecordedTick {
+    /** The ECS tick (`ctx.ecsTick`) this bucket belongs to. */
+    readonly tick: number;
+    /** The `dt` `world.update(dt)` was called with for this tick. */
+    readonly dt: number;
+    /** Commands applied this tick, in apply order (typed queue first, then ring),
+     * `onSpawned` stripped. */
+    readonly commands: readonly HostCommand[];
+}
+/**
+ * A recorded session: the `seed` it ran under, the seed-time commands drained at
+ * startup, and the per-tick command stream. Plain, serializable data — the
+ * record-side mirror of the typed `HostCommand` vocabulary. Replay it with
+ * {@link replayCommandLog}; persist it with {@link serializeCommandLog}.
+ */
+export interface CommandLog {
+    /** Session seed — the implementer's deterministic input (e.g. an RNG seed).
+     * Opaque to the engine (the core tick takes only `dt`); carried so a replay
+     * rebuilds the world the same way the original was built. */
+    readonly seed: number;
+    /** Commands drained at the PRE_STARTUP head (seed-time edits), applied before
+     * the first update tick. Enqueued BEFORE `world.startup()` on replay. */
+    readonly startup: readonly HostCommand[];
+    /** One entry per update tick, in order. */
+    readonly ticks: readonly RecordedTick[];
+}
+/**
+ * The record side of record/replay: a {@link HostCommandSink} the apply system
+ * feeds. Construct one with the session `seed`, hand it to
+ * `installHostCommandSeam(world, { recorder })`, and it accumulates the
+ * command stream as the ECS ticks. Read it back with {@link log} (a live view,
+ * ready to {@link serializeCommandLog serialize}).
+ *
+ * Bucketing: STARTUP-phase drains (which never call {@link openTick}) append to
+ * the {@link startup} bucket; each update-phase drain {@link openTick}s its tick
+ * — multiple update-phase drains in one tick reuse the same bucket (keyed by the
+ * ECS tick), so a frame's commands stay together. The apply system runs every
+ * tick, so every tick's `dt` is recorded even when no commands were applied.
+ *
+ * One recorder per session — don't share across worlds.
+ */
+export declare class HostCommandRecorder implements HostCommandSink {
+    /** Session seed, echoed into the produced {@link CommandLog}. */
+    readonly seed: number;
+    private readonly _startup;
+    private readonly _ticks;
+    /** Where {@link record} appends. Defaults to the startup bucket (seed-time
+     * drains happen before any `openTick`); each `openTick` repoints it. */
+    private sink;
+    constructor(seed?: number);
+    openTick(tick: number, dt: number): void;
+    readonly record: (cmd: HostCommand) => void;
+    /** A live {@link CommandLog} view over the accumulated stream — not a copy.
+     * Serialize it (which deep-copies through JSON) before mutating the world
+     * further if you need a stable snapshot. */
+    log(): CommandLog;
+}
+/** Serialize a {@link CommandLog} to a JSON string. `EntityID` is a plain number
+ * and round-trips as-is; a `ComponentDef` is a callable, so the replacer writes
+ * it as `{ [DEF_TAG]: id }`. (The recorder already stripped `onSpawned`, the
+ * only other non-serializable member.)
+ *
+ * Throws {@link ECS_ERROR.COMMAND_LOG_TAG_COLLISION} if any non-def object in the
+ * log (i.e. a command's `values` map) owns a field named {@link DEF_TAG}: the
+ * reviver tags defs in-band, so such a value would be silently revived as a def,
+ * dropping the real field data. Field names are arbitrary, so this is reachable;
+ * failing here keeps the round-trip lossless instead of corrupting on parse. */
+export declare function serializeCommandLog(log: CommandLog): string;
+/** Parse a {@link CommandLog} from {@link serializeCommandLog} output. */
+export declare function deserializeCommandLog(json: string): CommandLog;
+/** Outcome of {@link replayCommandLog}. */
+export interface ReplayResult {
+    /** Seed-time commands re-applied before the first tick. */
+    readonly startupCommands: number;
+    /** Update ticks replayed. */
+    readonly ticks: number;
+    /** Per-tick `stateHash` captured after each `update`, in tick order — empty
+     * unless the world is deterministic (or `hash` was forced). Compare against
+     * the original run's per-tick hashes to prove the replay matched (ADR-0020). */
+    readonly stateHashes: readonly number[];
+}
+/** Options for {@link replayCommandLog}. */
+export interface ReplayOptions {
+    /** Capture `world.stateHash()` after each tick. Defaults to the world's
+     * `deterministic` flag — a deterministic world is hashed, a non-deterministic
+     * one is not (its `stateHash` would throw, ADR-0020). Force `true` only on a
+     * deterministic world. */
+    readonly hash?: boolean;
+}
+/**
+ * Replay a recorded {@link CommandLog} against `world`, reproducing the original
+ * session tick-for-tick. `world` must be FRESH and NOT yet started, built
+ * identically to the recorded run (same components registered in the same order,
+ * same systems, same `seed` from `log.seed`) and seam-installed — pass the
+ * `HostCommandQueue` `installHostCommandSeam` returned as `queue`. The driver
+ * owns startup: it enqueues the seed-time commands, calls `world.startup()`
+ * (which drains them at PRE_STARTUP), then for each recorded tick enqueues that
+ * tick's commands and calls `world.update(dt)` with the recorded `dt`.
+ *
+ * Determinism (ADR-0020): with `{ deterministic: true }` the per-tick
+ * `stateHashes` this returns must equal the original run's — that equality is
+ * replay fidelity. Identity caveat (§85): a despawned-then-respawned entity gets
+ * a fresh id, but because spawn order is reproduced, every recorded id still
+ * resolves to the same entity on replay.
+ */
+export declare function replayCommandLog(world: ECS, queue: HostCommandQueue, log: CommandLog, opts?: ReplayOptions): ReplayResult;
+//# sourceMappingURL=command_log.d.ts.map

package/dist/core/ecs/command_log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command_log.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/command_log.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtF;;;2EAG2E;AAC3E,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;+BAC2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IAC1B;;iEAE6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;6EACyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACxC;AAiBD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAC1D,iEAAiE;IACjE,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C;4EACwE;IACxE,OAAO,CAAC,IAAI,CAAgC;gBAEhC,IAAI,SAAI;IAIpB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAaxC,QAAQ,CAAC,MAAM,QAAS,WAAW,KAAG,IAAI,CAExC;IAEF;;gDAE4C;IAC5C,GAAG,IAAI,UAAU;CAGjB;AAYD;;;;;;;;;gFASgF;AAChF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAqB3D;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAW9D;AAED,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;oFAEgF;IAChF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC7B;;;8BAG0B;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,GAAG,EACV,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE,aAAa,GAClB,YAAY,CAcd"}

package/dist/core/ecs/component.d.ts

@@ -0,0 +1,106 @@
+import { Brand, TypedArrayTag } from '../../type_primitives';
+export type ComponentID = Brand<number, "component_id">;
+export declare const asComponentId: (value: number) => ComponentID;
+/** Core schema type: maps field names to typed array tags. */
+export type ComponentSchema = Readonly<Record<string, TypedArrayTag>>;
+/** Compile-time tag → TypedArray mapping. */
+export type TagToTypedArray = {
+    f32: Float32Array;
+    f64: Float64Array;
+    i8: Int8Array;
+    i16: Int16Array;
+    i32: Int32Array;
+    u8: Uint8Array;
+    u16: Uint16Array;
+    u32: Uint32Array;
+};
+/** Maps schema fields to their value object: { x: number, y: number }. */
+export type FieldValues<S extends ComponentSchema> = {
+    readonly [K in keyof S]: number;
+};
+/** Maps schema fields to their specific typed array columns. */
+export type ColumnsForSchema<S extends ComponentSchema> = {
+    readonly [K in keyof S]: TagToTypedArray[S[K]];
+};
+/**
+ * Mutable sibling of `ColumnsForSchema` — the field-keyed column group handed
+ * back by `eachChunk`'s `cols.mut(def)` (no `readonly`, since the whole point
+ * is in-place writes). The change-tick is stamped once when the group is
+ * resolved, so the per-row loop is plain typed-array indexing (§eachChunk).
+ */
+export type MutableColumnsForSchema<S extends ComponentSchema> = {
+    [K in keyof S]: TagToTypedArray[S[K]];
+};
+/**
+ * A component handle. **Callable**: `Pos({ x, y })` produces a `Bundle` (omitted
+ * fields zero-fill at attach), so one varargs shape — `spawn(Pos({x,y}),
+ * Vel({vx:1}), IsEnemy)` — replaces the older incompatible attach shapes. A bare
+ * `Pos` (uncalled) still stands in for a tag / all-zero values wherever a
+ * `BundleOrDef` is accepted.
+ *
+ * The numeric component id lives on `.id` (registration order). Consumers treat
+ * the def as an opaque handle; internal code reads `def.id` where it needs the
+ * raw id. The call signature's `S` makes `ComponentDef<{x:"f64"}>` distinct from
+ * `ComponentDef<{vx:"f64"}>`, so no phantom field is needed for nominal typing.
+ *
+ * Build one with `makeComponentDef`; never construct by hand.
+ */
+export interface ComponentDef<S extends ComponentSchema = ComponentSchema> {
+    (values?: Partial<FieldValues<S>>): Bundle<S>;
+    readonly id: ComponentID;
+}
+/**
+ * Schema-erased component handle — just the `.id`. Internal, schema-agnostic
+ * code (access checks, dirty-set notes, field-id lookup) takes this instead of
+ * `ComponentDef`: the callable signature makes `ComponentDef<S>` *invariant* in
+ * `S` (a generic `ComponentDef<S>` is not assignable to `ComponentDef`), but
+ * every `ComponentDef<S>` is assignable to `ComponentHandle` because it carries
+ * `.id`. Use it wherever only the id is read.
+ */
+export type ComponentHandle = {
+    readonly id: ComponentID;
+};
+/**
+ * Mint a callable `ComponentDef` for a freshly-registered component id. The
+ * returned function produces a `Bundle` when called (`Pos({x,y})`) and carries
+ * its numeric id on a non-enumerable `.id` (invisible to spreads / `JSON`).
+ * The single cast bridges the function value to the branded handle type — the
+ * `.id` is installed at runtime by `defineProperty` (§10c branded-ID boundary).
+ */
+export declare function makeComponentDef<S extends ComponentSchema>(id: ComponentID): ComponentDef<S>;
+export interface Bundle<S extends ComponentSchema = ComponentSchema> {
+    readonly def: ComponentDef<S>;
+    readonly values: Partial<FieldValues<S>>;
+}
+/** Either a populated bundle or a bare def (tag / all-fields-zero). */
+export type BundleOrDef<S extends ComponentSchema = ComponentSchema> = Bundle<S> | ComponentDef<S>;
+/** Pair a component def with field values to attach. Omitted fields zero-fill. */
+export declare function bundle<S extends ComponentSchema>(def: ComponentDef<S>, values?: Partial<FieldValues<S>>): Bundle<S>;
+/** Extract the def from a `BundleOrDef`. A bare def is the callable; a bundle a plain object. */
+export declare function bundleDef(item: BundleOrDef): ComponentDef;
+/** Extract the values from a `BundleOrDef` (a bare def contributes no values). */
+export declare function bundleValues(item: BundleOrDef): Readonly<Record<string, number>>;
+/**
+ * Compile-time readonly view of a typed array column. Blocks index writes at
+ * the type layer.
+ *
+ * **Advisory, not a runtime barrier:** the value behind this type is the live
+ * mutable backing `TypedArray` (`Archetype.getColumnRead` returns
+ * `.buf as unknown as ReadonlyColumn`), so a §10c-policed cast can still write
+ * through. For mutation use the mutable `Archetype.getColumn` (tick-bumping).
+ * Enforced by the escape-hatch lint, not the runtime.
+ */
+export interface ReadonlyColumn {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+/**
+ * Compile-time readonly view of a Uint32Array. Blocks index writes at the type
+ * layer. **Advisory, not a runtime barrier** — same caveat as `ReadonlyColumn`:
+ * the underlying value is the live mutable buffer.
+ */
+export interface ReadonlyUint32Array {
+    readonly [index: number]: number;
+    readonly length: number;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/core/ecs/component.d.ts.map

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

package/dist/core/ecs/compute_backend.d.ts

@@ -0,0 +1,37 @@
+import { Brand } from '../../type_primitives';
+import { StoreLayoutListener } from './store_layout_listener';
+/**
+ * An opaque token identifying one of a backend's entry points (one
+ * "backend-system"). The engine **never interprets** it — the backend mints it
+ * and is the only thing that maps it back to a concrete computation. Carried on
+ * `SystemConfig.backendHandle` and handed verbatim to `ComputeBackend.run`.
+ *
+ * Branded so a stray `number` can't be mistaken for a handle; consumers mint
+ * one by casting (the backend owns the id space, like flecs's `run` function
+ * pointer or a small index into the backend's entry table).
+ */
+export type BackendSystemHandle = Brand<number, "backend_system_handle">;
+/**
+ * The engine-side contract a compute backend implements. Composes
+ * `StoreLayoutListener` (the already-clean SAB handshake — `setLayout` is called
+ * once on attach to seed the layout and again after every SAB grow/extend) with
+ * a single generic `run` entry point.
+ *
+ * A backend is attached opt-in via `ECS.attachBackend(backend)`, which also
+ * subscribes it as a layout listener, so a backend re-walks the layout on attach
+ * and republish for free.
+ */
+export interface ComputeBackend extends StoreLayoutListener {
+    /**
+     * Execute the backend-system identified by `handle`. Called by the
+     * `Schedule` in place of the system's `fn` closure, inside the same
+     * `accessCheck` span — so the system's declared `writes` authorise whatever
+     * shared-memory columns the backend mutates, exactly as a TS body that calls
+     * out to the backend would be authorised today.
+     *
+     * `handle` is opaque to the engine; it is one the backend minted and the
+     * engine merely round-trips from `SystemConfig.backendHandle`.
+     */
+    run(handle: BackendSystemHandle): void;
+}
+//# sourceMappingURL=compute_backend.d.ts.map

package/dist/core/ecs/compute_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute_backend.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/compute_backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAe,SAAQ,mBAAmB;IAC1D;;;;;;;;;OASG;IACH,GAAG,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACvC"}

package/dist/core/ecs/dispatch_trace.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Dev-mode dispatch tracer.
+ *
+ * Singleton buffer that captures `(callsite, channel, op, key)` per ECS /
+ * action dispatch when `VISUAL_INTEL_TRACE=1` is set in the environment.
+ * Compile-time gated by `__DEV__`, so production builds dead-code-eliminate
+ * every record() call. Output is a deterministic JSON snapshot the
+ * `visual-intel` service can ingest as a third channel of evidence
+ * alongside the existing static + symbol-propagation scans.
+ *
+ * Identity model. The engine has no access to source-level binding names
+ * (`ContactEvent`, `ConfigRes`) at runtime — `eventKey("Contact")` returns
+ * `Symbol("Contact")` and the variable name is erased. The tracer records the
+ * runtime-available identifier:
+ *
+ *   - ECS events / resources → the Symbol description (`label`).
+ *   - Actions → the numeric `def.id`.
+ *
+ * Resolution back to bindings happens in `visual-intel`, which already
+ * extracts `{ binding, label }` declarations for events / resources and
+ * `{ binding, id_expr }` for actions; the matching there is unambiguous.
+ *
+ * Callsite resolution. `new Error().stack` inside `record()`, walk the
+ * frames, drop everything inside `packages/engine/src/core/ecs/` (this
+ * file + the dispatcher seam), return the first repo-relative path. Stack-
+ * line strings are cached so repeat dispatches from the same site are
+ * O(1) after the first hit. The walk itself lives in the pure
+ * `resolveCallsiteFromStack()` helper so it can be driven by a synthetic
+ * stack in tests.
+ *
+ * Activation. `record()` is *unconditional* — it records on every call. The
+ * `isActive()` env-var gate is applied by the *callers* (`ecs.ts` /
+ * `query.ts`, all `if (__DEV__ && dispatchTrace.isActive())`), not inside
+ * `record()`. This keeps the gate in one place — the dispatch hot path —
+ * where `__DEV__ === false` dead-code-eliminates the whole branch in prod.
+ */
+export type DispatchChannel = "ecs-events" | "actions" | "resources";
+export type EcsEventOp = "emit" | "read";
+export type ActionOp = "send_action" | "handle_action";
+export type ResourceOp = "read" | "write" | "register" | "remove";
+export interface DispatchTraceEntry {
+    /** Symbol description (events / resources) or numeric `def.id` (actions). */
+    readonly key: string | number;
+    /** Repo-relative POSIX path of the calling file. */
+    readonly file: string;
+    readonly count: number;
+}
+export interface DispatchTraceSnapshot {
+    readonly schemaVersion: 1;
+    readonly capturedAt: string;
+    readonly channels: {
+        readonly "ecs-events": Record<EcsEventOp, DispatchTraceEntry[]>;
+        readonly actions: Record<ActionOp, DispatchTraceEntry[]>;
+        readonly resources: Record<ResourceOp, DispatchTraceEntry[]>;
+    };
+}
+declare class DispatchTrace {
+    private activeCache;
+    private repoRootCache;
+    private buf;
+    private callsiteCache;
+    isActive(): boolean;
+    private repoRoot;
+    private resolveCallsite;
+    private record;
+    recordEmit(label: string): void;
+    recordRead(label: string): void;
+    recordResourceRead(label: string): void;
+    recordResourceWrite(label: string): void;
+    recordResourceRegister(label: string): void;
+    recordResourceRemove(label: string): void;
+    recordSendAction(actId: number): void;
+    recordHandleAction(actId: number): void;
+    snapshot(): DispatchTraceSnapshot;
+    reset(): void;
+}
+declare function parseFrameFile(line: string): string | null;
+/**
+ * Walk a stack string, drop frames inside the engine ECS package, and return
+ * the first non-engine frame as a repo-relative POSIX path (or `null` if the
+ * stack has no attributable frame). Pure so tests can drive it with a
+ * synthetic stack; the optional `cache` memoises per-line results for the hot
+ * dispatch path. Mutates `cache` when supplied.
+ */
+declare function resolveCallsiteFromStack(stack: string | null, repoRoot: string, cache?: Map<string, string | null>): string | null;
+export declare const dispatchTrace: DispatchTrace;
+export declare const _dispatchTraceInternals: {
+    parseFrameFile: typeof parseFrameFile;
+    resolveCallsiteFromStack: typeof resolveCallsiteFromStack;
+    create: () => DispatchTrace;
+};
+export {};
+//# sourceMappingURL=dispatch_trace.d.ts.map

package/dist/core/ecs/dispatch_trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch_trace.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/dispatch_trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAOH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,SAAS,GAAG,WAAW,CAAC;AACrE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,eAAe,CAAC;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElE,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE;QAClB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;QAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;KAC7D,CAAC;CACF;AAID,cAAM,aAAa;IAClB,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,GAAG,CAA6B;IACxC,OAAO,CAAC,aAAa,CAAoC;IAEzD,QAAQ,IAAI,OAAO;IAWnB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,MAAM;IAOd,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG/B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG/B,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGvC,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGxC,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAG3C,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGzC,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAGrC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIvC,QAAQ,IAAI,qBAAqB;IAmCjC,KAAK,IAAI,IAAI;CAMb;AAMD,iBAAS,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOnD;AAED;;;;;;GAMG;AACH,iBAAS,wBAAwB,CAChC,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAChC,MAAM,GAAG,IAAI,CA0Bf;AAeD,eAAO,MAAM,aAAa,EAAE,aAAmC,CAAC;AAIhE,eAAO,MAAM,uBAAuB;;;;CAInC,CAAC"}