@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261016.1

package/src/handles.ts

@@ -1,297 +1,297 @@
-import * as z from "zod"
-import type { ArenaKind } from "./api/core/handles"
-
-// Runtime polyfill: engines without explicit-resource-management would otherwise
-// evaluate the class's computed [Symbol.asyncDispose] key as undefined and
-// silently create a property literally named "undefined".
-;(Symbol as { asyncDispose?: symbol }).asyncDispose ??= Symbol.for("Symbol.asyncDispose")
-
-/**
- * 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 class Handle<K extends string> {
-  /** Phantom brand — keeps `Handle<"vec3">` ≠ `Handle<"mass">` at compile time. */
-  declare readonly __handle: K
-
-  constructor(readonly id: string) {}
-
-  /** Wire tag — the host's result serialization (JSON round-trip) calls this. */
-  toJSON(): { __h: string } {
-    return { __h: this.id }
-  }
-
-  /** Template-string / logging form stays the bare id. */
-  toString(): string {
-    return this.id
-  }
-
-  /** Identity comparison by id — safe across re-wraps. */
-  equals(other: Handle<string>): boolean {
-    return this.id === other.id
-  }
-
-  /**
-   * Explicit-resource-management hook (`await using`). A no-op here; the
-   * plugin-client runtime installs the real enqueue-release behavior on the
-   * interned instance.
-   */
-  async [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">
-
-// ── Value-kind handles (all-handle model, §11) ──────────────────────────────
-// Under the all-handle decision every structured type is a handle. The only
-// non-handles crossing the boundary are JS primitives (number/string/boolean)
-// and enums — the irreducible construction/read leaves. Value handles are
-// immutable; math/geom operate on them via host RPC (no in-worker compute).
-export type Vec3Handle = Handle<"vec3">
-export type QuatHandle = Handle<"quat">
-export type LineHandle = Handle<"line">
-export type ArcHandle = Handle<"arc">
-/**
- * A NURBS curve value handle (open B-spline curve). Minted by
- * `core.geom.create.splineFromPoints` / `splineFromControlPoints`, and returned by
- * `edge.getCurve`, `profile.listCurves` and `update.curve.reverse` for a spline run;
- * accepted everywhere a {@linkcode CurveHandle} is (profileFromCurves, query.curve.*).
- * Closed spline loops never exist as a single handle — a closed run is built
- * directly as a profile via `core.geom.create.profileFromSplinePoints`.
- */
-export type SplineHandle = Handle<"spline">
-/** A curve is a line, an arc, or a spline — its handle is one of those kinds. */
-export type CurveHandle = LineHandle | ArcHandle | SplineHandle
-/**
- * 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">
-
-// ── BREP topology handles (geometry-kernel resource family, §2A.2.1) ─────────
-// Session-ephemeral, identity-deduped RESOURCE handles for the boundary-
-// representation topology graph. Read-only via `core.geom.query.{brep,face,edge,
-// halfedge,vertex}`; they go stale on undo/redo/re-topologize. Obtain a brep via
-// `design.query.geometry.getBrep`; every other topology handle is minted by
-// walking from a brep/face/edge/vertex handle already resolved off that brep.
-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 const handleSchema = <K extends string>(kind: K) =>
-  z
-    .preprocess(
-      (v) => {
-        if (typeof v === "string") return v
-        if (v instanceof Handle) return v.id
-        if (v && typeof v === "object") {
-          const o = v as Record<string, unknown>
-          if (typeof o.__h === "string") return o.__h
-          if (typeof o.id === "string") return o.id
-        }
-        return v
-      },
-      z.string().regex(new RegExp(`^${kind}_[A-Za-z0-9_-]+$`), `expected a "${kind}" handle`)
-    )
-    .transform((s) => new Handle<K>(s))
-
-export const ProfileHandle = handleSchema("profile")
-export const ContourHandle = handleSchema("contour")
-
-/**
- * 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 const ComponentHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as ComponentHandle)
-
-/**
- * Material handles are the raw `Material.name` string (entity-style, no `"<kind>_"`
- * prefix) — validated only as non-empty, resolved live via `scene.getMaterialByName`.
- */
-export const MaterialHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as MaterialHandle)
-
-/**
- * {@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 const UnderlayHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as UnderlayHandle)
-export const TerrainHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as TerrainHandle)
-export const ImportJobHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as ImportJobHandle)
-
-/**
- * {@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 const DimensionHandle = z
-  .string()
-  .min(1)
-  .transform((s) => s as DimensionHandle)
-
-// Value-kind handle schemas (all-handle model, §11).
-export const Vec3Handle = handleSchema("vec3")
-export const QuatHandle = handleSchema("quat")
-export const LineHandle = handleSchema("line")
-export const ArcHandle = handleSchema("arc")
-export const SplineHandle = handleSchema("spline")
-// Explicitly typed (rather than inferred): the inferred union type prints its
-// three fully-expanded member schemas into handles.d.ts, which is served to
-// agents whole and has a size budget. ZodUnion (not ZodType) keeps `.options`.
-export const CurveHandle: z.ZodUnion<
-  readonly [typeof LineHandle, typeof ArcHandle, typeof SplineHandle]
-> = z.union([LineHandle, ArcHandle, SplineHandle])
-export const CircleHandle = handleSchema("circle")
-
-// BREP topology handle schemas (§2A.2.1). Prefix-shape validation only; existence,
-// kind, and ownership are enforced host-side by the HandleRegistry topology arena.
-export const BrepHandle = handleSchema("brep")
-export const FaceHandle = handleSchema("face")
-export const EdgeHandle = handleSchema("edge")
-export const HalfEdgeHandle = handleSchema("halfedge")
-export const VertexHandle = handleSchema("vertex")
-export const Vec3Components = z.object({ x: z.number(), y: z.number(), z: z.number() })
-export const QuatComponents = z.object({
-  x: z.number(),
-  y: z.number(),
-  z: z.number(),
-  w: z.number(),
-})
-export const BBoxComponents = z.object({ min: Vec3Components, max: Vec3Components })
+import * as z from "zod"
+import type { ArenaKind } from "./api/core/handles"
+
+// Runtime polyfill: engines without explicit-resource-management would otherwise
+// evaluate the class's computed [Symbol.asyncDispose] key as undefined and
+// silently create a property literally named "undefined".
+;(Symbol as { asyncDispose?: symbol }).asyncDispose ??= Symbol.for("Symbol.asyncDispose")
+
+/**
+ * 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 class Handle<K extends string> {
+  /** Phantom brand — keeps `Handle<"vec3">` ≠ `Handle<"mass">` at compile time. */
+  declare readonly __handle: K
+
+  constructor(readonly id: string) {}
+
+  /** Wire tag — the host's result serialization (JSON round-trip) calls this. */
+  toJSON(): { __h: string } {
+    return { __h: this.id }
+  }
+
+  /** Template-string / logging form stays the bare id. */
+  toString(): string {
+    return this.id
+  }
+
+  /** Identity comparison by id — safe across re-wraps. */
+  equals(other: Handle<string>): boolean {
+    return this.id === other.id
+  }
+
+  /**
+   * Explicit-resource-management hook (`await using`). A no-op here; the
+   * plugin-client runtime installs the real enqueue-release behavior on the
+   * interned instance.
+   */
+  async [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">
+
+// ── Value-kind handles (all-handle model, §11) ──────────────────────────────
+// Under the all-handle decision every structured type is a handle. The only
+// non-handles crossing the boundary are JS primitives (number/string/boolean)
+// and enums — the irreducible construction/read leaves. Value handles are
+// immutable; math/geom operate on them via host RPC (no in-worker compute).
+export type Vec3Handle = Handle<"vec3">
+export type QuatHandle = Handle<"quat">
+export type LineHandle = Handle<"line">
+export type ArcHandle = Handle<"arc">
+/**
+ * A NURBS curve value handle (open B-spline curve). Minted by
+ * `core.geom.create.splineFromPoints` / `splineFromControlPoints`, and returned by
+ * `edge.getCurve`, `profile.listCurves` and `update.curve.reverse` for a spline run;
+ * accepted everywhere a {@linkcode CurveHandle} is (profileFromCurves, query.curve.*).
+ * Closed spline loops never exist as a single handle — a closed run is built
+ * directly as a profile via `core.geom.create.profileFromSplinePoints`.
+ */
+export type SplineHandle = Handle<"spline">
+/** A curve is a line, an arc, or a spline — its handle is one of those kinds. */
+export type CurveHandle = LineHandle | ArcHandle | SplineHandle
+/**
+ * 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">
+
+// ── BREP topology handles (geometry-kernel resource family, §2A.2.1) ─────────
+// Session-ephemeral, identity-deduped RESOURCE handles for the boundary-
+// representation topology graph. Read-only via `core.geom.query.{brep,face,edge,
+// halfedge,vertex}`; they go stale on undo/redo/re-topologize. Obtain a brep via
+// `design.query.geometry.getBrep`; every other topology handle is minted by
+// walking from a brep/face/edge/vertex handle already resolved off that brep.
+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 const handleSchema = <K extends string>(kind: K) =>
+  z
+    .preprocess(
+      (v) => {
+        if (typeof v === "string") return v
+        if (v instanceof Handle) return v.id
+        if (v && typeof v === "object") {
+          const o = v as Record<string, unknown>
+          if (typeof o.__h === "string") return o.__h
+          if (typeof o.id === "string") return o.id
+        }
+        return v
+      },
+      z.string().regex(new RegExp(`^${kind}_[A-Za-z0-9_-]+$`), `expected a "${kind}" handle`)
+    )
+    .transform((s) => new Handle<K>(s))
+
+export const ProfileHandle = handleSchema("profile")
+export const ContourHandle = handleSchema("contour")
+
+/**
+ * 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 const ComponentHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as ComponentHandle)
+
+/**
+ * Material handles are the raw `Material.name` string (entity-style, no `"<kind>_"`
+ * prefix) — validated only as non-empty, resolved live via `scene.getMaterialByName`.
+ */
+export const MaterialHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as MaterialHandle)
+
+/**
+ * {@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 const UnderlayHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as UnderlayHandle)
+export const TerrainHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as TerrainHandle)
+export const ImportJobHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as ImportJobHandle)
+
+/**
+ * {@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 const DimensionHandle = z
+  .string()
+  .min(1)
+  .transform((s) => s as DimensionHandle)
+
+// Value-kind handle schemas (all-handle model, §11).
+export const Vec3Handle = handleSchema("vec3")
+export const QuatHandle = handleSchema("quat")
+export const LineHandle = handleSchema("line")
+export const ArcHandle = handleSchema("arc")
+export const SplineHandle = handleSchema("spline")
+// Explicitly typed (rather than inferred): the inferred union type prints its
+// three fully-expanded member schemas into handles.d.ts, which is served to
+// agents whole and has a size budget. ZodUnion (not ZodType) keeps `.options`.
+export const CurveHandle: z.ZodUnion<
+  readonly [typeof LineHandle, typeof ArcHandle, typeof SplineHandle]
+> = z.union([LineHandle, ArcHandle, SplineHandle])
+export const CircleHandle = handleSchema("circle")
+
+// BREP topology handle schemas (§2A.2.1). Prefix-shape validation only; existence,
+// kind, and ownership are enforced host-side by the HandleRegistry topology arena.
+export const BrepHandle = handleSchema("brep")
+export const FaceHandle = handleSchema("face")
+export const EdgeHandle = handleSchema("edge")
+export const HalfEdgeHandle = handleSchema("halfedge")
+export const VertexHandle = handleSchema("vertex")
+export const Vec3Components = z.object({ x: z.number(), y: z.number(), z: z.number() })
+export const QuatComponents = z.object({
+  x: z.number(),
+  y: z.number(),
+  z: z.number(),
+  w: z.number(),
+})
+export const BBoxComponents = z.object({ min: Vec3Components, max: Vec3Components })