@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/dist/errors/envelope.d.ts

@@ -0,0 +1,56 @@
+import type { WirePluginErrorCode } from "./codes";
+/**
+ * Structured error payload carried on the `{success: false}` branch of the RPC
+ * wire result, next to the legacy `error: string` field (additive — old
+ * clients ignore it, old hosts never set it).
+ *
+ * Errors cross the worker boundary as THIS plain object, never as a thrown
+ * class: Comlink's throw transfer strips subclasses and custom fields and
+ * leaks host stacks. plugin-client reconstructs a typed `PluginError` from it
+ * (`fromEnvelope`).
+ */
+export declare const ERROR_ENVELOPE_VERSION: 1;
+export interface ErrorEnvelope {
+    envelopeVersion: typeof ERROR_ENVELOPE_VERSION;
+    code: WirePluginErrorCode;
+    /**
+     * Human-readable failure description. For INTERNAL/UNKNOWN this is a GENERIC
+     * message — the real message and stack stay host-side, logged under
+     * `errorId` (the worker is untrusted; internals must not leak).
+     */
+    message: string;
+    /**
+     * Per-occurrence id. For INTERNAL the host logs the real message and stack
+     * under this id (the sanitized message would otherwise be an undebuggable
+     * dead end). Other codes carry the id only to identify the occurrence in
+     * bug reports — the host does not log them. Client-minted ids carry a `c-`
+     * prefix.
+     */
+    errorId: string;
+    /** Structured, JSON-safe, code-specific data (issues / retryAfterMs / didYouMean / handles…). */
+    details?: Record<string, unknown>;
+    /**
+     * Wire id of the single primary offending handle, when the failure is
+     * handle-scoped. Multiple offenders go in `details.handles: string[]`.
+     * May echo ONLY ids the caller itself supplied (anti-oracle rule).
+     */
+    handle?: string;
+    /** Dotted method path of the failed call (e.g. "design.boolean.union"). */
+    methodPath?: string;
+    /** Machine-actionable fix suggestion (written for LLM plugin authors). */
+    hint?: string;
+}
+/**
+ * Structural guard for a wire value claiming to be an `ErrorEnvelope`.
+ *
+ * Checks shape only — deliberately does NOT reject codes outside the known
+ * union, so envelopes from a newer host still pass (forward compatibility).
+ */
+export declare function isErrorEnvelope(value: unknown): value is ErrorEnvelope;
+/**
+ * Mint a per-occurrence error id. Uses `crypto.randomUUID` when available
+ * (browser main thread and workers both have it); falls back to a
+ * counter+random suffix — uniqueness within a session is all that is needed.
+ */
+export declare function newErrorId(prefix?: string): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/errors/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/errors/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAElD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAA;AAEhD,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,OAAO,sBAAsB,CAAA;IAC9C,IAAI,EAAE,mBAAmB,CAAA;IACzB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAStE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAK,GAAG,MAAM,CAK9C"}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+export { PLUGIN_ERROR_CODES, CODE_META, isPluginErrorCode } from "./codes";
+export type { PluginErrorCode, WirePluginErrorCode, PluginErrorCategory, CodeMeta } from "./codes";
+export { ERROR_ENVELOPE_VERSION, isErrorEnvelope, newErrorId } from "./envelope";
+export type { ErrorEnvelope } from "./envelope";
+export { PluginError, PluginValidationError, PluginNotFoundError, PluginPermissionError, PluginHandleError, PluginQuotaError, PluginTimeoutError, PluginTransportError, PluginLifecycleError, PluginExecutionError, PluginInternalError, fromEnvelope, makeClientEnvelope, } from "./plugin-error";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC1E,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAElG,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAChF,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAA"}

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

@@ -0,0 +1,229 @@
+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.
+ *
+ * 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 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> = 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). */
+export type ContourHandle = Handle<"contour">;
+/** Entity-handle example: a Mass / space scene object (Component.id). */
+export type MassHandle = EntityId<"mass">;
+/**
+ * A scene BIM entity (wall, space, slab, floor, …). Backed by `Component.id` and
+ * resolved live via the host scene index (StructureCollection) — never stored in
+ * the resource registry. Stable across undo/redo and persistable (§9.2). This is
+ * the canonical return handle for every `design.create.*` creator. The token is
+ * the raw `Component.id` — NO `"component_"` prefix, so it round-trips with the
+ * ids the host already hands out.
+ */
+export type ComponentHandle = EntityId<"component">;
+/**
+ * A material handle. Like {@linkcode ComponentHandle}/`CommentHandle` this is an
+ * arena-free **entity-style** handle: the token IS the material's stable engine
+ * name (`Material.name`/`.id`), resolved live via `scene.getMaterialByName`
+ * host-side — no registry arena, no quota, no dispose, stable across undo/redo.
+ * 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 **dimension line** — one measurement annotation left behind by the Measuring
+ * Tape tool (NOT a width/height/depth property; see `design.dimensions`).
+ * Entity-style: the token IS the raw engine dimension id (`dim_…`), resolved live
+ * host-side from the dimension-line registry (`getDimensionLineMap()`) — not via
+ * `ComponentUtility.FindComponentById`, which does not index dimension lines (a
+ * dimension line is not a Component). No arena, no quota, stable across
+ * undo/redo and across reloads (the record persists with the project). Returned
+ * by `design.dimensions.create` and consumed by every other
+ * `design.dimensions.*` method.
+ */
+export type DimensionHandle = EntityId<"dimension">;
+/**
+ * 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">;
+export type ArcHandle = Handle<"arc">;
+/** A curve is a line or an arc — its handle is one of those kinds. */
+export type CurveHandle = LineHandle | ArcHandle;
+/**
+ * A circle value handle. A circle is a CLOSED curve — it deliberately does NOT
+ * join {@linkcode CurveHandle} (it has no stable start/end and would break the
+ * shared curve read contract), so it carries its own kind and its own
+ * `core.geom.query.circle` namespace (mirroring `query.arc`).
+ */
+export type CircleHandle = Handle<"circle">;
+export type BrepHandle = Handle<"brep">;
+export type FaceHandle = Handle<"face">;
+export type EdgeHandle = Handle<"edge">;
+/** Half-edge kind token is all-lowercase `"halfedge"` per §6.1 (no camelCase namespaces). */
+export type HalfEdgeHandle = Handle<"halfedge">;
+export type VertexHandle = Handle<"vertex">;
+/**
+ * Bare primitive records — how value-handle reads return their components
+ * (§11.4). Curves have **no** by-value record: a curve crosses the boundary as a
+ * {@linkcode CurveHandle} (line/arc), and its coordinates are read via the
+ * `core.geom.query.curve` API. There is no `CurveData` under the all-handle model.
+ */
+export type Vec3Components = {
+    x: number;
+    y: number;
+    z: number;
+};
+export type QuatComponents = {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+};
+/** Axis-aligned bounding box, read as two primitive corner records. */
+export type BBoxComponents = {
+    min: Vec3Components;
+    max: Vec3Components;
+};
+/**
+ * Build a Zod schema validating a handle of the given `kind` at the trust
+ * 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.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.
+ */
+export declare const ComponentHandle: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+/**
+ * Material handles are the raw `Material.name` string (entity-style, no `"<kind>_"`
+ * prefix) — validated only as non-empty, resolved live via `scene.getMaterialByName`.
+ */
+export declare const MaterialHandle: z.ZodPipe<z.ZodString, z.ZodTransform<MaterialHandle, 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>>;
+/**
+ * {@linkcode DimensionHandle} is an entity-style handle — the raw `dim_…` engine
+ * id, validated only as a non-empty string (no `"<kind>_"` prefix enforcement),
+ * resolved live host-side against the dimension-line registry (existence
+ * enforced there, as `HANDLE_INVALID`).
+ */
+export declare const DimensionHandle: z.ZodPipe<z.ZodString, z.ZodTransform<DimensionHandle, 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;
+    z: z.ZodNumber;
+}, z.core.$strip>;
+export declare const QuatComponents: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    z: z.ZodNumber;
+    w: z.ZodNumber;
+}, z.core.$strip>;
+export declare const BBoxComponents: z.ZodObject<{
+    min: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    max: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+//# sourceMappingURL=handles.d.ts.map

package/dist/handles.d.ts.map

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

package/dist/host-utils.d.ts

@@ -0,0 +1,47 @@
+import type { PluginApi } from "./api";
+import type { ErrorEnvelope } from "./errors";
+/**
+ * UnionToIntersection is a type utility that converts a union type to an intersection type.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type Flatten<T> = {
+    [K in keyof T]: T[K];
+};
+/**
+ * The full parameter tuple of a method — the positional-args transport forwards
+ * the whole argument list (`[]` for no-arg methods).
+ */
+type MethodArgs<F extends (...args: any[]) => any> = Parameters<F>;
+type MethodReturn<F extends (...args: any[]) => any> = Awaited<ReturnType<F>>;
+/**
+ * Recursively walks a type tree and produces a union of single-key Records
+ * for every leaf method, using dot-separated paths as keys.
+ */
+type ExtractMethodPaths<T, Prefix extends string = ""> = {
+    [K in keyof T & string]: T[K] extends (...args: any[]) => any ? Record<`${Prefix}${K}`, {
+        args: MethodArgs<T[K]>;
+        return: MethodReturn<T[K]>;
+    }> : T[K] extends object ? ExtractMethodPaths<T[K], `${Prefix}${K}.`> : never;
+}[keyof T & string];
+/**
+ * Maps every plugin API method path to its argument and return types.
+ * Automatically inferred from the PluginApi abstract class hierarchy.
+ */
+export type PluginApiMethodMap = Flatten<UnionToIntersection<ExtractMethodPaths<PluginApi>>>;
+export type PluginApiMethod = keyof PluginApiMethodMap;
+export type PluginApiCallPayload<M extends PluginApiMethod = PluginApiMethod> = {
+    method: M;
+    /** Positional argument tuple, spread back into the method host-side. */
+    args: PluginApiMethodMap[M]["args"];
+};
+export type PluginApiCallResult<M extends PluginApiMethod> = PluginApiMethodMap[M]["return"];
+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

@@ -0,0 +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;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"}