@snaptrude/plugin-core 0.7.0 → 0.8.0

package/src/handles.ts

@@ -1,22 +1,71 @@
 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.
  *
- * 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 & { readonly __handle: K }
+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> = 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">
@@ -119,19 +168,34 @@ export type BBoxComponents = { min: Vec3Components; max: Vec3Components }
 
 /**
  * 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 const handleSchema = <K extends string>(kind: K) =>
   z
-    .string()
-    .regex(new RegExp(`^${kind}_[A-Za-z0-9_-]+$`), `expected a "${kind}" handle`)
-    .transform((s) => s as Handle<K>)
+    .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")
-export const MassHandle = handleSchema("mass")
 
 /**
  * Entity handles are raw `Component.id` strings (no `"<kind>_"` prefix) — validated

package/tsconfig.json

@@ -3,7 +3,10 @@
     "target": "ES2020",
     "module": "ES2020",
     "moduleResolution": "bundler",
-    "lib": ["ES2020"],
+    "lib": [
+      "ES2020",
+      "ESNext.Disposable"
+    ],
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
@@ -13,5 +16,7 @@
     "declarationMap": true,
     "outDir": "dist"
   },
-  "include": ["src/**/*.ts"]
+  "include": [
+    "src/**/*.ts"
+  ]
 }