@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/dist/errors/plugin-error.d.ts

@@ -0,0 +1,69 @@
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes";
+import type { ErrorEnvelope } from "./envelope";
+/**
+ * Typed error every failed plugin API call rejects with.
+ *
+ * Rehydrated client-side from the wire `ErrorEnvelope` (`fromEnvelope`) — the
+ * class itself never crosses the worker boundary. Branch on the stable string
+ * `code`; use `PluginError.is()` rather than `instanceof` (a bundled duplicate
+ * SDK copy breaks `instanceof`, never the brand).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await snaptrude.design.boolean.union(handles)
+ * } catch (e) {
+ *   if (PluginError.is(e) && e.code === "RATE_LIMITED") {
+ *     await sleep(e.details?.retryAfterMs as number)
+ *   } else {
+ *     throw e
+ *   }
+ * }
+ * ```
+ */
+export declare class PluginError extends Error {
+    readonly code: WirePluginErrorCode;
+    readonly errorId: string;
+    readonly details?: Record<string, unknown>;
+    readonly handle?: string;
+    readonly methodPath?: string;
+    readonly hint?: string;
+    constructor(envelope: ErrorEnvelope);
+    /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+    static is(value: unknown): value is PluginError;
+    /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+    get category(): PluginErrorCategory;
+}
+export declare class PluginValidationError extends PluginError {
+}
+export declare class PluginNotFoundError extends PluginError {
+}
+export declare class PluginPermissionError extends PluginError {
+}
+export declare class PluginHandleError extends PluginError {
+}
+export declare class PluginQuotaError extends PluginError {
+}
+export declare class PluginTimeoutError extends PluginError {
+}
+export declare class PluginTransportError extends PluginError {
+}
+export declare class PluginLifecycleError extends PluginError {
+}
+export declare class PluginExecutionError extends PluginError {
+}
+export declare class PluginInternalError extends PluginError {
+}
+/**
+ * Rehydrate a wire envelope into the typed error the plugin catches.
+ * A code outside the known union (newer host) constructs the base
+ * `PluginError` with the code preserved verbatim.
+ */
+export declare function fromEnvelope(envelope: ErrorEnvelope): PluginError;
+/**
+ * Build an envelope for a CLIENT-detected failure (transport rejection,
+ * legacy host without `errorInfo`). Host-originated envelopes are built by
+ * the host's `toErrorEnvelope` mapper, never by this.
+ */
+export declare function makeClientEnvelope(code: PluginErrorCode, message: string, extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>): ErrorEnvelope;
+//# sourceMappingURL=plugin-error.d.ts.map

package/dist/errors/plugin-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-error.d.ts","sourceRoot":"","sources":["../../src/errors/plugin-error.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAExF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAc/C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;gBAEV,QAAQ,EAAE,aAAa;IAYnC,wFAAwF;IACxF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAQ/C,sFAAsF;IACtF,IAAI,QAAQ,IAAI,mBAAmB,CAElC;CACF;AAID,qBAAa,qBAAsB,SAAQ,WAAW;CAAG;AACzD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AACvD,qBAAa,qBAAsB,SAAQ,WAAW;CAAG;AACzD,qBAAa,iBAAkB,SAAQ,WAAW;CAAG;AACrD,qBAAa,gBAAiB,SAAQ,WAAW;CAAG;AACpD,qBAAa,kBAAmB,SAAQ,WAAW;CAAG;AACtD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,oBAAqB,SAAQ,WAAW;CAAG;AACxD,qBAAa,mBAAoB,SAAQ,WAAW;CAAG;AAqBvD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,GAAG,WAAW,CAIjE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC,CAAC,GACjF,aAAa,CAQf"}

package/dist/handles.d.ts

@@ -1,22 +1,57 @@
 import * as z from "zod";
+import type { ArenaKind } from "./api/core/handles";
 /**
  * An opaque, kind-tagged reference to a host-side object that crosses the RPC
  * boundary by IDENTITY rather than by value. See `PLUGIN_API_EXPOSURE_HLD.md` §9.
  *
- * The phantom `__handle` brand makes a `Handle<"profile">` incompatible with a
- * `Handle<"mass">` at compile time. At runtime a handle is just a string of the
- * form `"<kind>_<token>"` (e.g. `"profile_k3f9a2x"`), so it is structured-clone
- * safe and engine-free — plugin-core never imports the engine type it points at.
+ * A handle is a small CLASS instance wrapping the wire id. The phantom
+ * `__handle` brand makes a `Handle<"profile">` incompatible with a
+ * `Handle<"vec3">` at compile time. On the wire the id string is all that
+ * travels: the client SDK unwraps `Handle` arguments to `.id` before the RPC
+ * call, and the host tags returned handles as `{ __h: "<id>" }` (via
+ * {@linkcode Handle.toJSON}) for the client to re-wrap.
+ *
+ * Plugin-side lifecycle: the client SDK interns one live instance per id and
+ * registers it with a FinalizationRegistry — dropping every reference to a
+ * handle eventually releases its host registry entry. Deterministic release is
+ * still preferred: `core.handles.release/releaseAll` or scopes.
+ *
+ * Crossing non-RPC boundaries (UI postMessage, persistence, logging):
+ * send {@linkcode Handle.id} — structured clone strips the class prototype.
  */
-export type Handle<K extends string> = string & {
+export declare class Handle<K extends string> {
+    readonly id: string;
+    /** Phantom brand — keeps `Handle<"vec3">` ≠ `Handle<"mass">` at compile time. */
     readonly __handle: K;
-};
+    constructor(id: string);
+    /** Wire tag — the host's result serialization (JSON round-trip) calls this. */
+    toJSON(): {
+        __h: string;
+    };
+    /** Template-string / logging form stays the bare id. */
+    toString(): string;
+    /** Identity comparison by id — safe across re-wraps. */
+    equals(other: Handle<string>): boolean;
+    /**
+     * Explicit-resource-management hook (`await using`). A no-op here; the
+     * plugin-client runtime installs the real enqueue-release behavior on the
+     * interned instance.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/** Union of all releasable (arena-backed) handle kinds. */
+export type AnyArenaHandle = Handle<ArenaKind>;
 /**
  * A scene-entity handle. Backed by the host `Component.id` and resolved live via
  * the host scene index (StructureCollection) — never stored in the resource
  * registry. Stable across undo/redo and persistable across sessions (§9.2).
+ * Entity handles remain raw branded STRINGS (not {@linkcode Handle} instances):
+ * they have no arena entry, no lifecycle, and are equality-matched against
+ * plain ids embedded in result records.
  */
-export type EntityId<K extends string = string> = Handle<K>;
+export type EntityId<K extends string = string> = string & {
+    readonly __handle: K;
+};
 /** Resource handle: a host-resident, session-ephemeral geometry object (§9.2). */
 export type ProfileHandle = Handle<"profile">;
 /** Resource handle: a host-resident contour (outer profile + hole profiles). */
@@ -40,6 +75,31 @@ export type ComponentHandle = EntityId<"component">;
  * Project-scoped, not a scene entity.
  */
 export type MaterialHandle = EntityId<"material">;
+/**
+ * A placed **scene underlay** — an imported reference plane the user traces over:
+ * an image `FloorPlan`, a `PDF` overlay, or a `CAD` sketch. Entity-style: the token
+ * IS the raw `Component.id` (`fp_…` / a pdf id / `cad_…`). Resolved live host-side
+ * via the import-order layer walk (`collectStoreyImportItems`) — NOT via
+ * `ComponentUtility.FindComponentById`, which does not index underlays. No arena, no
+ * quota, stable across undo/redo. Returned by `core.io.import.{image,pdf,cadJson}`
+ * and consumed by every `core.io.underlay.*` method.
+ */
+export type UnderlayHandle = EntityId<"underlay">;
+/**
+ * The project's **site terrain** — a Mapbox-derived topography mesh. Entity-style
+ * and a project **singleton** (one terrain per project): the token is the terrain
+ * `Component.id` (`terrain-…`), resolved live via `TerrainOperations.getTerrain()`
+ * (absent from the level component collections, so NOT `FindComponentById`).
+ * Returned by `core.io.import.terrain`.
+ */
+export type TerrainHandle = EntityId<"terrain">;
+/**
+ * A handle to an **asynchronous import job** (today: a DWG → Forge conversion, which
+ * can take minutes). Returned immediately by `core.io.import.dwg`; poll it via
+ * `core.io.job.*` (`getStatus` / `isComplete` / `getResult` / `getError`). The token
+ * is the engine's import request id; job state lives in a host-side registry.
+ */
+export type ImportJobHandle = EntityId<"importJob">;
 export type Vec3Handle = Handle<"vec3">;
 export type QuatHandle = Handle<"quat">;
 export type LineHandle = Handle<"line">;
@@ -83,14 +143,18 @@ export type BBoxComponents = {
 };
 /**
  * Build a Zod schema validating a handle of the given `kind` at the trust
- * boundary. It checks only the `"<kind>_"` prefix shape; existence, kind, and
- * ownership are enforced host-side by the HandleRegistry (§9.7). Keeping it to
- * the prefix is engine-free and avoids an existence oracle.
+ * boundary and emitting a {@linkcode Handle} instance for impl code. Inbound
+ * forms accepted:
+ *  - the bare id string (the wire form — the client unwraps args to ids)
+ *  - a live `Handle` instance (host-internal re-parse, direct host callers)
+ *  - `{ __h: string }` (the tagged result form, echoed back as an arg)
+ *  - `{ id: string }` (a Handle stripped by structured clone at the UI boundary)
+ * Shape checking stays prefix-only; existence, kind, and ownership are enforced
+ * host-side by the HandleRegistry (§9.7) — no existence oracle.
  */
-export declare const handleSchema: <K extends string>(kind: K) => z.ZodPipe<z.ZodString, z.ZodTransform<Handle<K>, string>>;
-export declare const ProfileHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"profile">, string>>;
-export declare const ContourHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"contour">, string>>;
-export declare const MassHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"mass">, string>>;
+export declare const handleSchema: <K extends string>(kind: K) => z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<K>, string>>;
+export declare const ProfileHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"profile">, string>>;
+export declare const ContourHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"contour">, string>>;
 /**
  * Entity handles are raw `Component.id` strings (no `"<kind>_"` prefix) — validated
  * only as a non-empty string, resolved live via the scene index host-side.
@@ -101,17 +165,25 @@ export declare const ComponentHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Comp
  * prefix) — validated only as non-empty, resolved live via `scene.getMaterialByName`.
  */
 export declare const MaterialHandle: z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, string>>;
-export declare const Vec3Handle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"vec3">, string>>;
-export declare const QuatHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"quat">, string>>;
-export declare const LineHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"line">, string>>;
-export declare const ArcHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"arc">, string>>;
-export declare const CurveHandle: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"line">, string>>, z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"arc">, string>>]>;
-export declare const CircleHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"circle">, string>>;
-export declare const BrepHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"brep">, string>>;
-export declare const FaceHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"face">, string>>;
-export declare const EdgeHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"edge">, string>>;
-export declare const HalfEdgeHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"halfedge">, string>>;
-export declare const VertexHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Handle<"vertex">, string>>;
+/**
+ * {@linkcode UnderlayHandle} / {@linkcode TerrainHandle} / {@linkcode ImportJobHandle}
+ * are entity-style handles — raw host ids, validated only as a non-empty string
+ * (no `"<kind>_"` prefix), resolved live host-side (existence enforced there).
+ */
+export declare const UnderlayHandle: z.ZodPipe<z.ZodString, z.ZodTransform<UnderlayHandle, string>>;
+export declare const TerrainHandle: z.ZodPipe<z.ZodString, z.ZodTransform<TerrainHandle, string>>;
+export declare const ImportJobHandle: z.ZodPipe<z.ZodString, z.ZodTransform<ImportJobHandle, string>>;
+export declare const Vec3Handle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"vec3">, string>>;
+export declare const QuatHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"quat">, string>>;
+export declare const LineHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"line">, string>>;
+export declare const ArcHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"arc">, string>>;
+export declare const CurveHandle: z.ZodUnion<readonly [z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"line">, string>>, z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"arc">, string>>]>;
+export declare const CircleHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"circle">, string>>;
+export declare const BrepHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"brep">, string>>;
+export declare const FaceHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"face">, string>>;
+export declare const EdgeHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"edge">, string>>;
+export declare const HalfEdgeHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"halfedge">, string>>;
+export declare const VertexHandle: z.ZodPipe<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodString>, z.ZodTransform<Handle<"vertex">, string>>;
 export declare const Vec3Components: z.ZodObject<{
     x: z.ZodNumber;
     y: z.ZodNumber;

package/dist/handles.d.ts.map

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

package/dist/host-utils.d.ts

@@ -1,4 +1,5 @@
 import type { PluginApi } from "./api";
+import type { ErrorEnvelope } from "./errors";
 /**
  * UnionToIntersection is a type utility that converts a union type to an intersection type.
  */
@@ -37,7 +38,10 @@ export type PluginApiCallResult<M extends PluginApiMethod> = PluginApiMethodMap[
 export type PluginApiCallWrappedResult<M extends PluginApiMethod> = {
     success: boolean;
     data?: PluginApiCallResult<M>;
+    /** Legacy failure message — kept verbatim for already-published plugins. */
     error?: string;
+    /** Structured failure (hosts ≥ error-envelope rollout). Present iff `success` is false. */
+    errorInfo?: ErrorEnvelope;
 };
 export {};
 //# sourceMappingURL=host-utils.d.ts.map

package/dist/host-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../src/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC;;GAEG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAC7E,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAA;AAET,KAAK,OAAO,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1C;;;GAGG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;AAElE,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACzD,MAAM,CACJ,GAAG,MAAM,GAAG,CAAC,EAAE,EACf;QAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CACvD,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAC1C,KAAK;CACZ,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAInB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CACnD,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI;IAC9E,MAAM,EAAE,CAAC,CAAA;IACT,wEAAwE;IACxE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,eAAe,IACvD,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEjC,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,eAAe,IAAI;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAA"}
+{"version":3,"file":"host-utils.d.ts","sourceRoot":"","sources":["../src/host-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAI7C;;GAEG;AACH,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,GAAG,KAAK,CAAC,SAAS,CAC7E,CAAC,EAAE,MAAM,CAAC,KACP,IAAI,GACL,CAAC,GACD,KAAK,CAAA;AAET,KAAK,OAAO,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1C;;;GAGG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAA;AAElE,KAAK,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAA;AAE7E;;;GAGG;AACH,KAAK,kBAAkB,CAAC,CAAC,EAAE,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI;KACtD,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,GACzD,MAAM,CACJ,GAAG,MAAM,GAAG,CAAC,EAAE,EACf;QAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;KAAE,CACvD,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAC1C,KAAK;CACZ,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAA;AAInB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CACtC,mBAAmB,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CACnD,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAA;AAEtD,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI;IAC9E,MAAM,EAAE,CAAC,CAAA;IACT,wEAAwE;IACxE,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;CACpC,CAAA;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,eAAe,IACvD,kBAAkB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEjC,MAAM,MAAM,0BAA0B,CAAC,CAAC,SAAS,eAAe,IAAI;IAClE,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,SAAS,CAAC,EAAE,aAAa,CAAC;CAC3B,CAAA"}