@snaptrude/plugin-core 0.5.0 → 0.7.0

package/src/api/program/site.ts

@@ -127,6 +127,63 @@ export abstract class PluginProgramSiteApi {
    * ```
    */
   public abstract getContext(): PluginApiReturn<PluginProgramSiteContextResult>
+
+  /**
+   * Get the project's geographic location.
+   *
+   * The latitude/longitude the site is geo-located at — the location the
+   * `analysis.*` sun and daylight studies compute against. Returns `null`
+   * when the project is not geo-located on terrain (there is no fallback
+   * location).
+   *
+   * Note the spelling: this result uses the full `{ latitude, longitude }`
+   * keys, while the older site reads
+   * ({@linkcode PluginProgramSiteApi.getContext},
+   * {@linkcode PluginProgramSiteApi.listGeoPolygons}) use the abbreviated
+   * `{ lat, lng }`.
+   *
+   * @returns A {@linkcode PluginProgramSiteLocationResult} —
+   *   `{ latitude, longitude }`, or `null` when the project has no
+   *   geo-located site.
+   *
+   * @examplePrompt What's the project's latitude and longitude?
+   * @examplePrompt Where is this site located?
+   * @examplePrompt Get the geographic coordinates of the project
+   *
+   * # Example
+   * ```ts
+   * const location = await snaptrude.program.site.getLocation()
+   * if (location) console.log(location.latitude, location.longitude)
+   * ```
+   */
+  public abstract getLocation(): PluginApiReturn<PluginProgramSiteLocationResult>
+
+  /**
+   * Get the site's true-north angle.
+   *
+   * The angle in degrees the model's north (the scene's +Z axis) is rotated
+   * from true north, derived from the terrain's rotation. `0` means the
+   * model is aligned to true north. Reported in `[0, 360)`,
+   * **clockwise-positive** viewed from above (Babylon's +Y rotation sign) —
+   * note this is the opposite sign convention to `design.transform.rotate`,
+   * where positive = CCW. Returns `null` when the project is not
+   * geo-located on terrain.
+   *
+   * @returns A {@linkcode PluginProgramSiteNorthAngleResult} — the angle in
+   *   degrees (`[0, 360)`, clockwise-positive), or `null` when the project
+   *   has no geo-located site.
+   *
+   * @examplePrompt What's the north angle of the site?
+   * @examplePrompt How far is the model rotated from true north?
+   * @examplePrompt Get the project's true north direction
+   *
+   * # Example
+   * ```ts
+   * const northAngle = await snaptrude.program.site.getNorthAngle()
+   * if (northAngle !== null) console.log(`${northAngle}° from true north`)
+   * ```
+   */
+  public abstract getNorthAngle(): PluginApiReturn<PluginProgramSiteNorthAngleResult>
 }
 
 /**
@@ -324,3 +381,39 @@ export const PluginProgramSiteContextResult =
 export type PluginProgramSiteContextResult = z.infer<
   typeof PluginProgramSiteContextResult
 >
+
+/**
+ * The project's geographic location (WGS84).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `latitude` | `number` | Latitude (degrees) |
+ * | `longitude` | `number` | Longitude (degrees) |
+ */
+export const PluginProgramSiteLocation = z.object({
+  latitude: z.number(),
+  longitude: z.number(),
+})
+export type PluginProgramSiteLocation = z.infer<
+  typeof PluginProgramSiteLocation
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getLocation} — the location, or
+ * `null` when the project is not geo-located.
+ */
+export const PluginProgramSiteLocationResult =
+  PluginProgramSiteLocation.nullable()
+export type PluginProgramSiteLocationResult = z.infer<
+  typeof PluginProgramSiteLocationResult
+>
+
+/**
+ * Result of {@linkcode PluginProgramSiteApi.getNorthAngle} — the true-north
+ * angle in degrees (`[0, 360)`, clockwise-positive), or `null` when the
+ * project is not geo-located.
+ */
+export const PluginProgramSiteNorthAngleResult = z.number().nullable()
+export type PluginProgramSiteNorthAngleResult = z.infer<
+  typeof PluginProgramSiteNorthAngleResult
+>

package/src/errors/codes.ts

@@ -0,0 +1,136 @@
+/**
+ * The closed error-code registry — the single source of truth for every error
+ * that crosses the plugin wire (host → worker) or is minted client-side.
+ *
+ * APPEND-ONLY: codes are a published contract; never rename or remove one.
+ * Handle-resolution failures deliberately collapse to ONE code
+ * (`HANDLE_INVALID`) so error responses cannot be used as an existence /
+ * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6). `HANDLE_KIND_MISMATCH`
+ * stays distinct because the kind is information the caller already holds.
+ */
+export const PLUGIN_ERROR_CODES = [
+  "VALIDATION",
+  "INVALID_RPC_FORMAT",
+  "METHOD_NOT_FOUND",
+  "METHOD_NOT_PERMITTED",
+  "HANDLE_INVALID",
+  "HANDLE_KIND_MISMATCH",
+  "RESOURCE_QUOTA_EXCEEDED",
+  "RATE_LIMITED",
+  "PRECONDITION_FAILED",
+  "OPERATION_FAILED",
+  "TIMEOUT",
+  "CALL_TIMEOUT",
+  "TRANSPORT_LOST",
+  "PLUGIN_NOT_READY",
+  "PLUGIN_TERMINATED",
+  "RESULT_NOT_SERIALIZABLE",
+  "RESULT_TOO_LARGE",
+  "BATCH_PARTIAL",
+  "STORY_UPDATE_FAILED",
+  "STORY_HEIGHT_REJECTED",
+  "NO_ACTIVE_STRUCTURE",
+  "NO_ELIGIBLE_ELEMENTS",
+  "PROPOSAL_SWITCH_BLOCKED",
+  "INTERNAL",
+  "UNKNOWN",
+] as const
+
+export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number]
+
+/**
+ * A known code, or a string outside the union — a plugin built against an
+ * older SDK may receive codes a newer host appended. Keeps autocomplete for
+ * known codes while staying open on the wire (forward compatibility).
+ */
+export type WirePluginErrorCode = PluginErrorCode | (string & {})
+
+export type PluginErrorCategory =
+  | "validation"
+  | "not_found"
+  | "permission"
+  | "handle"
+  | "quota"
+  | "timeout"
+  | "transport"
+  | "lifecycle"
+  | "execution"
+  | "internal"
+
+/**
+ * Client-side metadata for a code. NOT carried on the wire — every field is a
+ * pure function of the code, and this table ships inside plugin-core, so both
+ * endpoints derive it locally.
+ */
+export interface CodeMeta {
+  /** Family of the code; picks the `PluginError` sugar subclass. */
+  category: PluginErrorCategory
+  /** Fallback `hint` when the throw site provides none. */
+  hintTemplate?: string
+}
+
+export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
+  VALIDATION: {
+    category: "validation",
+    hintTemplate: "Check details.issues for the failing argument.",
+  },
+  INVALID_RPC_FORMAT: { category: "validation" },
+  METHOD_NOT_FOUND: {
+    category: "not_found",
+    hintTemplate: "Check details.didYouMean for a close match.",
+  },
+  METHOD_NOT_PERMITTED: { category: "permission" },
+  HANDLE_INVALID: {
+    category: "handle",
+    hintTemplate: "Re-query the entity; do not cache handles across undo/reload.",
+  },
+  HANDLE_KIND_MISMATCH: { category: "handle" },
+  RESOURCE_QUOTA_EXCEEDED: {
+    category: "quota",
+    hintTemplate: "Release unused handles (core.handles.release) or use scopes.",
+  },
+  RATE_LIMITED: {
+    category: "quota",
+    hintTemplate: "Wait details.retryAfterMs before retrying.",
+  },
+  PRECONDITION_FAILED: { category: "execution" },
+  OPERATION_FAILED: { category: "execution" },
+  TIMEOUT: { category: "timeout" },
+  CALL_TIMEOUT: { category: "timeout" },
+  TRANSPORT_LOST: { category: "transport" },
+  PLUGIN_NOT_READY: { category: "lifecycle" },
+  PLUGIN_TERMINATED: { category: "lifecycle" },
+  RESULT_NOT_SERIALIZABLE: { category: "execution" },
+  RESULT_TOO_LARGE: { category: "execution" },
+  BATCH_PARTIAL: { category: "execution" },
+  STORY_UPDATE_FAILED: {
+    category: "execution",
+    hintTemplate: "The storey update could not be applied; re-read the storey and retry.",
+  },
+  STORY_HEIGHT_REJECTED: {
+    category: "execution",
+    hintTemplate: "The requested height was out of range; pick a value within the storey's limits.",
+  },
+  NO_ACTIVE_STRUCTURE: {
+    category: "execution",
+    hintTemplate: "Activate a structure before running this operation.",
+  },
+  NO_ELIGIBLE_ELEMENTS: {
+    category: "execution",
+    hintTemplate: "The storey has no elements eligible for this operation.",
+  },
+  PROPOSAL_SWITCH_BLOCKED: {
+    category: "execution",
+    hintTemplate: "Wait for the in-canvas agent run to finish, then retry.",
+  },
+  INTERNAL: {
+    category: "internal",
+    hintTemplate: "Host-side fault. Report with errorId.",
+  },
+  UNKNOWN: { category: "internal" },
+}
+
+/** Narrow an arbitrary string to a member of the closed code union. */
+export function isPluginErrorCode(value: string): value is PluginErrorCode {
+  return (PLUGIN_ERROR_CODES as readonly string[]).includes(value)
+}

package/src/errors/envelope.ts

@@ -0,0 +1,75 @@
+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 const ERROR_ENVELOPE_VERSION = 1 as const
+
+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 function isErrorEnvelope(value: unknown): value is ErrorEnvelope {
+  if (typeof value !== "object" || value === null) return false
+  const record = value as Record<string, unknown>
+  return (
+    record.envelopeVersion === ERROR_ENVELOPE_VERSION &&
+    typeof record.code === "string" &&
+    typeof record.message === "string" &&
+    typeof record.errorId === "string"
+  )
+}
+
+let idCounter = 0
+
+/**
+ * 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 function newErrorId(prefix = ""): string {
+  const cryptoApi = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto
+  if (cryptoApi?.randomUUID) return `${prefix}${cryptoApi.randomUUID()}`
+  idCounter += 1
+  return `${prefix}${Date.now().toString(36)}-${idCounter}-${Math.random().toString(36).slice(2, 10)}`
+}

package/src/errors/index.ts

@@ -0,0 +1,21 @@
+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"

package/src/errors/plugin-error.ts

@@ -0,0 +1,134 @@
+import { CODE_META, isPluginErrorCode } from "./codes"
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes"
+import { ERROR_ENVELOPE_VERSION, newErrorId } from "./envelope"
+import type { ErrorEnvelope } from "./envelope"
+
+/**
+ * Cross-copy brand: a plugin bundle may contain its OWN copy of this module,
+ * in which case `instanceof` fails across the two class identities.
+ * `Symbol.for` resolves to the same symbol in every copy within a realm, so
+ * `PluginError.is()` keeps working. Canonical check = `.is()` + `code`.
+ */
+const BRAND = Symbol.for("snaptrude.pluginError")
+
+interface Branded {
+  [BRAND]?: boolean
+}
+
+/**
+ * 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 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) {
+    super(envelope.message)
+    this.name = new.target.name
+    this.code = envelope.code
+    this.errorId = envelope.errorId
+    this.details = envelope.details
+    this.handle = envelope.handle
+    this.methodPath = envelope.methodPath
+    this.hint = envelope.hint ?? hintFor(envelope.code)
+    ;(this as Branded)[BRAND] = true
+  }
+
+  /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+  static is(value: unknown): value is PluginError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Branded)[BRAND] === true
+    )
+  }
+
+  /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+  get category(): PluginErrorCategory {
+    return isPluginErrorCode(this.code) ? CODE_META[this.code].category : "internal"
+  }
+}
+
+// Category sugar — same brand, so `PluginError.is()` matches all of them.
+// Convenience for single-SDK-copy plugins; docs teach `.is()` + `code`.
+export class PluginValidationError extends PluginError {}
+export class PluginNotFoundError extends PluginError {}
+export class PluginPermissionError extends PluginError {}
+export class PluginHandleError extends PluginError {}
+export class PluginQuotaError extends PluginError {}
+export class PluginTimeoutError extends PluginError {}
+export class PluginTransportError extends PluginError {}
+export class PluginLifecycleError extends PluginError {}
+export class PluginExecutionError extends PluginError {}
+export class PluginInternalError extends PluginError {}
+
+type PluginErrorConstructor = new (envelope: ErrorEnvelope) => PluginError
+
+const CATEGORY_CLASS: Record<PluginErrorCategory, PluginErrorConstructor> = {
+  validation: PluginValidationError,
+  not_found: PluginNotFoundError,
+  permission: PluginPermissionError,
+  handle: PluginHandleError,
+  quota: PluginQuotaError,
+  timeout: PluginTimeoutError,
+  transport: PluginTransportError,
+  lifecycle: PluginLifecycleError,
+  execution: PluginExecutionError,
+  internal: PluginInternalError,
+}
+
+function hintFor(code: WirePluginErrorCode): string | undefined {
+  return isPluginErrorCode(code) ? CODE_META[code].hintTemplate : undefined
+}
+
+/**
+ * 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 function fromEnvelope(envelope: ErrorEnvelope): PluginError {
+  if (!isPluginErrorCode(envelope.code)) return new PluginError(envelope)
+  const ErrorClass = CATEGORY_CLASS[CODE_META[envelope.code].category]
+  return new ErrorClass(envelope)
+}
+
+/**
+ * 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 function makeClientEnvelope(
+  code: PluginErrorCode,
+  message: string,
+  extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>
+): ErrorEnvelope {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code,
+    message,
+    errorId: newErrorId("c-"),
+    ...extra,
+  }
+}

package/src/handles.ts

@@ -46,6 +46,34 @@ export type ComponentHandle = EntityId<"component">
  */
 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 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)
@@ -123,6 +151,24 @@ export const MaterialHandle = z
   .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)
+
 // Value-kind handle schemas (all-handle model, §11).
 export const Vec3Handle = handleSchema("vec3")
 export const QuatHandle = handleSchema("quat")

package/src/host-utils.ts

@@ -1,4 +1,5 @@
 import type { PluginApi } from "./api"
+import type { ErrorEnvelope } from "./errors"
 
 // -- Type Utilities for inferring method paths from the class hierarchy ------
 
@@ -60,5 +61,8 @@ export type PluginApiCallResult<M extends PluginApiMethod> =
 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;
 }

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./api"
 export * from "./types"
 export * from "./host-utils"
 export * from "./handles"
+export * from "./errors"