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

package/src/api/core/math/vec3.ts

@@ -1,179 +1,179 @@
-import { PluginApiReturn } from "../../../types"
-import { Vec3Handle, Vec3Components } from "../../../handles"
-
-/**
- * 3D vector operations (all-handle model, §11).
- *
- * Vectors are opaque {@linkcode Vec3Handle}s; every operation is a host call
- * returning a new handle (vectors are immutable). Read primitive components back
- * with {@linkcode PluginVec3Api.components}. Accessed via `snaptrude.core.math.vec3`.
- */
-export abstract class PluginVec3Api {
-  constructor() {}
-
-  /**
-   * Create a vector from primitive components.
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(10, 0, 5)
-   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
-   * ```
-   */
-  abstract new(x: number, y: number, z: number): PluginApiReturn<Vec3Handle>
-  /**
-   * Add two vectors component-wise (`a + b`).
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
-   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const sum = await snaptrude.core.math.vec3.add(a, b)
-   * ```
-   */
-  abstract add(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
-  /**
-   * Subtract vector `b` from `a` component-wise (`a - b`).
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(3, 2, 1)
-   * const b = await snaptrude.core.math.vec3.new(1, 1, 1)
-   * const diff = await snaptrude.core.math.vec3.subtract(a, b)
-   * ```
-   */
-  abstract subtract(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
-  /**
-   * Scale `v` by a scalar.
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
-   * const doubled = await snaptrude.core.math.vec3.scale(v, 2)
-   * ```
-   */
-  abstract scale(v: Vec3Handle, scalar: number): PluginApiReturn<Vec3Handle>
-  /**
-   * Compute the dot product of two vectors.
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
-   * const b = await snaptrude.core.math.vec3.new(0.5, 0.5, 0)
-   * const d = await snaptrude.core.math.vec3.dot(a, b) // 0.5
-   * ```
-   */
-  abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
-  /**
-   * Compute the cross product `a × b` — the vector perpendicular to both.
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
-   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
-   * const perpendicular = await snaptrude.core.math.vec3.cross(a, b)
-   * ```
-   */
-  abstract cross(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
-  /**
-   * Compute the Euclidean length (magnitude) of a vector.
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
-   * const len = await snaptrude.core.math.vec3.length(v) // 5
-   * ```
-   */
-  abstract length(v: Vec3Handle): PluginApiReturn<number>
-  /**
-   * Compute the squared Euclidean length of a vector (avoids the sqrt).
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
-   * const sq = await snaptrude.core.math.vec3.lengthSquared(v) // 25
-   * ```
-   */
-  abstract lengthSquared(v: Vec3Handle): PluginApiReturn<number>
-  /**
-   * Return the unit vector in the same direction (the zero vector if length is 0).
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(0, 0, 10)
-   * const unit = await snaptrude.core.math.vec3.normalize(v) // (0, 0, 1)
-   * ```
-   */
-  abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>
-  /**
-   * Measure the straight-line (Euclidean) distance between two points.
-   *
-   * @examplePrompt What is the distance between these two points?
-   * @examplePrompt Measure how far apart these two points are
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const b = await snaptrude.core.math.vec3.new(3, 4, 0)
-   * const dist = await snaptrude.core.math.vec3.distance(a, b) // 5
-   * ```
-   */
-  abstract distance(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
-  /**
-   * Linearly interpolate between two vectors: `a + (b - a) * t`.
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
-   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
-   * const midpoint = await snaptrude.core.math.vec3.lerp(a, b, 0.5)
-   * ```
-   */
-  abstract lerp(a: Vec3Handle, b: Vec3Handle, t: number): PluginApiReturn<Vec3Handle>
-  /**
-   * Negate a vector, reversing its direction.
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(1, -2, 3)
-   * const reversed = await snaptrude.core.math.vec3.negate(v) // (-1, 2, -3)
-   * ```
-   */
-  abstract negate(v: Vec3Handle): PluginApiReturn<Vec3Handle>
-  /**
-   * Test whether two vectors have exactly equal components.
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
-   * const b = await snaptrude.core.math.vec3.new(1, 2, 3)
-   * const same = await snaptrude.core.math.vec3.equals(a, b) // true
-   * ```
-   */
-  abstract equals(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<boolean>
-  /**
-   * Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).
-   *
-   * # Example
-   * ```ts
-   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
-   * const b = await snaptrude.core.math.vec3.new(1.0004, 2, 3)
-   * const close = await snaptrude.core.math.vec3.equalsApprox(a, b, 1e-3) // true
-   * ```
-   */
-  abstract equalsApprox(
-    a: Vec3Handle,
-    b: Vec3Handle,
-    epsilon?: number,
-  ): PluginApiReturn<boolean>
-  /**
-   * Read the primitive `{ x, y, z }` components of a vector handle.
-   *
-   * # Example
-   * ```ts
-   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
-   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
-   * ```
-   */
-  abstract components(v: Vec3Handle): PluginApiReturn<Vec3Components>
-}
+import { PluginApiReturn } from "../../../types"
+import { Vec3Handle, Vec3Components } from "../../../handles"
+
+/**
+ * 3D vector operations (all-handle model, §11).
+ *
+ * Vectors are opaque {@linkcode Vec3Handle}s; every operation is a host call
+ * returning a new handle (vectors are immutable). Read primitive components back
+ * with {@linkcode PluginVec3Api.components}. Accessed via `snaptrude.core.math.vec3`.
+ */
+export abstract class PluginVec3Api {
+  constructor() {}
+
+  /**
+   * Create a vector from primitive components.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(10, 0, 5)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
+   * ```
+   */
+  abstract new(x: number, y: number, z: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Add two vectors component-wise (`a + b`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const sum = await snaptrude.core.math.vec3.add(a, b)
+   * ```
+   */
+  abstract add(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Subtract vector `b` from `a` component-wise (`a - b`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(3, 2, 1)
+   * const b = await snaptrude.core.math.vec3.new(1, 1, 1)
+   * const diff = await snaptrude.core.math.vec3.subtract(a, b)
+   * ```
+   */
+  abstract subtract(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Scale `v` by a scalar.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const doubled = await snaptrude.core.math.vec3.scale(v, 2)
+   * ```
+   */
+  abstract scale(v: Vec3Handle, scalar: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Compute the dot product of two vectors.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0.5, 0.5, 0)
+   * const d = await snaptrude.core.math.vec3.dot(a, b) // 0.5
+   * ```
+   */
+  abstract dot(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Compute the cross product `a × b` — the vector perpendicular to both.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(0, 1, 0)
+   * const perpendicular = await snaptrude.core.math.vec3.cross(a, b)
+   * ```
+   */
+  abstract cross(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Compute the Euclidean length (magnitude) of a vector.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const len = await snaptrude.core.math.vec3.length(v) // 5
+   * ```
+   */
+  abstract length(v: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Compute the squared Euclidean length of a vector (avoids the sqrt).
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const sq = await snaptrude.core.math.vec3.lengthSquared(v) // 25
+   * ```
+   */
+  abstract lengthSquared(v: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Return the unit vector in the same direction (the zero vector if length is 0).
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(0, 0, 10)
+   * const unit = await snaptrude.core.math.vec3.normalize(v) // (0, 0, 1)
+   * ```
+   */
+  abstract normalize(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Measure the straight-line (Euclidean) distance between two points.
+   *
+   * @examplePrompt What is the distance between these two points?
+   * @examplePrompt Measure how far apart these two points are
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(3, 4, 0)
+   * const dist = await snaptrude.core.math.vec3.distance(a, b) // 5
+   * ```
+   */
+  abstract distance(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<number>
+  /**
+   * Linearly interpolate between two vectors: `a + (b - a) * t`.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const b = await snaptrude.core.math.vec3.new(10, 0, 0)
+   * const midpoint = await snaptrude.core.math.vec3.lerp(a, b, 0.5)
+   * ```
+   */
+  abstract lerp(a: Vec3Handle, b: Vec3Handle, t: number): PluginApiReturn<Vec3Handle>
+  /**
+   * Negate a vector, reversing its direction.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, -2, 3)
+   * const reversed = await snaptrude.core.math.vec3.negate(v) // (-1, 2, -3)
+   * ```
+   */
+  abstract negate(v: Vec3Handle): PluginApiReturn<Vec3Handle>
+  /**
+   * Test whether two vectors have exactly equal components.
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const b = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const same = await snaptrude.core.math.vec3.equals(a, b) // true
+   * ```
+   */
+  abstract equals(a: Vec3Handle, b: Vec3Handle): PluginApiReturn<boolean>
+  /**
+   * Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).
+   *
+   * # Example
+   * ```ts
+   * const a = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const b = await snaptrude.core.math.vec3.new(1.0004, 2, 3)
+   * const close = await snaptrude.core.math.vec3.equalsApprox(a, b, 1e-3) // true
+   * ```
+   */
+  abstract equalsApprox(
+    a: Vec3Handle,
+    b: Vec3Handle,
+    epsilon?: number,
+  ): PluginApiReturn<boolean>
+  /**
+   * Read the primitive `{ x, y, z }` components of a vector handle.
+   *
+   * # Example
+   * ```ts
+   * const v = await snaptrude.core.math.vec3.new(1, 2, 3)
+   * const { x, y, z } = await snaptrude.core.math.vec3.components(v)
+   * ```
+   */
+  abstract components(v: Vec3Handle): PluginApiReturn<Vec3Components>
+}

package/src/api/core/mode/index.ts

@@ -1,108 +1,108 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-
-/**
- * The editor's top-bar application modes — the tabs a user switches between
- * while working on a project.
- */
-export const PluginAppMode = z.enum(["design", "bim", "present", "program"])
-export type PluginAppMode = z.infer<typeof PluginAppMode>
-
-export const PluginCoreModeSetArgs = z.object({
-  mode: PluginAppMode,
-})
-export type PluginCoreModeSetArgs = z.infer<typeof PluginCoreModeSetArgs>
-
-export interface PluginCoreModeListResult {
-  modes: PluginAppMode[]
-}
-
-export interface PluginCoreModeSetResult {
-  mode: PluginAppMode
-}
-
-/**
- * Application-mode control — read and switch the editor's top-bar mode
- * (Design, BIM, Present, Program), the same tabs a user clicks in the
- * top menu bar. Accessed via `snaptrude.core.mode`.
- *
- * Not to be confused with the viewport's 2D/3D camera mode
- * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
- *
- * `set` covers `design`, `bim`, and `present` — in-page switches — and
- * `program`, which opens the Program tab (a paired browser window) through the
- * same path as the top bar's Program button. Because the open happens outside a
- * user gesture the browser may block the pop-up; the editor then shows its
- * "Allow pop-up to continue" modal and the tab opens when the user confirms.
- * `get()` reports `"program"` only for code running in the Program tab itself.
- * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
- * the tab is ready before calling `program.spreadsheet.*`.
- */
-export abstract class PluginCoreModeApi {
-  constructor() {}
-
-  /**
-   * List every application mode the editor has.
-   *
-   * @returns The full set of mode tokens accepted by {@linkcode get} / {@linkcode set}.
-   *
-   * @examplePrompt What modes does Snaptrude have?
-   * @examplePrompt List the editor modes I can switch to
-   *
-   * # Example
-   * ```ts
-   * const { modes } = await snaptrude.core.mode.list()
-   * // ["design", "bim", "present", "program"]
-   * ```
-   */
-  public abstract list(): PluginApiReturn<PluginCoreModeListResult>
-
-  /**
-   * Get the currently active application mode.
-   *
-   * @returns The active mode token (e.g. `"design"`).
-   *
-   * @examplePrompt Which mode am I in right now?
-   * @examplePrompt Am I in present mode?
-   * @examplePrompt Check whether the editor is in BIM mode
-   *
-   * # Example
-   * ```ts
-   * const mode = await snaptrude.core.mode.get()
-   * if (mode !== "present") await snaptrude.core.mode.set("present")
-   * ```
-   */
-  public abstract get(): PluginApiReturn<PluginAppMode>
-
-  /**
-   * Switch the editor to another application mode — the same action as
-   * clicking that tab in the top menu bar.
-   *
-   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
-   * the Program tab (a paired browser window) exactly as the top bar's Program
-   * button does, and resolves once that tab has connected to the editor (up to
-   * ~90s — the browser may block the pop-up, in which case the editor shows an
-   * "Allow pop-up to continue" modal and waits for the user to confirm).
-   * Idempotent when the Program tab is already open. Note `get()` in the model
-   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
-   * a separate window.
-   *
-   * @param mode - Target mode token from {@linkcode PluginAppMode}
-   * @returns The committed `{ mode }` after the switch.
-   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
-   *   pop-up modal or the tab does not connect within the timeout.
-   *
-   * @examplePrompt Switch to present mode
-   * @examplePrompt Open BIM mode
-   * @examplePrompt Go back to design mode
-   * @examplePrompt Open program mode
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.core.mode.set("present")
-   * // ... presentation work ...
-   * await snaptrude.core.mode.set("design")
-   * ```
-   */
-  public abstract set(mode: PluginAppMode): PluginApiReturn<PluginCoreModeSetResult>
-}
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * The editor's top-bar application modes — the tabs a user switches between
+ * while working on a project.
+ */
+export const PluginAppMode = z.enum(["design", "bim", "present", "program"])
+export type PluginAppMode = z.infer<typeof PluginAppMode>
+
+export const PluginCoreModeSetArgs = z.object({
+  mode: PluginAppMode,
+})
+export type PluginCoreModeSetArgs = z.infer<typeof PluginCoreModeSetArgs>
+
+export interface PluginCoreModeListResult {
+  modes: PluginAppMode[]
+}
+
+export interface PluginCoreModeSetResult {
+  mode: PluginAppMode
+}
+
+/**
+ * Application-mode control — read and switch the editor's top-bar mode
+ * (Design, BIM, Present, Program), the same tabs a user clicks in the
+ * top menu bar. Accessed via `snaptrude.core.mode`.
+ *
+ * Not to be confused with the viewport's 2D/3D camera mode
+ * (`core.camera.setMode`) or saved presentation views (`presentation.views`).
+ *
+ * `set` covers `design`, `bim`, and `present` — in-page switches — and
+ * `program`, which opens the Program tab (a paired browser window) through the
+ * same path as the top bar's Program button. Because the open happens outside a
+ * user gesture the browser may block the pop-up; the editor then shows its
+ * "Allow pop-up to continue" modal and the tab opens when the user confirms.
+ * `get()` reports `"program"` only for code running in the Program tab itself.
+ * Prefer {@linkcode PluginWorkspaceApi.openProgramMode} when you need to know
+ * the tab is ready before calling `program.spreadsheet.*`.
+ */
+export abstract class PluginCoreModeApi {
+  constructor() {}
+
+  /**
+   * List every application mode the editor has.
+   *
+   * @returns The full set of mode tokens accepted by {@linkcode get} / {@linkcode set}.
+   *
+   * @examplePrompt What modes does Snaptrude have?
+   * @examplePrompt List the editor modes I can switch to
+   *
+   * # Example
+   * ```ts
+   * const { modes } = await snaptrude.core.mode.list()
+   * // ["design", "bim", "present", "program"]
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginCoreModeListResult>
+
+  /**
+   * Get the currently active application mode.
+   *
+   * @returns The active mode token (e.g. `"design"`).
+   *
+   * @examplePrompt Which mode am I in right now?
+   * @examplePrompt Am I in present mode?
+   * @examplePrompt Check whether the editor is in BIM mode
+   *
+   * # Example
+   * ```ts
+   * const mode = await snaptrude.core.mode.get()
+   * if (mode !== "present") await snaptrude.core.mode.set("present")
+   * ```
+   */
+  public abstract get(): PluginApiReturn<PluginAppMode>
+
+  /**
+   * Switch the editor to another application mode — the same action as
+   * clicking that tab in the top menu bar.
+   *
+   * `"design"`, `"bim"` and `"present"` switch in place. `"program"` opens
+   * the Program tab (a paired browser window) exactly as the top bar's Program
+   * button does, and resolves once that tab has connected to the editor (up to
+   * ~90s — the browser may block the pop-up, in which case the editor shows an
+   * "Allow pop-up to continue" modal and waits for the user to confirm).
+   * Idempotent when the Program tab is already open. Note `get()` in the model
+   * tab keeps reporting the model tab's own mode afterwards; the Program tab is
+   * a separate window.
+   *
+   * @param mode - Target mode token from {@linkcode PluginAppMode}
+   * @returns The committed `{ mode }` after the switch.
+   * @throws `PRECONDITION_FAILED` for `"program"` when the user dismisses the
+   *   pop-up modal or the tab does not connect within the timeout.
+   *
+   * @examplePrompt Switch to present mode
+   * @examplePrompt Open BIM mode
+   * @examplePrompt Go back to design mode
+   * @examplePrompt Open program mode
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.mode.set("present")
+   * // ... presentation work ...
+   * await snaptrude.core.mode.set("design")
+   * ```
+   */
+  public abstract set(mode: PluginAppMode): PluginApiReturn<PluginCoreModeSetResult>
+}