@helixdev/helix-sdk 0.1.1-staging.7 → 0.1.1-staging.9

package/dist/multiplayer-contract/state.d.ts

@@ -0,0 +1,46 @@
+export type Vec3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/** Pinned units. Linear in meters / meters-per-second; every angle is degrees (see the *Deg suffixes). */
+export declare const UNITS: {
+    readonly position: "meters";
+    readonly velocity: "meters/second";
+    readonly angles: "degrees";
+};
+/** Stable per-player identity (set at join from the room credential; not part of the per-tick churn). */
+export interface PlayerIdentity {
+    /** Opaque per-connection room playerKey (= the state.players map key). NOT the credential `sub` — that stays server-side (§4). */
+    id: string;
+    /** Sanitized display name for nameplates (sanitized before it enters room state — see plan H4). */
+    displayName: string;
+}
+/**
+ * The per-tick replicated kinematic + animation parameters for one player. The room holds the
+ * authoritative copy (a @colyseus/schema mirror of these fields); the NetworkDriver maps each field
+ * onto the named character blackboard param. FIRST DRAFT — the exact injected set is confirmed by
+ * spike S2 (engine headless-replica write-path); changing the field set bumps CONTRACT_VERSION.
+ */
+export interface PlayerReplicaState {
+    /** World feet position, METERS. Interpolated by the remote replica. */
+    position: Vec3;
+    /** Body facing, DEGREES. The adapter converts to radians for body.setFacingYaw. */
+    facingYawDeg: number;
+    /** Horizontal planar speed, M/S. → blackboard 'speed' (blend-space input). */
+    speed: number;
+    /** Signed movement direction relative to facing, DEGREES (−180..180). → blackboard 'direction'. */
+    moveDirectionDeg: number;
+    /** Vertical velocity, M/S (+up). → blackboard 'verticalVelocity' (jump/fall states). */
+    verticalVelocity: number;
+    /** Ground contact. → blackboard 'isGrounded' (grounded/air transitions). */
+    grounded: boolean;
+    /** Crouch stance. → routes the locomotion anim graph to its crouched states. */
+    crouched: boolean;
+    /** Aim yaw, DEGREES (world). → blackboard 'cameraYaw' (aim-additive source). */
+    aimYawDeg: number;
+    /** Aim pitch, DEGREES. → blackboard 'cameraPitch' (aim-additive source). */
+    aimPitchDeg: number;
+    /** Ability ids currently active (e.g. ['locomotion','fly']). Drives remote ability activation. */
+    activeAbilities: string[];
+}

package/dist/multiplayer-contract/state.js

@@ -0,0 +1,15 @@
+// Replicated player state — the parameters the room broadcasts and the engine's NetworkDriver feeds
+// into the character blackboard. We replicate PARAMETERS, never bone transforms: animation runs fully
+// client-side off these values (see character-architecture §3).
+//
+// ALL ANGLES ARE DEGREES — every angular field is suffixed *Deg. One unit on the wire, so there is no
+// radians/degrees ambiguity to forget. The engine mixes units internally (the body is radians, the
+// animation params are degrees); the engine adapter owns the single deg↔rad conversion at the body
+// boundary (body.setFacingYaw) — the contract itself stays all-degrees.
+/** Pinned units. Linear in meters / meters-per-second; every angle is degrees (see the *Deg suffixes). */
+export const UNITS = {
+    position: 'meters',
+    velocity: 'meters/second',
+    angles: 'degrees',
+};
+//# sourceMappingURL=state.js.map

package/dist/multiplayer-contract/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/multiplayer-contract/state.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,sGAAsG;AACtG,gEAAgE;AAChE,EAAE;AACF,sGAAsG;AACtG,mGAAmG;AACnG,mGAAmG;AACnG,wEAAwE;AAIxE,0GAA0G;AAC1G,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,QAAQ,EAAE,QAAQ;IAClB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,SAAS;CACT,CAAC"}

package/dist/multiplayer.d.ts

@@ -0,0 +1,96 @@
+import { type StateMessage, type RoomState, type PlayerState, type EntityState, type RoomVarValue, type Vec3 } from './multiplayer-contract';
+export type ReplicaInput = Omit<StateMessage, 'seq'>;
+/** Options for joinRoom — only needed where the API base can't be derived from the token (local dev/tests). */
+export interface JoinRoomOptions {
+    /** Override the platform API base URL. Default: the world_session token's `iss`, else configure({ apiBaseUrl }). */
+    apiBaseUrl?: string;
+}
+/** The curated live-room surface handed to world authors. Colyseus's API, re-exposed under Helix.*. */
+export interface HelixRoom {
+    readonly roomId: string;
+    readonly sessionId: string;
+    /** Authoritative shared state (a @colyseus/schema instance shaped like the contract RoomState). */
+    readonly state: RoomState;
+    /** Fires after every applied patch from the server. */
+    onStateChange(cb: (state: RoomState) => void): void;
+    /** Subscribe to a collection's adds (Tier-2 seam: players today, entities reserved). Fires for existing entries too. */
+    onAdd(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
+    onAdd(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
+    onRemove(collection: 'players', cb: (player: PlayerState, id: string) => void): void;
+    onRemove(collection: 'entities', cb: (entity: EntityState, id: string) => void): void;
+    /** A world-authored server→client message (the room broadcasts these for declared events). */
+    onMessage<Payload = unknown>(type: string, cb: (payload: Payload) => void): void;
+    /** Per-tick predicted state. Coalesced + flushed at MESSAGE_RATE.stateHz, seq-tagged (D3/D4). */
+    sendState(input: ReplicaInput): void;
+    /** Activate/deactivate a built-in ability (sent immediately; server enforces the rate ceiling). */
+    sendAbility(ability: string, active: boolean): void;
+    /** A world-authored declared action (the generic extensibility channel). */
+    sendAction(name: string, args?: Record<string, RoomVarValue>): void;
+    /**
+     * Upload an owner-authoritative entity's client-simulated state (Tier 2 Phase 4.6c). Call only for an entity
+     * whose `controller` is this client (state.entities[id].controller === sessionId); the room rejects others.
+     * Sent immediately, per-entity seq-tagged; the room gates the position against the kind's maxSpeed + clamps vars.
+     */
+    uploadEntity(entityId: string, input: {
+        position: Vec3;
+        vars?: Record<string, RoomVarValue>;
+    }): void;
+    /**
+     * Upload MANY owner-authoritative entities in ONE message (Tier 2 Phase 4.10). Prefer this over per-entity
+     * uploadEntity when hosting multiple entities: the per-connection rate cap counts messages, so N single uploads
+     * spend N tokens/tick and starve, while one batch spends one. Position is sent as a compact [x,y,z] tuple; each
+     * entry is gated/clamped server-side exactly like uploadEntity. Pass only entities this client controls.
+     */
+    uploadEntities(entities: ReadonlyArray<{
+        id: string;
+        position: Vec3;
+        vars?: Record<string, RoomVarValue>;
+        epoch?: number;
+    }>): void;
+    /** Sent-but-unacknowledged states — the reconciliation tail the engine NetworkDriver replays (D4). */
+    pendingInputs(): readonly StateMessage[];
+    /** Prune the reconciliation buffer once the server confirms it processed up to `seq` (D4). */
+    acknowledge(seq: number): void;
+    /** Connection dropped; the client is auto-reconnecting (built into @colyseus/sdk). */
+    onDrop(cb: () => void): void;
+    /** Auto-reconnection succeeded. */
+    onReconnect(cb: () => void): void;
+    /** Left for good (kicked, room disposed, or after we leave) — `code` is the close code. */
+    onLeave(cb: (code: number) => void): void;
+    /** Leave intentionally (no reconnection grace held server-side). */
+    leave(): Promise<void>;
+}
+export interface MultiplayerHost {
+    isInitialized(): boolean;
+    getToken(): string | null;
+    getWorldId(): string | null;
+}
+export declare class HelixMultiplayer {
+    private readonly host;
+    private apiBaseUrl;
+    private room;
+    private callbacks;
+    private seq;
+    private entitySeq;
+    private entityBatchSeq;
+    private pendingInput;
+    private flushTimer;
+    private inputBuffer;
+    private worldId;
+    constructor(host: MultiplayerHost);
+    configure(options: {
+        apiBaseUrl: string;
+    }): void;
+    joinRoom(worldId?: string, options?: JoinRoomOptions): Promise<HelixRoom>;
+    private requestJoin;
+    private makeHandle;
+    private startFlush;
+    private flush;
+    private persistReconnect;
+    private readReconnect;
+    private reconnectWsUrl;
+    private clearReconnect;
+    private tryReconnect;
+    private leave;
+    private teardown;
+}

package/dist/multiplayer.js

@@ -0,0 +1,247 @@
+// Helix.multiplayer — the client half of HELIX multiplayer (plan pillar D). Wraps the official
+// Colyseus browser client (@colyseus/sdk, schema v4 — the renamed colyseus.js, paired with the 0.17
+// room server) so world authors never import it directly. Flow: POST the platform
+// /api/v1/instant-worlds/:worldId/join with the world_session token → { wsUrl, roomName, credential }
+// → Client.joinOrCreate(token) → a curated HelixRoom handle. The engine NetworkDriver consumes the
+// room state; this module owns the connect handshake, the throttled seq-tagged send path (D3), the
+// reconciliation buffer (D4), and teardown/reconnection wiring (D5).
+import { ClientMessageType, MESSAGE_RATE, } from './multiplayer-contract';
+// ~12s of inputs at 10Hz — generous reconciliation window; bounded so a missing server ack can't grow it forever.
+const INPUT_BUFFER_MAX = 120;
+// sessionStorage key (per world) for the colyseus reconnectionToken + its wsUrl. sessionStorage is per-tab and
+// SURVIVES A RELOAD but not a tab close — exactly the lifetime we want: a reload resumes the held seat; a new
+// tab / post-close start does a fresh join. This is what makes a reload RECONNECT (bypassing the room's
+// onAuth one-seat-per-account gate, which would otherwise reject the reload's fresh join during the grace
+// window) instead of falling back to single-player.
+const RECONNECT_KEY = (worldId) => `helix:mp:reconnect:${worldId}`;
+export class HelixMultiplayer {
+    host;
+    apiBaseUrl = null;
+    room = null;
+    callbacks = null;
+    seq = 0;
+    entitySeq = {}; // per-entity monotonic upload seq (4.6c owner-entity channel)
+    entityBatchSeq = 0; // per-connection monotonic batch seq (4.10 owner-entity batch channel)
+    pendingInput = null;
+    flushTimer = null;
+    inputBuffer = [];
+    worldId = null; // the joined world (the reconnect-token storage key)
+    constructor(host) {
+        this.host = host;
+    }
+    // Pin the platform API base once (local dev / staging where the token issuer isn't the live host).
+    configure(options) {
+        this.apiBaseUrl = options.apiBaseUrl.replace(/\/$/, '');
+    }
+    // Join (or create) this world's room. worldId defaults to the current world. Requires login: a guest
+    // has no world_session and can't reach /join — multiplayer is logged-in only (single-player for guests).
+    async joinRoom(worldId, options = {}) {
+        if (!this.host.isInitialized())
+            throw new Error('Helix: call Helix.init() before Helix.multiplayer.joinRoom()');
+        if (this.room)
+            throw new Error('Helix.multiplayer: already in a room — call leave() first');
+        const token = this.host.getToken();
+        if (!token)
+            throw new Error('Helix.multiplayer: multiplayer requires login (no session) — call Helix.auth.requestLogin() first');
+        const id = worldId ?? this.host.getWorldId();
+        if (!id)
+            throw new Error('Helix.multiplayer: no world id — pass joinRoom(worldId) when running outside a HELIX shell');
+        const apiBase = options.apiBaseUrl?.replace(/\/$/, '') ?? this.apiBaseUrl ?? issuerOf(token);
+        if (!apiBase)
+            throw new Error('Helix.multiplayer: cannot resolve the API base URL — call Helix.multiplayer.configure({ apiBaseUrl })');
+        const colyseus = (await import('@colyseus/sdk'));
+        // RESUME FIRST: on a reload, a seat persisted in sessionStorage is still held in the server's grace window —
+        // reconnect to it (resumes the same seat + its vars, bypassing onAuth) instead of a fresh join that onAuth
+        // would reject as a duplicate. On any failure (grace expired / clean despawn / new tab) fall back to /join.
+        let room = await this.tryReconnect(colyseus, id);
+        if (!room) {
+            const reservation = await this.requestJoin(apiBase, id, token);
+            const client = new colyseus.Client(reservation.wsUrl);
+            // buildId is the matchmaking filter (room filterBy(['buildId'])) — it groups players per active build.
+            // The room re-validates it against the verified credential in onAuth, so a spoofed value can't cross builds.
+            room = await client.joinOrCreate(reservation.roomName, { token: reservation.credential, buildId: reservation.buildId });
+            this.persistReconnect(id, reservation.wsUrl, room.reconnectionToken);
+        }
+        this.worldId = id;
+        this.room = room;
+        this.callbacks = colyseus.getStateCallbacks(room);
+        this.startFlush();
+        // Keep the persisted token fresh as colyseus rotates it (e.g. after an in-page auto-reconnect).
+        room.onReconnect(() => this.persistReconnect(id, this.reconnectWsUrl(id), room.reconnectionToken));
+        room.onLeave(() => this.teardown());
+        return this.makeHandle(room);
+    }
+    async requestJoin(apiBase, worldId, token) {
+        const res = await fetch(`${apiBase}/api/v1/instant-worlds/${encodeURIComponent(worldId)}/join`, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}` },
+        });
+        if (!res.ok) {
+            const detail = await res.json().catch(() => null);
+            const message = (detail && typeof detail.message === 'string' && detail.message) || `HTTP ${res.status}`;
+            throw new Error(`Helix.multiplayer: join failed — ${message}`);
+        }
+        return (await res.json());
+    }
+    makeHandle(room) {
+        const collection = (name) => {
+            if (!this.callbacks)
+                throw new Error('Helix.multiplayer: room not ready');
+            return this.callbacks(room.state)[name];
+        };
+        return {
+            roomId: room.roomId,
+            sessionId: room.sessionId,
+            get state() {
+                return room.state;
+            },
+            onStateChange: (cb) => void room.onStateChange((s) => cb(s)),
+            onAdd: (name, cb) => void collection(name).onAdd((v, k) => cb(v, k), true),
+            onRemove: (name, cb) => void collection(name).onRemove((v, k) => cb(v, k)),
+            onMessage: (type, cb) => void room.onMessage(type, (p) => cb(p)),
+            sendState: (input) => {
+                this.pendingInput = input;
+            },
+            sendAbility: (ability, active) => room.send(ClientMessageType.Ability, { ability, active }),
+            sendAction: (name, args) => room.send(ClientMessageType.Action, { name, args }),
+            uploadEntity: (entityId, input) => {
+                const seq = (this.entitySeq[entityId] = (this.entitySeq[entityId] ?? 0) + 1);
+                room.send(ClientMessageType.EntityState, { entity: entityId, seq, position: input.position, vars: input.vars });
+            },
+            uploadEntities: (entities) => {
+                if (entities.length === 0)
+                    return;
+                const seq = ++this.entityBatchSeq;
+                const states = entities.map((e) => ({
+                    e: e.id,
+                    p: [e.position.x, e.position.y, e.position.z],
+                    ...(e.vars !== undefined ? { v: e.vars } : {}),
+                    ...(e.epoch !== undefined ? { ep: e.epoch } : {}),
+                }));
+                room.send(ClientMessageType.EntityStateBatch, { seq, states });
+            },
+            pendingInputs: () => this.inputBuffer.slice(),
+            acknowledge: (seq) => {
+                this.inputBuffer = this.inputBuffer.filter((m) => m.seq > seq);
+            },
+            onDrop: (cb) => void room.onDrop(() => cb()),
+            onReconnect: (cb) => void room.onReconnect(() => cb()),
+            onLeave: (cb) => void room.onLeave((code) => cb(code)),
+            leave: () => this.leave(),
+        };
+    }
+    // D3: coalesce per-frame sendState calls and flush the latest at most stateHz times/second, tagging a
+    // monotonic seq. D4: buffer each sent state (bounded) so the engine can replay the unacknowledged tail.
+    startFlush() {
+        const periodMs = Math.round(1000 / MESSAGE_RATE.stateHz);
+        this.flushTimer = setInterval(() => this.flush(), periodMs);
+    }
+    flush() {
+        if (!this.pendingInput || !this.room)
+            return;
+        const message = { ...this.pendingInput, seq: ++this.seq };
+        this.pendingInput = null;
+        this.room.send(ClientMessageType.State, message);
+        this.inputBuffer.push(message);
+        if (this.inputBuffer.length > INPUT_BUFFER_MAX)
+            this.inputBuffer.shift();
+    }
+    // D5 RECONNECTION (sessionStorage-backed): persist / read / clear the colyseus reconnectionToken + its wsUrl
+    // per world. sessionStorage is per-tab and survives a RELOAD but not a close — so a reload resumes the held
+    // seat (below) while a new tab does a fresh join. We deliberately do NOT consent-leave on tab unload anymore:
+    // letting the socket drop holds the seat in the server's grace window so a reload can RECONNECT to it (and
+    // keep its vars), instead of a fresh join that the room's one-seat-per-account onAuth gate would reject. A
+    // genuine close just lets the grace window expire (the seat despawns after RECONNECT_GRACE_SEC).
+    persistReconnect(worldId, wsUrl, reconnectionToken) {
+        if (typeof sessionStorage === 'undefined' || !wsUrl || !reconnectionToken)
+            return;
+        try {
+            sessionStorage.setItem(RECONNECT_KEY(worldId), JSON.stringify({ wsUrl, reconnectionToken }));
+        }
+        catch { /* storage unavailable */ }
+    }
+    readReconnect(worldId) {
+        if (typeof sessionStorage === 'undefined')
+            return null;
+        try {
+            const raw = sessionStorage.getItem(RECONNECT_KEY(worldId));
+            const v = raw ? JSON.parse(raw) : null;
+            return v?.wsUrl && v.reconnectionToken ? { wsUrl: v.wsUrl, reconnectionToken: v.reconnectionToken } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    reconnectWsUrl(worldId) {
+        return this.readReconnect(worldId)?.wsUrl ?? '';
+    }
+    clearReconnect(worldId) {
+        if (typeof sessionStorage === 'undefined')
+            return;
+        try {
+            sessionStorage.removeItem(RECONNECT_KEY(worldId));
+        }
+        catch { /* ignore */ }
+    }
+    // Resume a grace-held seat (a reload). Returns the resumed room, or null to fall through to a fresh join
+    // (no saved token / grace expired / seat despawned / stale wsUrl — reconnect() rejects and we drop the token).
+    async tryReconnect(colyseus, worldId) {
+        const saved = this.readReconnect(worldId);
+        if (!saved)
+            return null;
+        try {
+            const client = new colyseus.Client(saved.wsUrl);
+            const room = await client.reconnect(saved.reconnectionToken);
+            this.persistReconnect(worldId, saved.wsUrl, room.reconnectionToken); // the token may rotate on resume
+            return room;
+        }
+        catch {
+            this.clearReconnect(worldId);
+            return null;
+        }
+    }
+    // Leave for good: consented (frees the seat immediately, no grace) + drop the saved token so we don't try to
+    // resume a seat we deliberately left. (A reload does NOT call this — it just unloads.)
+    async leave() {
+        const room = this.room;
+        if (this.worldId)
+            this.clearReconnect(this.worldId);
+        this.teardown();
+        if (room)
+            await room.leave(true);
+    }
+    // Reset in-memory state. Called on a drop too (onLeave) — it does NOT clear the saved reconnect token, so a
+    // later reload can still resume the grace-held seat.
+    teardown() {
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        this.flushTimer = null;
+        this.room = null;
+        this.callbacks = null;
+        this.pendingInput = null;
+        this.inputBuffer = [];
+        this.worldId = null;
+        this.seq = 0;
+        this.entitySeq = {};
+        this.entityBatchSeq = 0;
+    }
+}
+// Read the `iss` claim from a JWT without verifying (the world_session issuer is the platform API
+// origin). Verification isn't this side's job; the room verifies the credential against JWKS. Returns
+// null if there's no usable http(s) issuer — in which case the world must configure({ apiBaseUrl }).
+// NOTE: the new backend does not set `iss` on the world_session yet, so configure()/options is the
+// resolution path until the join lane adds it (tracked in MIGRATION.md, backend step).
+function issuerOf(token) {
+    const segment = token.split('.')[1];
+    if (!segment)
+        return null;
+    try {
+        const json = atob(segment.replace(/-/g, '+').replace(/_/g, '/'));
+        const iss = JSON.parse(json).iss;
+        return typeof iss === 'string' && /^https?:\/\//.test(iss) ? iss.replace(/\/$/, '') : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=multiplayer.js.map

package/dist/multiplayer.js.map

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

package/dist/protocol.d.ts

@@ -1,4 +1,4 @@
-export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_VERSION = 2;
 export type HelixUser = {
     id: string;
     username: string;
@@ -15,18 +15,28 @@ export type HelixSession = {
     scopes: string[];
     user: HelixUser;
 };
+export type DebugLogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+export type DebugLogEntry = {
+    level: DebugLogLevel;
+    args: string[];
+    t: number;
+};
 export type WorldToShellMessage = {
     type: 'helix:ready';
     protocolVersion: number;
 } | {
     type: 'helix:request-login';
     requestId: string;
+} | {
+    type: 'helix:log';
+    entry: DebugLogEntry;
 };
 export type ShellToWorldMessage = {
     type: 'helix:init';
     protocolVersion: number;
     world: HelixWorldContext;
     session: HelixSession | null;
+    debug?: boolean;
 } | {
     type: 'helix:session';
     session: HelixSession | null;

package/dist/protocol.js

@@ -1,7 +1,8 @@
 // postMessage protocol between a world (sandboxed iframe) and the HELIX shell
 // (the play page, or a local `helix dev` shell). This file IS the wire contract
-// — both sides import it; version any breaking change.
-export const PROTOCOL_VERSION = 1;
+// — both sides import it; version any breaking change. (v2 is additive: helix:init
+// gained `debug`, and helix:log carries world logs to the shell when debug is on.)
+export const PROTOCOL_VERSION = 2;
 export function isShellMessage(data) {
     return (typeof data === 'object' &&
         data !== null &&

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,uDAAuD;AAEvD,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA6ClC,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ;QACrD,CAAE,IAAyB,CAAC,IAAI,KAAK,YAAY;YAC9C,IAAyB,CAAC,IAAI,KAAK,eAAe;YAClD,IAAyB,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAC5D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,mFAAmF;AACnF,mFAAmF;AAEnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC;AA4DlC,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,KAAK,IAAI;QACb,OAAQ,IAA2B,CAAC,IAAI,KAAK,QAAQ;QACrD,CAAE,IAAyB,CAAC,IAAI,KAAK,YAAY;YAC9C,IAAyB,CAAC,IAAI,KAAK,eAAe;YAClD,IAAyB,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAC5D,CAAC;AACJ,CAAC"}