@snaptrude/plugin-core 0.3.0 → 0.6.0

package/dist/api/core/groups.d.ts

@@ -0,0 +1,485 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+import { ComponentHandle } from "../../handles";
+/**
+ * Groups — read and edit the group hierarchy of the active project.
+ *
+ * A **group** is a named, lockable container that bundles components (and other
+ * groups) so they can be selected and transformed as one. This is the
+ * plugin-facing view of that hierarchy: a group's identity, name, member count,
+ * lock state, and parent — never the underlying meshes.
+ *
+ * Reads return plain records and never throw for a missing group (`get` returns
+ * `null`, `list` returns `[]`, `isLocked` returns `false`). Ids are stable public
+ * strings, never engine mesh handles.
+ *
+ * Members are moved and copied through the design operations by group id — use
+ * {@linkcode PluginDesignApi.transform}`.move` and `design.create.copy`, not a method here.
+ * Locking likewise routes through `design.lock`.
+ *
+ * Sub-namespace members typed as optional (`?`) are **authored ahead of the
+ * host** — declared so plugins and codegen can see the shape, but kept out of the
+ * discovery manifest until the host lands them (at which point they are promoted
+ * to required `abstract` members).
+ *
+ * Accessed via `snaptrude.core.groups`.
+ */
+export declare abstract class PluginCoreGroupsApi {
+    constructor();
+    /**
+     * List every group in the active project.
+     *
+     * Returns each group's identity, member count, lock state, and parent group
+     * (when nested), for the whole project.
+     *
+     * @returns A {@linkcode PluginCoreGroupsListResult} with a `groups` array
+     *   (empty when the project has none).
+     *
+     * @examplePrompt List all the groups in my project
+     * @examplePrompt What groups do I have and how many things are in each?
+     * @examplePrompt Show every group with its lock state
+     * @examplePrompt How many groups are in this model?
+     *
+     * # Example
+     * ```ts
+     * const { groups } = await snaptrude.core.groups.list()
+     * for (const g of groups) console.log(g.name, g.memberCount, g.isLocked)
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginCoreGroupsListResult>;
+    /**
+     * Get a single group by id.
+     *
+     * @param groupId - The id of the group to read.
+     * @returns The matching {@linkcode PluginCoreGroupRef}, or `null` if no group
+     *   has that id.
+     *
+     * @examplePrompt Get the group with id group-12
+     * @examplePrompt Look up a single group by its id
+     * @examplePrompt Is group-3 locked and how many members does it have?
+     *
+     * # Example
+     * ```ts
+     * const group = await snaptrude.core.groups.get("group-12")
+     * if (group) console.log(group.name, group.memberCount)
+     * ```
+     */
+    abstract get(groupId: string): PluginApiReturn<PluginCoreGroupsGetResult>;
+    /**
+     * Get the group a component belongs to.
+     *
+     * Returns the **innermost** group directly containing the component, or `null`
+     * if the component is ungrouped or does not exist.
+     *
+     * @param componentId - The `Component.id` of the component to look up.
+     * @returns The innermost {@linkcode PluginCoreGroupRef} containing the
+     *   component, or `null`.
+     *
+     * @examplePrompt Which group is this wall in?
+     * @examplePrompt Find the group that contains component cmp_42
+     * @examplePrompt Is this element grouped, and if so which group?
+     *
+     * # Example
+     * ```ts
+     * const group = await snaptrude.core.groups.getForComponent("cmp_42")
+     * console.log(group ? group.name : "ungrouped")
+     * ```
+     */
+    abstract getForComponent(componentId: ComponentHandle): PluginApiReturn<PluginCoreGroupsGetForComponentResult>;
+    /**
+     * List the direct members of a group.
+     *
+     * Returns each direct child as an id + kind (`component` or a nested `group`).
+     * Nested groups are returned as members, not flattened.
+     *
+     * @param groupId - The id of the group whose members to read.
+     * @returns A {@linkcode PluginCoreGroupsListMembersResult} with a `members`
+     *   array (empty when the group is empty or missing).
+     *
+     * @examplePrompt What's inside group-12?
+     * @examplePrompt List the members of this group
+     * @examplePrompt Show the components and subgroups in group-3
+     *
+     * # Example
+     * ```ts
+     * const { members } = await snaptrude.core.groups.listMembers("group-12")
+     * for (const m of members) console.log(m.type, m.id)
+     * ```
+     */
+    abstract listMembers(groupId: string): PluginApiReturn<PluginCoreGroupsListMembersResult>;
+    /**
+     * Report whether a group is locked.
+     *
+     * A predicate: it never mutates and never throws — an unknown group id returns
+     * `false`.
+     *
+     * @param groupId - The id of the group to test.
+     * @returns `true` if the group exists and is locked, otherwise `false`.
+     *
+     * @examplePrompt Is group-12 locked?
+     * @examplePrompt Check whether this group is locked before editing it
+     * @examplePrompt Tell me if the group is locked
+     *
+     * # Example
+     * ```ts
+     * if (await snaptrude.core.groups.isLocked("group-12")) {
+     *   console.log("locked — unlock it first")
+     * }
+     * ```
+     */
+    abstract isLocked(groupId: string): PluginApiReturn<PluginCoreGroupsIsLockedResult>;
+    /**
+     * Get the axis-aligned bounds of a group.
+     *
+     * Returns the world-space bounding box of everything in the group — its `min`
+     * and `max` corners and the `center` — in internal units, or `null` when the
+     * group is empty (has no meshes) or does not exist. `null` is distinct from a
+     * real group at the origin, whose box is centered on `{0,0,0}`.
+     *
+     * @param groupId - The id of the group to measure.
+     * @returns A {@linkcode PluginCoreGroupsGetBoundsResult} with `min`, `max`, and
+     *   `center` points, or `null` if the group is empty or gone.
+     *
+     * @examplePrompt How big is this group?
+     * @examplePrompt Get the bounding box of group-12
+     * @examplePrompt Where is the center of this group?
+     *
+     * # Example
+     * ```ts
+     * const bounds = await snaptrude.core.groups.getBounds("group-12")
+     * if (bounds) console.log(bounds.center.x, bounds.center.y, bounds.center.z)
+     * ```
+     */
+    abstract getBounds(groupId: string): PluginApiReturn<PluginCoreGroupsGetBoundsResult>;
+    /**
+     * Group components into a new group.
+     *
+     * Bundles the given components under a new group. Pass a `name` to label it;
+     * otherwise it gets an auto-generated fallback name that you can change later
+     * with {@linkcode PluginCoreGroupsApi.update}.
+     *
+     * @param componentIds - The ids of the components to group (at least one).
+     * @param name - Display name for the new group (auto-generated if omitted).
+     * @returns The new group's id (read the full record back with
+     *   {@linkcode PluginCoreGroupsApi.get}).
+     * @throws If a component id is invalid or the group could not be created.
+     *
+     * @examplePrompt Group the selected components
+     * @examplePrompt Make a group called Kitchen from these elements
+     * @examplePrompt Bundle components cmp_1 and cmp_2 into a group
+     *
+     * # Example
+     * ```ts
+     * const { groupId } = await snaptrude.core.groups.create(["cmp_1", "cmp_2"], "Kitchen")
+     * ```
+     */
+    abstract create(componentIds: ComponentHandle[], name?: string): PluginApiReturn<PluginCoreGroupsCreateResult>;
+    /**
+     * Update a group's name and/or membership.
+     *
+     * A **sparse** update: omitted fields are left unchanged. `addComponentIds`
+     * and `removeComponentIds` are applied as membership deltas (add before
+     * remove); `name` renames the group.
+     *
+     * @param groupId - The id of the group to update.
+     * @param options - Any of `name`, `addComponentIds`, `removeComponentIds`;
+     *   omitted fields are left unchanged.
+     * @returns The updated {@linkcode PluginCoreGroupRef}.
+     * @throws If no group has the given id, or a component id is invalid.
+     *
+     * @examplePrompt Rename group-12 to Kitchen
+     * @examplePrompt Add these two walls to the group
+     * @examplePrompt Remove cmp_7 from group-3
+     *
+     * # Example
+     * ```ts
+     * const group = await snaptrude.core.groups.update("group-12", {
+     *   name: "Kitchen",
+     *   addComponentIds: ["cmp_9"],
+     * })
+     * ```
+     */
+    abstract update(groupId: string, options?: {
+        name?: string;
+        addComponentIds?: ComponentHandle[];
+        removeComponentIds?: ComponentHandle[];
+    }): PluginApiReturn<PluginCoreGroupsUpdateResult>;
+    /**
+     * Delete (dissolve) a group.
+     *
+     * Dissolves the group container. The member elements are **not** deleted —
+     * they are returned to the group's parent (or ungrouped at the top level).
+     *
+     * @param groupId - The id of the group to dissolve.
+     * @returns Confirmation that the group was dissolved.
+     * @throws If no group has the given id.
+     *
+     * @examplePrompt Ungroup group-12
+     * @examplePrompt Dissolve this group but keep its contents
+     * @examplePrompt Delete the group without deleting its members
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.groups.delete("group-12")
+     * ```
+     */
+    abstract delete(groupId: string): PluginApiReturn<PluginCoreGroupsDeleteResult>;
+}
+/**
+ * A group in the active project.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable public group id (e.g. `"group-12"`) — never a mesh handle |
+ * | `name` | `string` | Display name (auto-generated fallback until the user sets one) |
+ * | `memberCount` | `number` | Number of direct members (components + nested groups) |
+ * | `isLocked` | `boolean` | Whether the group is locked against edits |
+ * | `parentId` | `string \| undefined` | Parent group id when this group is nested, else absent |
+ */
+export declare const PluginCoreGroupRef: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    memberCount: z.ZodNumber;
+    isLocked: z.ZodBoolean;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreGroupRef = z.infer<typeof PluginCoreGroupRef>;
+/**
+ * A direct member of a group.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | `Component.id` for a component member, or the group id for a nested group |
+ * | `type` | `"component" \| "group"` | Whether this member is a component or a nested group |
+ */
+export declare const PluginCoreGroupMember: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        component: "component";
+        group: "group";
+    }>;
+}, z.core.$strip>;
+export type PluginCoreGroupMember = z.infer<typeof PluginCoreGroupMember>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groups` | {@linkcode PluginCoreGroupRef}`[]` | Every group in the active project |
+ */
+export declare const PluginCoreGroupsListResult: z.ZodObject<{
+    groups: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        memberCount: z.ZodNumber;
+        isLocked: z.ZodBoolean;
+        parentId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreGroupsListResult = z.infer<typeof PluginCoreGroupsListResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group to read |
+ */
+export declare const PluginCoreGroupsGetArgs: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsGetArgs = z.infer<typeof PluginCoreGroupsGetArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.get} — the group, or `null` when no
+ * group has the given id.
+ */
+export declare const PluginCoreGroupsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    memberCount: z.ZodNumber;
+    isLocked: z.ZodBoolean;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginCoreGroupsGetResult = z.infer<typeof PluginCoreGroupsGetResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.getForComponent}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentId` | `ComponentHandle` | The `Component.id` to look up |
+ */
+export declare const PluginCoreGroupsGetForComponentArgs: z.ZodObject<{
+    componentId: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+}, z.core.$strip>;
+export type PluginCoreGroupsGetForComponentArgs = z.infer<typeof PluginCoreGroupsGetForComponentArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.getForComponent} — the innermost
+ * group containing the component, or `null`.
+ */
+export declare const PluginCoreGroupsGetForComponentResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    memberCount: z.ZodNumber;
+    isLocked: z.ZodBoolean;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type PluginCoreGroupsGetForComponentResult = z.infer<typeof PluginCoreGroupsGetForComponentResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group whose members to read |
+ */
+export declare const PluginCoreGroupsListMembersArgs: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsListMembersArgs = z.infer<typeof PluginCoreGroupsListMembersArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginCoreGroupMember}`[]` | The group's direct members (empty when the group is empty or missing) |
+ */
+export declare const PluginCoreGroupsListMembersResult: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodEnum<{
+            component: "component";
+            group: "group";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginCoreGroupsListMembersResult = z.infer<typeof PluginCoreGroupsListMembersResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.isLocked}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group to test |
+ */
+export declare const PluginCoreGroupsIsLockedArgs: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsIsLockedArgs = z.infer<typeof PluginCoreGroupsIsLockedArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.isLocked} — `true` when the group
+ * exists and is locked, else `false`.
+ */
+export declare const PluginCoreGroupsIsLockedResult: z.ZodBoolean;
+export type PluginCoreGroupsIsLockedResult = z.infer<typeof PluginCoreGroupsIsLockedResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.getBounds}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group to measure |
+ */
+export declare const PluginCoreGroupsGetBoundsArgs: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsGetBoundsArgs = z.infer<typeof PluginCoreGroupsGetBoundsArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.getBounds} — the group's world-space
+ * axis-aligned bounds in internal units, or `null` when the group is empty (has
+ * no meshes) or does not exist.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `min` | {@linkcode Vec3Components} | The minimum corner (`x`, `y`, `z`) |
+ * | `max` | {@linkcode Vec3Components} | The maximum corner (`x`, `y`, `z`) |
+ * | `center` | {@linkcode Vec3Components} | The box center (`x`, `y`, `z`) |
+ */
+export declare const PluginCoreGroupsGetBoundsResult: z.ZodNullable<z.ZodObject<{
+    min: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    max: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    center: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+export type PluginCoreGroupsGetBoundsResult = z.infer<typeof PluginCoreGroupsGetBoundsResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `componentIds` | `ComponentHandle[]` | The ids of the components to group (at least one) |
+ * | `name` | `string \| undefined` | Display name for the new group (auto-generated if omitted) |
+ */
+export declare const PluginCoreGroupsCreateArgs: z.ZodObject<{
+    componentIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreGroupsCreateArgs = z.infer<typeof PluginCoreGroupsCreateArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.create} — the id of the new group.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the newly created group |
+ */
+export declare const PluginCoreGroupsCreateResult: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsCreateResult = z.infer<typeof PluginCoreGroupsCreateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `addComponentIds` | `ComponentHandle[] \| undefined` | Components to add to the group |
+ * | `removeComponentIds` | `ComponentHandle[] \| undefined` | Components to remove from the group |
+ */
+export declare const PluginCoreGroupsUpdateArgs: z.ZodObject<{
+    groupId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    addComponentIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+    removeComponentIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>>>;
+}, z.core.$strip>;
+export type PluginCoreGroupsUpdateArgs = z.infer<typeof PluginCoreGroupsUpdateArgs>;
+/** Result of {@linkcode PluginCoreGroupsApi.update} — the updated group record. */
+export declare const PluginCoreGroupsUpdateResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    memberCount: z.ZodNumber;
+    isLocked: z.ZodBoolean;
+    parentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginCoreGroupsUpdateResult = z.infer<typeof PluginCoreGroupsUpdateResult>;
+/**
+ * Arguments for {@linkcode PluginCoreGroupsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | The id of the group to dissolve |
+ */
+export declare const PluginCoreGroupsDeleteArgs: z.ZodObject<{
+    groupId: z.ZodString;
+}, z.core.$strip>;
+export type PluginCoreGroupsDeleteArgs = z.infer<typeof PluginCoreGroupsDeleteArgs>;
+/**
+ * Result of {@linkcode PluginCoreGroupsApi.delete} — confirmation that the group
+ * was dissolved (its members are preserved).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `deleted` | `true` | Always `true` on success |
+ */
+export declare const PluginCoreGroupsDeleteResult: z.ZodObject<{
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type PluginCoreGroupsDeleteResult = z.infer<typeof PluginCoreGroupsDeleteResult>;
+//# sourceMappingURL=groups.d.ts.map

package/dist/api/core/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../../src/api/core/groups.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAA;AAE/D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAsB,mBAAmB;;IAGvC;;;;;;;;;;;;;;;;;;;OAmBG;aACa,IAAI,IAAI,eAAe,CAAC,0BAA0B,CAAC;IAEnE;;;;;;;;;;;;;;;;OAgBG;aACa,GAAG,CACjB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,yBAAyB,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;OAmBG;aACa,eAAe,CAC7B,WAAW,EAAE,eAAe,GAC3B,eAAe,CAAC,qCAAqC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,WAAW,CACzB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,iCAAiC,CAAC;IAErD;;;;;;;;;;;;;;;;;;;OAmBG;aACa,QAAQ,CACtB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,8BAA8B,CAAC;IAElD;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,SAAS,CACvB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,+BAA+B,CAAC;IAEnD;;;;;;;;;;;;;;;;;;;;;OAqBG;aACa,MAAM,CACpB,YAAY,EAAE,eAAe,EAAE,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;aACa,MAAM,CACpB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,eAAe,CAAC,EAAE,eAAe,EAAE,CAAA;QACnC,kBAAkB,CAAC,EAAE,eAAe,EAAE,CAAA;KACvC,GACA,eAAe,CAAC,4BAA4B,CAAC;IAEhD;;;;;;;;;;;;;;;;;;OAkBG;aACa,MAAM,CACpB,OAAO,EAAE,MAAM,GACd,eAAe,CAAC,4BAA4B,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;;;iBAM7B,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAEnE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;iBAGhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;iBAErC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;iBAElC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAE7E;;;GAGG;AACH,eAAO,MAAM,yBAAyB;;;;;;kBAAgC,CAAA;AACtE,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,yBAAyB,CACjC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mCAAmC;;iBAE9C,CAAA;AACF,MAAM,MAAM,mCAAmC,GAAG,CAAC,CAAC,KAAK,CACvD,OAAO,mCAAmC,CAC3C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qCAAqC;;;;;;kBACnB,CAAA;AAC/B,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,qCAAqC,CAC7C,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B;;iBAE1C,CAAA;AACF,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACnD,OAAO,+BAA+B,CACvC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;iBAE5C,CAAA;AACF,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CACrD,OAAO,iCAAiC,CACzC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B,cAAc,CAAA;AACzD,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;;iBAExC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,6BAA6B,CACrC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;kBAM/B,CAAA;AACb,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CACnD,OAAO,+BAA+B,CACvC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;iBAGrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,0BAA0B;;;;;iBAKrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED,mFAAmF;AACnF,eAAO,MAAM,4BAA4B;;;;;;iBAAqB,CAAA;AAC9D,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;iBAErC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA"}

package/dist/api/core/history/index.d.ts

@@ -0,0 +1,78 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../../types";
+/**
+ * Undo / redo of committed history entries.
+ *
+ * History steps operate on Snaptrude's command stack: {@linkcode PluginHistoryApi.undo}
+ * steps back over committed entries, {@linkcode PluginHistoryApi.redo} re-applies
+ * undone ones. Both take an optional step count (default 1) and report how many
+ * steps were actually applied — fewer than requested when the stack runs out.
+ *
+ * Accessed via `snaptrude.core.history`.
+ */
+export declare abstract class PluginHistoryApi {
+    constructor();
+    /**
+     * Step back over committed history entries.
+     *
+     * @param steps - (Optional) The number of entries to undo (default 1).
+     * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
+     *   entries actually undone (≤ `steps`; fewer if the undo stack ran out).
+     *
+     * @examplePrompt Undo my last change
+     * @examplePrompt Undo the last 3 actions
+     * @examplePrompt Revert what I just did to the model
+     * @examplePrompt Step back one change
+     * @examplePrompt Take back that last edit
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.history.undo()   // one step
+     * await snaptrude.core.history.undo(3)  // up to three steps
+     * ```
+     */
+    abstract undo(steps?: number): PluginApiReturn<PluginHistoryStepResult>;
+    /**
+     * Step forward over previously undone entries. Symmetric with
+     * {@linkcode PluginHistoryApi.undo}.
+     *
+     * @param steps - (Optional) The number of entries to redo (default 1).
+     * @returns A {@linkcode PluginHistoryStepResult} with `stepsApplied` — the
+     *   entries actually redone (≤ `steps`; fewer if the redo stack ran out).
+     *
+     * @examplePrompt Redo the change I just undid
+     * @examplePrompt Redo the last two undone actions
+     * @examplePrompt Bring back the edit I reverted
+     * @examplePrompt Step forward again in the history
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.core.history.redo()
+     * await snaptrude.core.history.redo(2)
+     * ```
+     */
+    abstract redo(steps?: number): PluginApiReturn<PluginHistoryStepResult>;
+}
+/**
+ * Arguments for {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `steps` | `number?` | Number of history entries to step (positive integer). Defaults to 1. |
+ */
+export declare const PluginHistoryStepArgs: z.ZodObject<{
+    steps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginHistoryStepArgs = z.infer<typeof PluginHistoryStepArgs>;
+/**
+ * Result of {@linkcode PluginHistoryApi.undo} / {@linkcode PluginHistoryApi.redo}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `stepsApplied` | `number` | History entries actually stepped — `≤ steps`, fewer when the stack ran out. |
+ */
+export declare const PluginHistoryStepResult: z.ZodObject<{
+    stepsApplied: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginHistoryStepResult = z.infer<typeof PluginHistoryStepResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/core/history/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/core/history/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;;;;;;;GASG;AACH,8BAAsB,gBAAgB;;IAGpC;;;;;;;;;;;;;;;;;;OAkBG;aACa,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,uBAAuB,CAAC;IAE9E;;;;;;;;;;;;;;;;;;OAkBG;aACa,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,uBAAuB,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;iBAEhC,CAAA;AAEF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;iBAElC,CAAA;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA"}

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

@@ -1,18 +1,68 @@
 import { PluginMathApi } from "./math";
 import { PluginGeomApi } from "./geom";
+import { PluginHistoryApi } from "./history";
+import { PluginUnitsApi } from "./units";
+import { PluginZoomApi } from "./zoom";
+import { PluginProjectApi } from "./project";
+import { PluginCommentApi } from "./comment";
+import { PluginCoreGroupsApi } from "./groups";
+import { PluginCoreBuildingsApi } from "./buildings";
+import { PluginCoreLayersApi } from "./layers";
+import { PluginCoreTagsApi } from "./tags";
+import { PluginCoreIoApi } from "./io";
 /**
- * Core primitives used across the plugin API.
+ * Core primitives and infrastructure used across the plugin API.
  *
  * - {@linkcode PluginCoreApi.math} — Vector and quaternion operations
  * - {@linkcode PluginCoreApi.geom} — Geometry primitives (lines, arcs, curves, profiles)
+ * - {@linkcode PluginCoreApi.history} — Undo / redo of committed history entries
+ * - {@linkcode PluginCoreApi.units} — Unit-type queries and conversion
+ * - {@linkcode PluginCoreApi.zoom} — Camera zoom controls (extents / selection)
+ * - {@linkcode PluginCoreApi.project} — Project-level settings and info
+ * - {@linkcode PluginCoreApi.comment} — Comments: create, edit, resolve, tag, list
+ * - {@linkcode PluginCoreApi.groups} — Read & edit the group hierarchy
+ * - {@linkcode PluginCoreApi.buildings} — Read & edit buildings and their storeys
+ * - {@linkcode PluginCoreApi.layers} — Read & toggle storey drawing/reference layers
+ * - {@linkcode PluginCoreApi.tags} — Tag catalog + assignment
+ * - {@linkcode PluginCoreApi.io} — Import files (image/pdf/cad/model/terrain), poll jobs, manage underlays
  */
 export declare abstract class PluginCoreApi {
     /** Vector and quaternion math utilities. See {@linkcode PluginMathApi}. */
     abstract math: PluginMathApi;
     /** Geometry primitives and constructors. See {@linkcode PluginGeomApi}. */
     abstract geom: PluginGeomApi;
+    /** Undo / redo of committed history entries. See {@linkcode PluginHistoryApi}. */
+    abstract history: PluginHistoryApi;
+    /** Unit-type queries and conversion. See {@linkcode PluginUnitsApi}. */
+    abstract units: PluginUnitsApi;
+    /** Camera zoom controls. See {@linkcode PluginZoomApi}. */
+    abstract zoom: PluginZoomApi;
+    /** Project-level settings and info. See {@linkcode PluginProjectApi}. */
+    abstract project: PluginProjectApi;
+    /** Comments — create, edit, resolve, tag, list. See {@linkcode PluginCommentApi}. */
+    abstract comment: PluginCommentApi;
+    /** Groups — read & edit the group hierarchy. See {@linkcode PluginCoreGroupsApi}. */
+    abstract groups: PluginCoreGroupsApi;
+    /** Buildings — read & edit buildings and their storeys. See {@linkcode PluginCoreBuildingsApi}. */
+    abstract buildings: PluginCoreBuildingsApi;
+    /** Layers — read & toggle storey drawing/reference layers. See {@linkcode PluginCoreLayersApi}. */
+    abstract layers: PluginCoreLayersApi;
+    /** Tags — tag catalog + assignment. See {@linkcode PluginCoreTagsApi}. */
+    abstract tags: PluginCoreTagsApi;
+    /** I/O — file import, import jobs, and underlay management. See {@linkcode PluginCoreIoApi}. */
+    abstract io: PluginCoreIoApi;
     constructor();
 }
 export * from "./math";
 export * from "./geom";
+export * from "./history";
+export * from "./units";
+export * from "./zoom";
+export * from "./project";
+export * from "./comment";
+export * from "./groups";
+export * from "./buildings";
+export * from "./layers";
+export * from "./tags";
+export * from "./io";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEtC;;;;;GAKG;AACH,8BAAsB,aAAa;IACjC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAA;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,MAAM,CAAA;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,8BAAsB,aAAa;IACjC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,2EAA2E;IAC3E,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,kFAAkF;IAClF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,wEAAwE;IACxE,SAAgB,KAAK,EAAE,cAAc,CAAA;IACrC,2DAA2D;IAC3D,SAAgB,IAAI,EAAE,aAAa,CAAA;IACnC,yEAAyE;IACzE,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,OAAO,EAAE,gBAAgB,CAAA;IACzC,qFAAqF;IACrF,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,mGAAmG;IACnG,SAAgB,SAAS,EAAE,sBAAsB,CAAA;IACjD,mGAAmG;IACnG,SAAgB,MAAM,EAAE,mBAAmB,CAAA;IAC3C,0EAA0E;IAC1E,SAAgB,IAAI,EAAE,iBAAiB,CAAA;IACvC,gGAAgG;IAChG,SAAgB,EAAE,EAAE,eAAe,CAAA;;CAGpC;AAED,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,QAAQ,CAAA;AACtB,cAAc,MAAM,CAAA"}