@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/dist/api/workspace/index.d.ts

@@ -0,0 +1,505 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * `snaptrude.workspace.*` — the dashboard surface: projects and teams outside the
+ * open canvas.
+ *
+ * This namespace reads and creates the containers a design lives in — the
+ * project itself and the team it belongs to — mirroring the Snaptrude dashboard.
+ * Teams are **read-only** here (no create/invite/delete in v1, a deliberate
+ * safety decision); there are no folders in v1. A `projectId` is the project's
+ * floorkey. Plan limits are enforced by the backend — a limit rejection surfaces
+ * as a normal host error. It also carries the workspace-level mode switch for
+ * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
+ * {@linkcode PluginWorkspaceApi.closePresentMode}).
+ *
+ * - {@linkcode PluginWorkspaceApi.projects} — Create, copy, list, read & rename projects
+ * - {@linkcode PluginWorkspaceApi.teams} — Read teams and their members
+ * - {@linkcode PluginWorkspaceApi.openPresentMode} / {@linkcode PluginWorkspaceApi.closePresentMode} — Open/close the Present-mode documentation editor
+ */
+export declare abstract class PluginWorkspaceApi {
+    /** Projects — create, copy, list, read & rename. See {@linkcode PluginWorkspaceProjectsApi}. */
+    abstract projects: PluginWorkspaceProjectsApi;
+    /** Teams — read teams and their members. See {@linkcode PluginWorkspaceTeamsApi}. */
+    abstract teams: PluginWorkspaceTeamsApi;
+    /**
+     * Open Present mode — the documentation editor the `presentation.*`
+     * namespaces operate on.
+     *
+     * Switches the workspace into Present mode and resolves only once the
+     * Present canvas has finished mounting (waits up to ~15s; a mount that
+     * never completes is refused with a typed `PRECONDITION_FAILED`), so a
+     * `presentation.*` call issued right after this resolves finds Present
+     * mode open. Idempotent — resolves immediately when Present mode is
+     * already open. Write-gated: switching the mode under the user's feet is
+     * approval-controlled by design.
+     *
+     * @throws `PRECONDITION_FAILED` if the Present canvas does not mount within
+     *   the timeout.
+     *
+     * @examplePrompt Open present mode
+     * @examplePrompt Switch to the presentation editor
+     * @examplePrompt Open the sheets so I can lay out views
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.workspace.openPresentMode()
+     * const { sheets } = await snaptrude.presentation.sheets.list()
+     * ```
+     */
+    abstract openPresentMode(): PluginApiReturn<void>;
+    /**
+     * Close Present mode and return to the modeling canvas.
+     *
+     * Idempotent — a no-op when Present mode is not open. Write-gated, like
+     * {@linkcode PluginWorkspaceApi.openPresentMode}.
+     *
+     * @examplePrompt Close present mode
+     * @examplePrompt Exit the presentation editor
+     * @examplePrompt Go back to the modeling canvas
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.workspace.closePresentMode()
+     * ```
+     */
+    abstract closePresentMode(): PluginApiReturn<void>;
+    constructor();
+}
+/**
+ * `workspace.projects.*` — create, copy, list, read & rename projects.
+ *
+ * A **project** is a single Snaptrude model, identified by its `projectId`
+ * (floorkey). Reads never throw for a miss ({@linkcode PluginWorkspaceProjectsApi.get}
+ * returns `null`). Create/copy/rename go through the backend, which enforces plan
+ * limits — a rejection surfaces as a normal host error.
+ *
+ * Accessed via `snaptrude.workspace.projects`.
+ */
+export declare abstract class PluginWorkspaceProjectsApi {
+    constructor();
+    /**
+     * Create a new, empty BIM project.
+     *
+     * Creates the project on the backend and returns its `projectId` (floorkey).
+     * Pass `options.teamId` to create it inside a team (otherwise it lands in the
+     * user's personal workspace) and `options.unit` to set the default length unit.
+     *
+     * @param name - Display name of the new project.
+     * @param options - Optional `unit` (default length unit) and `teamId` (owning team).
+     * @returns The new project's `projectId`.
+     * @throws If the backend rejects the create (e.g. a plan project limit).
+     *
+     * @examplePrompt Create a new project called Tower Study
+     * @examplePrompt Start a new project in the Acme team
+     * @examplePrompt Make a fresh project using millimeters
+     * @examplePrompt Create an empty project for me to work in
+     *
+     * # Example
+     * ```ts
+     * const { projectId } = await snaptrude.workspace.projects.create("Tower Study", {
+     *   teamId: "team_1",
+     *   unit: "mm",
+     * })
+     * ```
+     */
+    abstract create(name: string, options?: {
+        unit?: string;
+        teamId?: string;
+    }): PluginApiReturn<PluginWorkspaceProjectsCreateResult>;
+    /**
+     * Copy the **current** project into a new project — the dashboard's "Save As".
+     *
+     * Duplicates the project that is currently open into a new project with the
+     * given name, and returns the new `projectId`. Pass `options.teamId` to place
+     * the copy in a specific team.
+     *
+     * @param name - Display name for the copy.
+     * @param options - Optional `teamId` (team to place the copy in).
+     * @returns The new project's `projectId`.
+     * @throws If the backend rejects the copy (e.g. a plan project limit).
+     *
+     * @examplePrompt Save this project as a new copy called Tower Study v2
+     * @examplePrompt Duplicate the current project into the Acme team
+     * @examplePrompt Make a copy of this project so I can try changes
+     *
+     * # Example
+     * ```ts
+     * const { projectId } = await snaptrude.workspace.projects.copy("Tower Study v2")
+     * ```
+     */
+    abstract copy(name: string, options?: {
+        teamId?: string;
+    }): PluginApiReturn<PluginWorkspaceProjectsCopyResult>;
+    /**
+     * List the projects the user can access.
+     *
+     * Returns a {@linkcode PluginProjectRef} per project. Pass `options.teamId` to
+     * scope the list to a single team; omit it for the user's accessible projects.
+     *
+     * @param options - Optional `teamId` filter.
+     * @returns A {@linkcode PluginWorkspaceProjectsListResult} with a `projects`
+     *   array (empty when there are none).
+     *
+     * @examplePrompt List all my projects
+     * @examplePrompt Show the projects in the Acme team
+     * @examplePrompt How many projects do I have?
+     * @examplePrompt What projects can I open?
+     *
+     * # Example
+     * ```ts
+     * const { projects } = await snaptrude.workspace.projects.list({ teamId: "team_1" })
+     * for (const p of projects) console.log(p.id, p.name)
+     * ```
+     */
+    abstract list(options?: {
+        teamId?: string;
+    }): PluginApiReturn<PluginWorkspaceProjectsListResult>;
+    /**
+     * Get a single project by id.
+     *
+     * @param projectId - The project's `projectId` (floorkey).
+     * @returns The matching {@linkcode PluginProjectRef}, or `null` if no project
+     *   has that id / the user cannot access it.
+     *
+     * @examplePrompt Get the project with this id
+     * @examplePrompt Look up a project by its floorkey
+     * @examplePrompt What is the name of this project?
+     *
+     * # Example
+     * ```ts
+     * const project = await snaptrude.workspace.projects.get("floorkey_123")
+     * if (project) console.log(project.name)
+     * ```
+     */
+    abstract get(projectId: string): PluginApiReturn<PluginWorkspaceProjectsGetResult>;
+    /**
+     * Rename a project.
+     *
+     * @param projectId - The project's `projectId` (floorkey).
+     * @param name - The project's new display name.
+     * @returns The renamed project's `projectId`.
+     * @throws If no project has the given id or the rename is rejected.
+     *
+     * @examplePrompt Rename this project to Tower Study Final
+     * @examplePrompt Change the name of project floorkey_123
+     * @examplePrompt Give this project a new name
+     *
+     * # Example
+     * ```ts
+     * const { projectId } = await snaptrude.workspace.projects.rename(
+     *   "floorkey_123",
+     *   "Tower Study Final",
+     * )
+     * ```
+     */
+    abstract rename(projectId: string, name: string): PluginApiReturn<PluginWorkspaceProjectsRenameResult>;
+}
+/**
+ * `workspace.teams.*` — read teams and their members.
+ *
+ * A **team** is a shared workspace that owns projects and members. **Read-only**
+ * in v1: there is no create/invite/delete (a deliberate safety decision). Reads
+ * never throw for a miss ({@linkcode PluginWorkspaceTeamsApi.get} returns `null`).
+ *
+ * Accessed via `snaptrude.workspace.teams`.
+ */
+export declare abstract class PluginWorkspaceTeamsApi {
+    constructor();
+    /**
+     * List the teams the user belongs to.
+     *
+     * @returns A {@linkcode PluginWorkspaceTeamsListResult} with a `teams` array
+     *   (empty when the user belongs to none).
+     *
+     * @examplePrompt List all my teams
+     * @examplePrompt Which teams am I a member of?
+     * @examplePrompt Show every team I can access
+     *
+     * # Example
+     * ```ts
+     * const { teams } = await snaptrude.workspace.teams.list()
+     * for (const t of teams) console.log(t.id, t.name)
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginWorkspaceTeamsListResult>;
+    /**
+     * Get a single team by id.
+     *
+     * @param teamId - The id of the team to read.
+     * @returns The matching {@linkcode PluginTeamRef}, or `null` if no team has that
+     *   id / the user is not a member.
+     *
+     * @examplePrompt Get the team with id team_1
+     * @examplePrompt Look up a team by its id
+     * @examplePrompt What is the name of this team?
+     *
+     * # Example
+     * ```ts
+     * const team = await snaptrude.workspace.teams.get("team_1")
+     * if (team) console.log(team.name)
+     * ```
+     */
+    abstract get(teamId: string): PluginApiReturn<PluginWorkspaceTeamsGetResult>;
+    /**
+     * List the members of a team.
+     *
+     * @param teamId - The id of the team whose members to list.
+     * @returns A {@linkcode PluginWorkspaceTeamsListMembersResult} with a `members`
+     *   array (empty when the team has none / is missing).
+     *
+     * @examplePrompt List the members of the Acme team
+     * @examplePrompt Who is on team_1?
+     * @examplePrompt How many people are in this team?
+     *
+     * # Example
+     * ```ts
+     * const { members } = await snaptrude.workspace.teams.listMembers("team_1")
+     * for (const m of members) console.log(m.name, m.email)
+     * ```
+     */
+    abstract listMembers(teamId: string): PluginApiReturn<PluginWorkspaceTeamsListMembersResult>;
+}
+/**
+ * A project reference — a conservative projection of a project, never the raw
+ * backend payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The project's `projectId` (floorkey) |
+ * | `name` | `string` | Display name |
+ * | `teamId` | `string?` | Owning team id (absent for personal projects) |
+ * | `createdAt` | `string?` | Creation timestamp (ISO 8601) when known |
+ * | `modifiedAt` | `string?` | Last-modified timestamp (ISO 8601) when known |
+ */
+export declare const PluginProjectRef: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    teamId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    modifiedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProjectRef = z.infer<typeof PluginProjectRef>;
+/**
+ * A team reference — a conservative projection of a team, never the raw backend
+ * payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable team id |
+ * | `name` | `string` | Display name |
+ * | `role` | `string?` | The user's role in the team when known |
+ */
+export declare const PluginTeamRef: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginTeamRef = z.infer<typeof PluginTeamRef>;
+/**
+ * A team member reference — a conservative projection of a member, never the raw
+ * backend payload.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable user id |
+ * | `name` | `string` | Display name |
+ * | `email` | `string?` | Email address when known |
+ * | `role` | `string?` | The member's role in the team when known |
+ */
+export declare const PluginTeamMemberRef: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginTeamMemberRef = z.infer<typeof PluginTeamMemberRef>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.create} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new project |
+ * | `unit` | `string?` | Default length unit |
+ * | `teamId` | `string?` | Owning team id (personal workspace if omitted) |
+ */
+export declare const PluginWorkspaceProjectsCreateArgs: z.ZodObject<{
+    name: z.ZodString;
+    unit: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsCreateArgs = z.infer<typeof PluginWorkspaceProjectsCreateArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the created project |
+ */
+export declare const PluginWorkspaceProjectsCreateResult: z.ZodObject<{
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsCreateResult = z.infer<typeof PluginWorkspaceProjectsCreateResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.copy} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name for the copy |
+ * | `teamId` | `string?` | Team to place the copy in |
+ */
+export declare const PluginWorkspaceProjectsCopyArgs: z.ZodObject<{
+    name: z.ZodString;
+    teamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsCopyArgs = z.infer<typeof PluginWorkspaceProjectsCopyArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.copy}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the copied project |
+ */
+export declare const PluginWorkspaceProjectsCopyResult: z.ZodObject<{
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsCopyResult = z.infer<typeof PluginWorkspaceProjectsCopyResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.list} (options flattened).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string?` | Scope the list to this team; omit for all accessible projects |
+ */
+export declare const PluginWorkspaceProjectsListArgs: z.ZodObject<{
+    teamId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsListArgs = z.infer<typeof PluginWorkspaceProjectsListArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projects` | {@linkcode PluginProjectRef}`[]` | Accessible projects (empty when none) |
+ */
+export declare const PluginWorkspaceProjectsListResult: z.ZodObject<{
+    projects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        teamId: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        modifiedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsListResult = z.infer<typeof PluginWorkspaceProjectsListResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The project's `projectId` (floorkey) |
+ */
+export declare const PluginWorkspaceProjectsGetArgs: z.ZodObject<{
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsGetArgs = z.infer<typeof PluginWorkspaceProjectsGetArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.get} — the project, or `null`
+ * when no project has the given id.
+ */
+export declare const PluginWorkspaceProjectsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    teamId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    modifiedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginWorkspaceProjectsGetResult = z.infer<typeof PluginWorkspaceProjectsGetResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceProjectsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The project's `projectId` (floorkey) |
+ * | `name` | `string` | The project's new display name |
+ */
+export declare const PluginWorkspaceProjectsRenameArgs: z.ZodObject<{
+    projectId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsRenameArgs = z.infer<typeof PluginWorkspaceProjectsRenameArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceProjectsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `projectId` | `string` | The id (floorkey) of the renamed project |
+ */
+export declare const PluginWorkspaceProjectsRenameResult: z.ZodObject<{
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceProjectsRenameResult = z.infer<typeof PluginWorkspaceProjectsRenameResult>;
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teams` | {@linkcode PluginTeamRef}`[]` | The user's teams (empty when none) |
+ */
+export declare const PluginWorkspaceTeamsListResult: z.ZodObject<{
+    teams: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginWorkspaceTeamsListResult = z.infer<typeof PluginWorkspaceTeamsListResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceTeamsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string` | The id of the team to read |
+ */
+export declare const PluginWorkspaceTeamsGetArgs: z.ZodObject<{
+    teamId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceTeamsGetArgs = z.infer<typeof PluginWorkspaceTeamsGetArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.get} — the team, or `null` when no
+ * team has the given id.
+ */
+export declare const PluginWorkspaceTeamsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginWorkspaceTeamsGetResult = z.infer<typeof PluginWorkspaceTeamsGetResult>;
+/**
+ * Arguments for {@linkcode PluginWorkspaceTeamsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `teamId` | `string` | The id of the team whose members to list |
+ */
+export declare const PluginWorkspaceTeamsListMembersArgs: z.ZodObject<{
+    teamId: z.ZodString;
+}, z.core.$strip>;
+export type PluginWorkspaceTeamsListMembersArgs = z.infer<typeof PluginWorkspaceTeamsListMembersArgs>;
+/**
+ * Result of {@linkcode PluginWorkspaceTeamsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginTeamMemberRef}`[]` | The team's members (empty when none) |
+ */
+export declare const PluginWorkspaceTeamsListMembersResult: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        role: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginWorkspaceTeamsListMembersResult = z.infer<typeof PluginWorkspaceTeamsListMembersResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/workspace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/workspace/index.ts"],"names":[],"mappings":"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"}

package/dist/errors/codes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const PLUGIN_ERROR_CODES: readonly ["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"];
+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 declare const CODE_META: Record<PluginErrorCode, CodeMeta>;
+/** Narrow an arbitrary string to a member of the closed code union. */
+export declare function isPluginErrorCode(value: string): value is PluginErrorCode;
+//# sourceMappingURL=codes.d.ts.map

package/dist/errors/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/errors/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,kgBA0BrB,CAAA;AAEV,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjE;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjE,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,CAAA;AAEd;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,kEAAkE;IAClE,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CA2DvD,CAAA;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE"}

package/dist/errors/envelope.d.ts

@@ -0,0 +1,56 @@
+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 declare const ERROR_ENVELOPE_VERSION: 1;
+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 declare function isErrorEnvelope(value: unknown): value is ErrorEnvelope;
+/**
+ * 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 declare function newErrorId(prefix?: string): string;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/errors/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/errors/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAElD;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAG,CAAU,CAAA;AAEhD,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,OAAO,sBAAsB,CAAA;IAC9C,IAAI,EAAE,mBAAmB,CAAA;IACzB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAStE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,SAAK,GAAG,MAAM,CAK9C"}

package/dist/errors/index.d.ts

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAC1E,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAElG,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAChF,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,GACnB,MAAM,gBAAgB,CAAA"}