shaders 3.1.463 → 3.2.465

package/dist/core/std/sim/agentRender.d.ts

@@ -0,0 +1,274 @@
+import { d } from '../../gpu/kit/index';
+import { Vec4StateArray, AgentHome2 } from './agentForces';
+
+type AtomicU32 = d.atomicU32;
+type StorageTex = d.textureStorage2d<'rgba16float', 'write-only'>;
+/** The world-splat core: per-agent vec4 state + the energy/excitement accumulators. */
+export interface WorldSplatLayout {
+    readonly $: {
+        readonly agents: Vec4StateArray;
+        readonly accumE: AtomicU32[];
+        readonly accumS: AtomicU32[];
+        readonly params: {
+            readonly aspect: number;
+            readonly bodyR: number;
+        };
+    };
+}
+/** The ramp-resolve core: the two accumulators, the output texture, the colour endpoints. */
+export interface RampResolveLayout {
+    readonly $: {
+        readonly accumE: AtomicU32[];
+        readonly accumS: AtomicU32[];
+        readonly outTex: StorageTex;
+        readonly params: {
+            readonly colA: d.v4f;
+            readonly colB: d.v4f;
+        };
+    };
+}
+export interface OrientedWorldSplatConfig {
+    shape: string;
+    /** Square accumulator resolution. */
+    res: number;
+    /** Sanity cap on the body half-width, in texels (the window itself is dynamic). */
+    splatRCap: number;
+    /** Where the agent's heading comes from: its velocity (xy = vel) or its angle (z = θ). */
+    heading: 'velocity' | 'angle';
+    /** Excitement source: the per-agent envelope buffer, or local speed / params.speedNorm. */
+    agitation: 'buffer' | 'speed';
+    /** Stretch the round glow into a comet along the heading (velocity consumers). */
+    comet: boolean;
+    /** Derive the position from a home part + stored offset (MagneticFilings). */
+    home?: AgentHome2;
+    name: string;
+}
+/**
+ * Rasterize one oriented agent into the accumulators by evaluating the baked shape's coverage
+ * per texel in heading space (t along the heading, n perpendicular), in WORLD units so the
+ * shape reads undistorted on any aspect. Hard shapes get a single-texel AA edge and over-drive
+ * the fixed-point gain (interiors resolve fully opaque); the glow is a Gaussian falloff, comet-
+ * stretched for the velocity consumers. The window is sized per agent from its ACTUAL accept
+ * radius per axis and clipped once (the shared harness helper), and additive fixed-point
+ * atomics are order-independent — no sort. Symmetric shapes (a plain dot, an un-stretched
+ * glow) skip the heading rotation entirely — it cannot change a radial profile.
+ */
+declare function splatOrientedWorld(layout: WorldSplatLayout, cfg: OrientedWorldSplatConfig): (i: number) => void;
+export declare const pointSlot: {
+    /** Placement: the stored position plus a circular orbital wander whose radius and rate
+     *  scale with `params.randomness`, phase + rate hashed per agent. Needs
+     *  `params.{time, randomness}`. */
+    readonly orbitalPlace: (layout: {
+        readonly $: {
+            readonly params: {
+                readonly time: number;
+                readonly randomness: number;
+            };
+        };
+    }, cfg: {
+        radius: number;
+        rate: number;
+    }) => PointWorldSplatConfig["place"];
+    /** Brightness: a hash-phased sinusoidal twinkle (blend set by `params.twinkle`) × the
+     *  presence cascade. Needs `params.{time, twinkle}`. */
+    readonly twinkleBrightness: (layout: {
+        readonly $: {
+            readonly params: {
+                readonly time: number;
+                readonly twinkle: number;
+            };
+        };
+    }, cfg: {
+        freq: number;
+    }) => PointWorldSplatConfig["brightness"];
+    /** Body radius: the shared `params.bodyR` scaled by the presence cascade, floored. */
+    readonly presenceRadius: (layout: {
+        readonly $: {
+            readonly params: {
+                readonly bodyR: number;
+            };
+        };
+    }) => PointWorldSplatConfig["bodyRadius"];
+};
+export interface PointWorldSplatConfig {
+    shape: string;
+    res: number;
+    /** Placement part: stored position → rendered position (the orbital wander). */
+    place: (fi: number, stored: d.v2f) => d.v2f;
+    /** Brightness part: the twinkle × presence energy modulation. */
+    brightness: (fi: number) => number;
+    /** Body-radius part: per-agent size (presence cascade), already floored. */
+    bodyRadius: (fi: number) => number;
+    name: string;
+}
+/**
+ * Rasterize one un-oriented mote with a LIVE softness uniform (`params.softness` feathers the
+ * baked hard shapes toward the glow skirt at runtime; the glow shape is always fully soft —
+ * its mix folds away and the fast texel fn emits the Gaussian skirt only). Placement,
+ * brightness and per-agent size arrive as slot parts — they are the consumer's look.
+ */
+/** The point-splat core: agent state + the energy accumulator + the live softness. */
+export interface PointWorldSplatLayout {
+    readonly $: {
+        readonly agents: Vec4StateArray;
+        readonly accumE: AtomicU32[];
+        readonly params: {
+            readonly aspect: number;
+            readonly softness: number;
+        };
+    };
+}
+declare function splatPointWorld(layout: PointWorldSplatLayout, cfg: PointWorldSplatConfig): (i: number) => void;
+interface VolumeRenderLayout {
+    readonly $: {
+        readonly pos: Vec4StateArray;
+        readonly vel: Vec4StateArray;
+        readonly accumE: AtomicU32[];
+        readonly accumS: AtomicU32[];
+        readonly outTex: StorageTex;
+        readonly params: {
+            readonly colA: d.v4f;
+            readonly colB: d.v4f;
+            readonly centerX: number;
+            readonly centerYv: number;
+            readonly scale: number;
+            readonly rotC: number;
+            readonly rotS: number;
+            readonly aspect: number;
+            readonly size: number;
+            readonly exposure: number;
+            readonly softness: number;
+            readonly speedColorK: number;
+        };
+    };
+}
+export interface VolumeSplatConfig {
+    shape: string;
+    outRes: number;
+    maxSplatSize: number;
+    /** Radial reject: a texel contributes while q = dist²/size² < extQ. */
+    extQ: number;
+    names: {
+        splat: string;
+        glow: string;
+        profile: string;
+    };
+}
+/**
+ * Project a 3D swarm particle to screen (2D placement rotation + a soft perspective from its
+ * z), then accumulate the particle's softness-blended profile into the energy buffer and a
+ * speed-weighted copy into the second buffer (the resolve derives per-texel average speed for
+ * the rest→excited ramp). Additive fixed-point atomics are order-independent — no z-sort.
+ */
+declare function splatVolume(layout: VolumeRenderLayout, cfg: VolumeSplatConfig): (i: number) => void;
+interface ReliefRenderLayout {
+    readonly $: {
+        readonly pos: Vec4StateArray;
+        readonly col: Vec4StateArray;
+        readonly accumR: AtomicU32[];
+        readonly accumG: AtomicU32[];
+        readonly accumB: AtomicU32[];
+        readonly accumW: AtomicU32[];
+        readonly outTex: StorageTex;
+        readonly params: {
+            readonly rowX: d.v4f;
+            readonly rowY: d.v4f;
+            readonly rowZ: d.v4f;
+            readonly time: number;
+            readonly gridW: number;
+            readonly gridH: number;
+            readonly outW: number;
+            readonly outH: number;
+            readonly depth: number;
+            readonly wobbleAmp: number;
+            readonly depthShading: number;
+            readonly spacing: number;
+            readonly particleSize: number;
+            readonly aspect: number;
+            readonly zoom: number;
+            readonly transX: number;
+            readonly transY: number;
+        };
+    };
+}
+export interface ReliefSplatConfig {
+    shape: string;
+    /** Cap on a particle's body radius in texels (the window itself is dynamic). */
+    splatRCap: number;
+    /** Hard-edge anti-alias half-width, in render texels. */
+    aaW: number;
+    /** Child alpha below which a particle is skipped entirely. */
+    minAlpha: number;
+    /** Fixed-point scale for the atomic accumulators. */
+    fp: number;
+    /** Idle-wobble base frequency (× params.time). */
+    wobbleFreq: number;
+    /** Projection strength. */
+    perspK: number;
+    name: string;
+}
+/**
+ * The camera + colorFrom-layer splat variant: rotate the particle's 3D world position by the
+ * camera rows, project through a perspective from screen center (near ones enlarge, brighten
+ * and spread outward), then accumulate the shape's coverage as DEPTH-WEIGHTED colour into the
+ * four fixed-point buffers. The weight (persp²·shade) makes near particles dominate the
+ * per-texel average → stylized pseudo-occlusion, no z-sort.
+ */
+declare function splatRelief(layout: ReliefRenderLayout, cfg: ReliefSplatConfig): (x: number, y: number) => void;
+export interface RampResolveConfig {
+    /** Baked colour-space mode for the rest→excited mix (the canonical mixColorsVariants path). */
+    colorSpace: number;
+    res: number;
+    /** Fixed-point inverse gain (1/255 for the world splats, 1/256 for the volume splat). */
+    invGain: number;
+    /** Scale the energy by `params.exposure` (the volume consumer's brightness knob). */
+    exposure?: boolean;
+    /** Trail canvas: 'on' (always composited), {baked: boolean} (read baked out at trails = 0,
+     *  write kept so scrubbing up never ghosts), or 'none' (no trail buffer in the layout). */
+    trails: 'on' | 'none' | {
+        baked: boolean;
+    };
+    name: string;
+}
+/**
+ * Accumulators → colour: the rest→excited ramp mixes in the baked colour space, driven by the
+ * per-texel average excitement (`accumS / accumE`). Most texels get no splat energy at all and
+ * the endpoints are uniforms, so zero-energy texels skip the mix — RGB must still be colA (not
+ * black) or the fragment's bilinear upsample would drag a dark fringe into every edge texel.
+ */
+declare function resolveRamp(layout: RampResolveLayout, cfg: RampResolveConfig): (x: number, y: number) => void;
+/** Accumulated energy → a single tint's alpha (`params.color`) — transparent between agents. */
+declare function resolveTint(layout: {
+    readonly $: {
+        readonly accumE: AtomicU32[];
+        readonly outTex: StorageTex;
+        readonly params: {
+            readonly color: d.v4f;
+        };
+    };
+}, cfg: {
+    res: number;
+    name: string;
+}): (x: number, y: number) => void;
+/**
+ * Weighted-average colour resolve (RGB/W — the fixed-point scale cancels) + a coverage alpha
+ * from W (the relief consumer).
+ */
+declare function resolveWeightedColor(layout: ReliefRenderLayout, cfg: {
+    fp: number;
+    alphaK: number;
+    name: string;
+}): (x: number, y: number) => void;
+export declare const splat: {
+    readonly orientedWorld: typeof splatOrientedWorld;
+    readonly pointWorld: typeof splatPointWorld;
+    readonly volume: typeof splatVolume;
+    readonly relief: typeof splatRelief;
+};
+export declare const resolve: {
+    readonly ramp: typeof resolveRamp;
+    readonly tint: typeof resolveTint;
+    readonly weightedColor: typeof resolveWeightedColor;
+};
+export {};
+//# sourceMappingURL=agentRender.d.ts.map

package/dist/core/std/sim/agentRender.d.ts.map

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

package/dist/core/std/sim/agents.d.ts

@@ -0,0 +1,119 @@
+import { Expr, GpuComputeNode, GpuFragmentParams } from '../../gpu/contract';
+import { d } from '../../gpu/kit/index';
+import { AgentPipelineSpec, AgentSystem, AgentSystemConfig, DeviceTier } from '../../gpu/scaffolds/agentSystem';
+import { ComputeStep } from '../../gpu/compute';
+import { splat, resolve, OrientedWorldSplatConfig, PointWorldSplatConfig, VolumeSplatConfig, ReliefSplatConfig, RampResolveConfig, WorldSplatLayout, PointWorldSplatLayout, RampResolveLayout } from './agentRender';
+
+type AnyWgslStruct = d.AnyWgslStruct;
+/** The two render pipelines every agent shader ends its frame program with. */
+export interface RenderAgentsPipelines {
+    splat: AgentPipelineSpec;
+    resolve: AgentPipelineSpec;
+}
+/**
+ * The render subsystem as one declared part: a splat variant + its matching resolve, returned
+ * as ready pipeline specs for the frame program. Kernel factories live in `agentRender`.
+ */
+export declare const renderAgents: {
+    /** Heading-oriented world-space agents with the rest→excited colour ramp (Boids,
+     *  MagneticFilings, ParticleFlow). */
+    readonly orientedWorld: (layout: WorldSplatLayout & RampResolveLayout, cfg: Omit<OrientedWorldSplatConfig, "name"> & {
+        ramp: Omit<RampResolveConfig, "name" | "res" | "invGain"> & {
+            invGain?: number;
+        };
+        names: {
+            splat: string;
+            resolve: string;
+        };
+        /** Chain the extra bind group onto the splat (a shape family's own resources). */
+        extraOnSplat?: boolean;
+    }) => RenderAgentsPipelines;
+    /** Un-oriented point motes with a live softness and a single tint (FloatingParticles). */
+    readonly pointWorld: (layout: PointWorldSplatLayout & Parameters<typeof resolve.tint>[0], cfg: Omit<PointWorldSplatConfig, "name"> & {
+        names: {
+            splat: string;
+            resolve: string;
+        };
+    }) => RenderAgentsPipelines;
+    /** Perspective-projected 3D swarm with the speed-driven colour ramp (Particles). */
+    readonly volume: (layout: Parameters<typeof splat.volume>[0] & RampResolveLayout, cfg: Omit<VolumeSplatConfig, "names"> & {
+        ramp: Omit<RampResolveConfig, "name" | "res" | "invGain">;
+        names: VolumeSplatConfig["names"] & {
+            resolve: string;
+        };
+        extraOnSplat?: boolean;
+    }) => RenderAgentsPipelines;
+    /** Camera-projected image relief with depth-weighted colour averaging (ParticleField). */
+    readonly relief: (layout: Parameters<typeof splat.relief>[0], cfg: Omit<ReliefSplatConfig, "name"> & {
+        out: [number, number];
+        weightedColor: {
+            alphaK: number;
+        };
+        names: {
+            splat: string;
+            resolve: string;
+        };
+    }) => RenderAgentsPipelines;
+};
+/** What `bake` assembles at composition time from the declared parts. */
+export interface AgentSimBaked {
+    pipelines: Record<string, AgentPipelineSpec>;
+    /** Per-frame execution order (keys of `pipelines`). */
+    program: readonly string[];
+    /** One-shot spawn step, prepended on the first frame and on a reseed. */
+    initStep?: string;
+    /** Override the declared output extent (an aspect-fitted target decided per composition). */
+    outputSize?: [number, number];
+    /** A second bind group chained onto every pipeline marked `extra` (shape-family SDFs). */
+    extraBindGroup?: unknown;
+    /** Resources already available at composition to bind onto `externalKeys` immediately. */
+    bindNow?: Record<string, unknown>;
+    /** A composition payload handed to `frame` (fluid solvers, per-shape CPU resolvers…). */
+    setup?: unknown;
+}
+export interface AgentSimFragmentConfig {
+    /** The compute output the fragment bilinear-samples full-canvas (rgba16f is filterable). */
+    output: string;
+    /** GPU-free fallback: transparent (generators) or the raw child (child-driven effects). */
+    fallback: 'transparent' | 'child';
+    /** Optional compose over the sampled field (e.g. straight-alpha over the child). */
+    compose?: (field: Expr, params: GpuFragmentParams) => Expr;
+}
+export interface AgentSimConfig<TParams extends AnyWgslStruct> {
+    layout: AgentSystemConfig<TParams>['layout'];
+    params: TParams;
+    maxAgents: number;
+    /** Effective count ceiling per device tier (the prop's declared range is unchanged). */
+    countCap?: DeviceTier;
+    output: AgentSystemConfig<TParams>['output'];
+    /** Layout keys bound late or via `bake.bindNow` (a child RTT, a solver handoff texture). */
+    externalKeys?: readonly string[];
+    /** Read the child as a texture and late-bind it onto this external key (ParticleField). */
+    childTexture?: {
+        externalKey: string;
+    };
+    /** Composition-time baking: assemble the declared parts. Null = no simulation composes. */
+    bake: (params: GpuFragmentParams) => AgentSimBaked | null;
+    /** The per-frame CPU program: write uniforms, return the frame's steps (usually via
+     *  `sys.frame(...)`, prepending any extra passes the shader owns). */
+    frame: (sys: AgentSystem<TParams>, params: GpuFragmentParams, setup: unknown) => (frameParams: unknown) => ComputeStep[] | null;
+    fragment: AgentSimFragmentConfig;
+}
+/** The two definition halves the spread contributes (the ComputeBackedEffect shape). */
+export interface AgentSimSpread {
+    compute: GpuComputeNode;
+    gpu: {
+        fragment: (params: GpuFragmentParams) => Expr;
+    };
+}
+/**
+ * Compose an agent simulation: `bake` the declared parts into kernels, wire them through the
+ * `createAgentSystem` harness, and sample the resolved field in the fragment.
+ */
+export declare function agentSim<TParams extends AnyWgslStruct>(cfg: AgentSimConfig<TParams>): AgentSimSpread;
+export { force, torque, field, drift, channel, integrator, composeForces3, composeSteer2, composeTorques, restOrientationAngle } from './agentForces';
+export type { AgentForce3, AgentSteer2, AgentTorque, AgentFieldAt, AgentHome2, AgentDrift, AgentChannel, ShapeField3, } from './agentForces';
+export { splat, resolve, pointSlot } from './agentRender';
+export { shapeField } from './shapeFields';
+export * as agentFrame from './agentFrame';
+//# sourceMappingURL=agents.d.ts.map

package/dist/core/std/sim/agents.d.ts.map

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

package/dist/core/std/sim/feedback.d.ts

@@ -0,0 +1,51 @@
+import { GpuComputeNode, GpuFragmentParams } from '../../gpu/contract';
+import { SimBindContext, SimSize, SimSlot, SimTick } from '../../gpu/scaffolds/feedbackSim';
+
+/** The TypeGPU root, via the contract (direct `typegpu` imports are restricted to src/gpu/). */
+export type FeedbackRoot = NonNullable<GpuFragmentParams['gpu']>['root'];
+/** A 2D-dispatched TGSL kernel over the state grid. */
+export type FeedbackKernel = (cx: number, cy: number) => void;
+/** What the bind-group builders get: the scaffold's context plus the params uniform's buffer. */
+export type FeedbackBindContext = SimBindContext & {
+    paramsBuffer: unknown;
+};
+export interface FeedbackSimConfig<TParams, TGroups> {
+    /** State + display resolution per axis (square — both current consumers' shape). */
+    size: number;
+    format: 'rgba16float' | 'rgba32float';
+    /** Extra texture pairs swapping in lockstep with the state (TimeTrail's prev-live copy). */
+    extraSlots?: Record<string, SimSize>;
+    /** Orientation-independent extra textures. */
+    textures?: Record<string, SimSize>;
+    /** Prop whose value scales `dt`. */
+    speedProp?: string;
+    maxDeltaTime?: number;
+    /** The shader's per-frame params struct — the noun owns its uniform. */
+    paramsSchema: unknown;
+    /** Build one orientation's bind groups (called twice, late, by the scaffold). */
+    bindGroups: (ctx: FeedbackBindContext, read: SimSlot, write: SimSlot) => TGroups;
+    /** Build orientation-independent bind groups (called once, late). */
+    staticGroups?: (ctx: FeedbackBindContext) => unknown;
+    /**
+     * The state-advance kernel — ONE kernel per step, compile-time variant selected in the build
+     * callback. Splitting a step into several kernels is a different simulation (and different
+     * WGSL); a shader that needs a multi-dispatch step should not ride this noun's default frame.
+     */
+    step: FeedbackKernel;
+    /** Idle-gate policy: true → skip the frame entirely (the scaffold then skips the swap too). */
+    skip?: (t: SimTick<TGroups, unknown>) => boolean;
+    /** The per-frame params derivation — the one runtime surface. Written before the dispatch. */
+    values: (t: SimTick<TGroups, unknown>) => TParams;
+    /** Extra `outputs` entries beyond the scaffold's childTexture/display. */
+    outputs?: Record<string, unknown>;
+}
+/**
+ * The feedback-simulation noun. Spread it into a definition: `...feedbackSim((params, root) => ({...}))`.
+ *
+ * Requires a child (these are all child-consuming echo/decoder effects): bails to `null` (fragment
+ * passthrough) without one, without a device, or when the scaffold cannot allocate.
+ */
+export declare function feedbackSim<TParams, TGroups = unknown>(build: (params: GpuFragmentParams, root: FeedbackRoot) => FeedbackSimConfig<TParams, TGroups>): {
+    compute: GpuComputeNode;
+};
+//# sourceMappingURL=feedback.d.ts.map

package/dist/core/std/sim/feedback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback.d.ts","sourceRoot":"","sources":["../../../src/std/sim/feedback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAC,cAAc,EAAE,iBAAiB,EAAC,MAAM,oBAAoB,CAAA;AAEzE,OAAO,EAAyB,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,OAAO,EAAC,MAAM,iCAAiC,CAAA;AAGrI,gGAAgG;AAChG,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAExE,uDAAuD;AACvD,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;AAE7D,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG;IAAC,YAAY,EAAE,OAAO,CAAA;CAAC,CAAA;AAE1E,MAAM,WAAW,iBAAiB,CAAC,OAAO,EAAE,OAAO;IAC/C,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,aAAa,GAAG,aAAa,CAAA;IACrC,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,YAAY,EAAE,OAAO,CAAA;IACrB,iFAAiF;IACjF,UAAU,EAAE,CAAC,GAAG,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;IAChF,qEAAqE;IACrE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAA;IACpD;;;;OAIG;IACH,IAAI,EAAE,cAAc,CAAA;IACpB,+FAA+F;IAC/F,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;IAChD,8FAA8F;IAC9F,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;IACjD,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,EAClD,KAAK,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,YAAY,KAAK,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC,GAC9F;IAAC,OAAO,EAAE,cAAc,CAAA;CAAC,CA0C3B"}