@snaptrude/plugin-core 0.7.1 → 0.8.0

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 (popup 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). */
@@ -108,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 popup-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.
@@ -134,17 +173,17 @@ export declare const MaterialHandle: z.ZodPipe<z.ZodString, z.ZodTransform<Mater
 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.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>>;
+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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"}