@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/handles.ts

@@ -0,0 +1,148 @@
+import * as z from "zod"
+
+/**
+ * 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.
+ */
+export type Handle<K extends string> = string & { readonly __handle: K }
+
+/**
+ * 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).
+ */
+export type EntityId<K extends string = string> = 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">
+
+// ── 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 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">
+
+// ── 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. 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.
+ */
+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>)
+
+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
+ * 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)
+
+// 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 CurveHandle = z.union([LineHandle, ArcHandle])
+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 })

package/src/host-utils.ts

@@ -0,0 +1,64 @@
+import type { PluginApi } from "./api"
+
+// -- Type Utilities for inferring method paths from the class hierarchy ------
+
+/**
+ * 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]
+
+// -- Plugin API method map ---------------------------------------------------
+
+/**
+ * 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>;
+  error?: string;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./api"
+export * from "./types"
+export * from "./host-utils"
+export * from "./handles"

package/src/types.ts

@@ -0,0 +1,16 @@
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string
+
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "bundler",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "typeRoots": [],
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup"
+
+export default defineConfig( (options) => {
+  return {
+    entry: ["src/index.ts"],
+    format: ["cjs", "esm"],
+    dts: false,
+    sourcemap: true,
+    onSuccess: "tsc", // Run tsc to generate d.ts and d.ts.map
+    watch: options.watch,
+  }
+})