@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/dist/api/program/areas.d.ts

@@ -0,0 +1,360 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+import { ComponentHandle } from "../../handles";
+/**
+ * Program areas — the FAR / built-up-area rollup for the active program.
+ *
+ * This is the zoning-compliance lens on the model: carpet / built-up / excluded
+ * area totals, the site area, and the achieved-vs-target **FAR** (Floor Area
+ * Ratio). It complements {@linkcode PluginProgramMetricsApi}, which is the
+ * department-allocation lens (targets vs allocated area per department); this
+ * namespace is the whole-program area/FAR summary and its groupings.
+ *
+ * `achievedFar` is **derived and read-only** — computed from built-up area and
+ * site area. `targetFar` is the goal you set (via {@linkcode
+ * PluginProgramAreasApi.update}); the two are the same ratio, one measured and
+ * one intended. The surface speaks **FAR only** — there is no FSI alias.
+ *
+ * Reads return plain records and never throw. The write member typed as optional
+ * (`?`) is **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 it
+ * (at which point it is promoted to a required `abstract` member).
+ *
+ * Accessed via `snaptrude.program.areas`.
+ */
+export declare abstract class PluginProgramAreasApi {
+    constructor();
+    /**
+     * Get the program area summary.
+     *
+     * Returns the whole-program totals — carpet / built-up / excluded area, site
+     * area, and achieved vs target FAR — with the area unit they are reported in.
+     *
+     * @returns A {@linkcode PluginProgramAreaSummary}. `achievedFar` is `null` when
+     *   the site area or target FAR is not set.
+     *
+     * @examplePrompt What's my FAR right now?
+     * @examplePrompt Give me the program area summary
+     * @examplePrompt How much built-up area have I used against the site area?
+     * @examplePrompt Am I within my FAR target?
+     *
+     * # Example
+     * ```ts
+     * const s = await snaptrude.program.areas.get()
+     * console.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)
+     * ```
+     */
+    abstract get(): PluginApiReturn<PluginProgramAreasGetResult>;
+    /**
+     * List the program area rollup grouped by a facet.
+     *
+     * Breaks the program's area totals into buckets — by label, storey, building,
+     * department, or tag category.
+     *
+     * @param groupBy - The facet to group by (a {@linkcode PluginProgramAreaGroupBy}).
+     * @param categoryId - The tag category to group by (required when `groupBy` is
+     *   `"tagCategories"`).
+     * @returns A {@linkcode PluginProgramAreasListResult} with a `groups` array
+     *   (empty when the program has no spaces).
+     *
+     * @examplePrompt Break down the area by storey
+     * @examplePrompt Show the area rollup per department
+     * @examplePrompt Group the built-up area by building
+     *
+     * # Example
+     * ```ts
+     * const { groups } = await snaptrude.program.areas.list("storeys")
+     * for (const g of groups) console.log(g.name, g.builtUp, g.count)
+     * ```
+     */
+    abstract list(groupBy: PluginProgramAreaGroupBy, categoryId?: string): PluginApiReturn<PluginProgramAreasListResult>;
+    /**
+     * List the spaces that make up one area group.
+     *
+     * Drills into a single bucket returned by {@linkcode
+     * PluginProgramAreasApi.list} and returns its member spaces with their per-space
+     * area figures.
+     *
+     * @param groupBy - The same facet used to produce the group (a {@linkcode
+     *   PluginProgramAreaGroupBy}).
+     * @param groupId - The id of the group to expand.
+     * @param categoryId - The tag category context (required when `groupBy` is
+     *   `"tagCategories"`).
+     * @returns A {@linkcode PluginProgramAreasListMembersResult} with a `members`
+     *   array (empty when the group is missing or empty).
+     *
+     * @examplePrompt List the spaces on this storey with their areas
+     * @examplePrompt What rooms are in the Bedrooms department bucket?
+     * @examplePrompt Break the storey area down into individual spaces
+     *
+     * # Example
+     * ```ts
+     * const { members } = await snaptrude.program.areas.listMembers("storeys", "st_2")
+     * for (const m of members) console.log(m.label, m.carpet)
+     * ```
+     */
+    abstract listMembers(groupBy: PluginProgramAreaGroupBy, groupId: string, categoryId?: string): PluginApiReturn<PluginProgramAreasListMembersResult>;
+    /**
+     * Update the program's FAR settings.
+     *
+     * A **sparse** update of the program-level FAR inputs — target FAR, the site
+     * area, and the allowed deviation. This is a **non-undoable settings write**
+     * (persisted with the project). `achievedFar` recomputes from these.
+     *
+     * @param options - Any of `targetFar`, `siteArea`, `deviation`; omitted fields
+     *   are left unchanged.
+     * @returns The recomputed {@linkcode PluginProgramAreaSummary}.
+     * @throws If a value is out of range.
+     *
+     * @examplePrompt Set the target FAR to 2.5
+     * @examplePrompt Override the site area to 5000
+     * @examplePrompt Allow a 10 percent FAR deviation
+     *
+     * # Example
+     * ```ts
+     * const s = await snaptrude.program.areas.update({ targetFar: 2.5 })
+     * console.log(s.achievedFar, s.targetFar)
+     * ```
+     */
+    abstract update(options?: {
+        targetFar?: number;
+        siteArea?: number;
+        deviation?: number;
+    }): PluginApiReturn<PluginProgramAreasUpdateResult>;
+}
+/**
+ * The whole-program area / FAR summary. All area figures are in `areaUnit`;
+ * ratios (`achievedFar`, `targetFar`, `deviation`) are unitless.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `count` | `number` | Number of spaces in the program (a count, not an area) |
+ * | `hiddenCount` | `number` | Number of those spaces that are currently hidden |
+ * | `carpet` | `number` | Total carpet area in `areaUnit` |
+ * | `builtUp` | `number` | Total built-up area in `areaUnit` |
+ * | `excluded` | `number` | Total excluded area in `areaUnit` |
+ * | `farBuiltUp` | `number` | Built-up area that counts toward FAR, in `areaUnit` |
+ * | `siteArea` | `number` | Site/plot area in `areaUnit` |
+ * | `achievedFar` | `number \| null` | Derived FAR (`farBuiltUp / siteArea`); `null` when site area or target FAR is unset |
+ * | `targetFar` | `number` | The target FAR goal (set via `update`) |
+ * | `deviation` | `number` | Allowed FAR deviation, as a percentage |
+ * | `areaUnit` | `"ft2" \| "m2"` | The unit every area figure above is reported in |
+ */
+export declare const PluginProgramAreaSummary: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreaSummary = z.infer<typeof PluginProgramAreaSummary>;
+/**
+ * One bucket of the area rollup. Carpet / built-up / excluded figures are in the
+ * program's area unit (see {@linkcode PluginProgramAreaSummary.areaUnit});
+ * `targetArea` is in `targetUnit`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupId` | `string` | Stable id of the group (e.g. storey id, department id) |
+ * | `name` | `string` | Display name of the group |
+ * | `color` | `string` | CSS hex color string for the group |
+ * | `carpet` | `number` | Carpet area for this group |
+ * | `builtUp` | `number` | Built-up area for this group |
+ * | `excluded` | `number` | Excluded area for this group |
+ * | `count` | `number` | Number of spaces in this group |
+ * | `targetArea` | `number` | Target area for this group, in `targetUnit` |
+ * | `targetUnit` | `"ft2" \| "m2"` | The unit `targetArea` is reported in |
+ */
+export declare const PluginProgramAreaGroup: z.ZodObject<{
+    groupId: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    count: z.ZodNumber;
+    targetArea: z.ZodNumber;
+    targetUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreaGroup = z.infer<typeof PluginProgramAreaGroup>;
+/**
+ * A single space within an area group. Area figures are in the program's area
+ * unit (see {@linkcode PluginProgramAreaSummary.areaUnit}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `ComponentHandle` | `Component.id` of the space (never a mesh handle) |
+ * | `label` | `string` | Display label of the space |
+ * | `carpet` | `number` | Carpet area of the space |
+ * | `builtUp` | `number` | Built-up area of the space |
+ * | `excluded` | `number` | Excluded area of the space |
+ * | `isVisible` | `boolean` | Whether the space is currently visible |
+ */
+export declare const PluginProgramAreaMember: z.ZodObject<{
+    id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+    label: z.ZodString;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    isVisible: z.ZodBoolean;
+}, z.core.$strip>;
+export type PluginProgramAreaMember = z.infer<typeof PluginProgramAreaMember>;
+/** The facet to group the area rollup by. */
+export declare const PluginProgramAreaGroupBy: z.ZodEnum<{
+    buildings: "buildings";
+    storeys: "storeys";
+    departments: "departments";
+    labels: "labels";
+    tagCategories: "tagCategories";
+}>;
+export type PluginProgramAreaGroupBy = z.infer<typeof PluginProgramAreaGroupBy>;
+/** Result of {@linkcode PluginProgramAreasApi.get} — the program area summary. */
+export declare const PluginProgramAreasGetResult: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreasGetResult = z.infer<typeof PluginProgramAreasGetResult>;
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet to group by |
+ * | `categoryId` | `string \| undefined` | Tag category to group by; required when `groupBy` is `"tagCategories"` |
+ */
+export declare const PluginProgramAreasListArgs: z.ZodObject<{
+    groupBy: z.ZodEnum<{
+        buildings: "buildings";
+        storeys: "storeys";
+        departments: "departments";
+        labels: "labels";
+        tagCategories: "tagCategories";
+    }>;
+    categoryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramAreasListArgs = z.infer<typeof PluginProgramAreasListArgs>;
+/**
+ * Result of {@linkcode PluginProgramAreasApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groups` | {@linkcode PluginProgramAreaGroup}`[]` | The area buckets (empty when the program has no spaces) |
+ */
+export declare const PluginProgramAreasListResult: z.ZodObject<{
+    groups: z.ZodArray<z.ZodObject<{
+        groupId: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodString;
+        carpet: z.ZodNumber;
+        builtUp: z.ZodNumber;
+        excluded: z.ZodNumber;
+        count: z.ZodNumber;
+        targetArea: z.ZodNumber;
+        targetUnit: z.ZodEnum<{
+            ft2: "ft2";
+            m2: "m2";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramAreasListResult = z.infer<typeof PluginProgramAreasListResult>;
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `groupBy` | {@linkcode PluginProgramAreaGroupBy} | The facet the group came from |
+ * | `groupId` | `string` | The id of the group to expand |
+ * | `categoryId` | `string \| undefined` | Tag category context; required when `groupBy` is `"tagCategories"` |
+ */
+export declare const PluginProgramAreasListMembersArgs: z.ZodObject<{
+    groupBy: z.ZodEnum<{
+        buildings: "buildings";
+        storeys: "storeys";
+        departments: "departments";
+        labels: "labels";
+        tagCategories: "tagCategories";
+    }>;
+    groupId: z.ZodString;
+    categoryId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramAreasListMembersArgs = z.infer<typeof PluginProgramAreasListMembersArgs>;
+/**
+ * Result of {@linkcode PluginProgramAreasApi.listMembers}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `members` | {@linkcode PluginProgramAreaMember}`[]` | The group's member spaces (empty when missing or empty) |
+ */
+export declare const PluginProgramAreasListMembersResult: z.ZodObject<{
+    members: z.ZodArray<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<ComponentHandle, string>>;
+        label: z.ZodString;
+        carpet: z.ZodNumber;
+        builtUp: z.ZodNumber;
+        excluded: z.ZodNumber;
+        isVisible: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramAreasListMembersResult = z.infer<typeof PluginProgramAreasListMembersResult>;
+/**
+ * Arguments for {@linkcode PluginProgramAreasApi.update}. Sparse — only the
+ * provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `targetFar` | `number \| undefined` | New target FAR (≥ 0) |
+ * | `siteArea` | `number \| undefined` | Site-area override (> 0), in the program's area unit |
+ * | `deviation` | `number \| undefined` | Allowed FAR deviation percentage (0–100) |
+ */
+export declare const PluginProgramAreasUpdateArgs: z.ZodObject<{
+    targetFar: z.ZodOptional<z.ZodNumber>;
+    siteArea: z.ZodOptional<z.ZodNumber>;
+    deviation: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramAreasUpdateArgs = z.infer<typeof PluginProgramAreasUpdateArgs>;
+/**
+ * Result of {@linkcode PluginProgramAreasApi.update} — the recomputed program
+ * area summary.
+ */
+export declare const PluginProgramAreasUpdateResult: z.ZodObject<{
+    count: z.ZodNumber;
+    hiddenCount: z.ZodNumber;
+    carpet: z.ZodNumber;
+    builtUp: z.ZodNumber;
+    excluded: z.ZodNumber;
+    farBuiltUp: z.ZodNumber;
+    siteArea: z.ZodNumber;
+    achievedFar: z.ZodNullable<z.ZodNumber>;
+    targetFar: z.ZodNumber;
+    deviation: z.ZodNumber;
+    areaUnit: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramAreasUpdateResult = z.infer<typeof PluginProgramAreasUpdateResult>;
+//# sourceMappingURL=areas.d.ts.map

package/dist/api/program/areas.d.ts.map

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

package/dist/api/program/classification.d.ts

@@ -0,0 +1,135 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program classification — the catalog of space-classification options, and a
+ * space's display tags.
+ *
+ * Only the genuinely program-specific reads live here: the selectable
+ * space-type / area-class / mass-type options, and a space's tags for display.
+ * Reading or changing a *single space's* classification (its type, label, area
+ * class, or department) is done through the space reads/writes, not duplicated
+ * here. Tag definitions are managed elsewhere — these methods are display-only.
+ *
+ * Both methods are reads.
+ *
+ * Accessed via `snaptrude.program.classification`.
+ */
+export declare abstract class PluginProgramClassificationApi {
+    constructor();
+    /**
+     * List the selectable classification options for spaces.
+     *
+     * The static catalog (project-independent) of space types, area classes, and
+     * mass types a space can be classified as.
+     *
+     * @returns A {@linkcode PluginProgramClassificationTypesResult} with the
+     *   `spaceTypes`, `areaClasses`, and `massTypes` option lists.
+     *
+     * @examplePrompt What space types can I assign?
+     * @examplePrompt List the available area classifications
+     * @examplePrompt What classification options exist?
+     * @examplePrompt Show me the valid space-type values
+     *
+     * # Example
+     * ```ts
+     * const { spaceTypes, areaClasses } = await snaptrude.program.classification.listTypes()
+     * ```
+     */
+    abstract listTypes(): PluginApiReturn<PluginProgramClassificationTypesResult>;
+    /**
+     * List a space's tags for display, grouped by category.
+     *
+     * @param id - The id of the space whose tags to read.
+     * @returns A {@linkcode PluginProgramClassificationTagsResult} with the space's
+     *   `tagIds` and `tagsByCategory`.
+     *
+     * @examplePrompt What tags are on this space?
+     * @examplePrompt Show the tags grouped by category for sp_4
+     * @examplePrompt List this room's display tags
+     * @examplePrompt Which tags does this space have?
+     *
+     * # Example
+     * ```ts
+     * const { tagsByCategory } = await snaptrude.program.classification.listTags("sp_4")
+     * ```
+     */
+    abstract listTags(id: string): PluginApiReturn<PluginProgramClassificationTagsResult>;
+}
+/**
+ * A selectable classification option.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `string` | Stored value |
+ * | `label` | `string` | Display label |
+ */
+export declare const PluginClassificationOption: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type PluginClassificationOption = z.infer<typeof PluginClassificationOption>;
+/**
+ * Result of {@linkcode PluginProgramClassificationApi.listTypes}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceTypes` | {@linkcode PluginClassificationOption}`[]` | Selectable space types |
+ * | `areaClasses` | {@linkcode PluginClassificationOption}`[]` | Selectable area classes (NET/GROSS/EXCLUDED) |
+ * | `massTypes` | {@linkcode PluginClassificationOption}`[]` | Selectable mass/object types |
+ */
+export declare const PluginProgramClassificationTypesResult: z.ZodObject<{
+    spaceTypes: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    areaClasses: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    massTypes: z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramClassificationTypesResult = z.infer<typeof PluginProgramClassificationTypesResult>;
+/** Arguments for {@linkcode PluginProgramClassificationApi.listTags}. */
+export declare const PluginProgramClassificationListTagsArgs: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramClassificationListTagsArgs = z.infer<typeof PluginProgramClassificationListTagsArgs>;
+/**
+ * A display tag on a space.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagId` | `string` | Tag id |
+ * | `tagName` | `string` | Tag display name |
+ * | `color` | `string` | CSS hex color string |
+ * | `categoryId` | `string` | Id of the tag's category |
+ */
+export declare const PluginSpaceTag: z.ZodObject<{
+    tagId: z.ZodString;
+    tagName: z.ZodString;
+    color: z.ZodString;
+    categoryId: z.ZodString;
+}, z.core.$strip>;
+export type PluginSpaceTag = z.infer<typeof PluginSpaceTag>;
+/**
+ * Result of {@linkcode PluginProgramClassificationApi.listTags}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `tagIds` | `string[]` | All tag ids on the space |
+ * | `tagsByCategory` | `Record<string, `{@linkcode PluginSpaceTag}`>` | Tags keyed by category name |
+ */
+export declare const PluginProgramClassificationTagsResult: z.ZodObject<{
+    tagIds: z.ZodArray<z.ZodString>;
+    tagsByCategory: z.ZodRecord<z.ZodString, z.ZodObject<{
+        tagId: z.ZodString;
+        tagName: z.ZodString;
+        color: z.ZodString;
+        categoryId: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramClassificationTagsResult = z.infer<typeof PluginProgramClassificationTagsResult>;
+//# sourceMappingURL=classification.d.ts.map

package/dist/api/program/classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.ts","sourceRoot":"","sources":["../../../src/api/program/classification.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;GAaG;AACH,8BAAsB,8BAA8B;;IAGlD;;;;;;;;;;;;;;;;;;OAkBG;aACa,SAAS,IAAI,eAAe,CAAC,sCAAsC,CAAC;IAEpF;;;;;;;;;;;;;;;;OAgBG;aACa,QAAQ,CACtB,EAAE,EAAE,MAAM,GACT,eAAe,CAAC,qCAAqC,CAAC;CAC1D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;;iBAGrC,CAAA;AACF,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAC9C,OAAO,0BAA0B,CAClC,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sCAAsC;;;;;;;;;;;;;iBAIjD,CAAA;AACF,MAAM,MAAM,sCAAsC,GAAG,CAAC,CAAC,KAAK,CAC1D,OAAO,sCAAsC,CAC9C,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,uCAAuC;;iBAElD,CAAA;AACF,MAAM,MAAM,uCAAuC,GAAG,CAAC,CAAC,KAAK,CAC3D,OAAO,uCAAuC,CAC/C,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc;;;;;iBAKzB,CAAA;AACF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;iBAGhD,CAAA;AACF,MAAM,MAAM,qCAAqC,GAAG,CAAC,CAAC,KAAK,CACzD,OAAO,qCAAqC,CAC7C,CAAA"}

package/dist/api/program/cores.d.ts

@@ -0,0 +1,174 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program cores — the building's vertical-circulation cores (lift / stair / shaft
+ * shells).
+ *
+ * Read the cores in the scene, test whether a space is a core, and trigger core
+ * generation from a layout. `create` is a **thin trigger**: the program hands a
+ * core layout to the core-generation engine, which authors the geometry — the
+ * core geometry itself is owned by the geometry layer, not here (the exact
+ * layout ↔ engine payload is coordinated with the geometry owner).
+ *
+ * `list`/`isCore` are reads; `create` triggers generation.
+ *
+ * Accessed via `snaptrude.program.cores`.
+ */
+export declare abstract class PluginProgramCoresApi {
+    constructor();
+    /**
+     * List the cores currently in the building.
+     *
+     * @returns A {@linkcode PluginProgramCoresListResult} with each core's id,
+     *   core group, and storey (empty when there are none).
+     *
+     * @examplePrompt List the cores in the building
+     * @examplePrompt How many cores are placed?
+     * @examplePrompt Show me the lift and stair cores
+     * @examplePrompt Which storeys have cores?
+     *
+     * # Example
+     * ```ts
+     * const { cores } = await snaptrude.program.cores.list()
+     * ```
+     */
+    abstract list(): PluginApiReturn<PluginProgramCoresListResult>;
+    /**
+     * Test whether a space is a circulation core element.
+     *
+     * @param id - The id of the space to test.
+     * @returns `true` if the space is a core element.
+     *
+     * @examplePrompt Is this space a core?
+     * @examplePrompt Does this mass belong to the core?
+     * @examplePrompt Check if space sp_1 is a circulation core
+     *
+     * # Example
+     * ```ts
+     * const isCore = await snaptrude.program.cores.isCore("sp_1")
+     * ```
+     */
+    abstract isCore(id: string): PluginApiReturn<boolean>;
+    /**
+     * Generate core geometry from a layout (thin trigger).
+     *
+     * Hands the core layout to the core-generation engine and returns how many core
+     * elements were created. The geometry is authored by the engine, not here.
+     * _(Authored ahead — optional until the host's geometry adapter lands; the
+     * reads {@linkcode PluginProgramCoresApi.list}/{@linkcode PluginProgramCoresApi.isCore}
+     * are live.)_
+     *
+     * @param cores - The {@linkcode PluginProgramCoreSpec} layout of cores to
+     *   generate.
+     * @param lengthUnit - Unit of the spec dimensions (default project unit).
+     * @returns A {@linkcode PluginProgramCoresCreateResult} with the created count.
+     * @throws If the layout could not be realized.
+     *
+     * @examplePrompt Generate the building cores from this layout
+     * @examplePrompt Place the elevator and stair cores
+     * @examplePrompt Create the service core shells
+     *
+     * # Example
+     * ```ts
+     * await snaptrude.program.cores.create([
+     *   { type: "lift", position: { x: 0, y: 0, z: 0 }, width: 3, depth: 4 },
+     * ])
+     * ```
+     */
+    create?: (cores: PluginProgramCoreSpec[], lengthUnit?: "mm" | "m" | "ft") => PluginApiReturn<PluginProgramCoresCreateResult>;
+}
+/**
+ * A circulation core element in the building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Component id of the core element |
+ * | `groupId` | `string` | Id of the core group this element belongs to |
+ * | `storey` | `number` | Storey (floor number) the element sits on |
+ */
+export declare const PluginProgramCore: z.ZodObject<{
+    id: z.ZodString;
+    groupId: z.ZodString;
+    storey: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramCore = z.infer<typeof PluginProgramCore>;
+/** Result of {@linkcode PluginProgramCoresApi.list}. */
+export declare const PluginProgramCoresListResult: z.ZodObject<{
+    cores: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        groupId: z.ZodString;
+        storey: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramCoresListResult = z.infer<typeof PluginProgramCoresListResult>;
+/** Arguments for {@linkcode PluginProgramCoresApi.isCore}. */
+export declare const PluginProgramCoresIsCoreArgs: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramCoresIsCoreArgs = z.infer<typeof PluginProgramCoresIsCoreArgs>;
+/**
+ * One core to generate. The geometry layer interprets this layout (the exact
+ * fields are coordinated with the geometry owner).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | `string \| undefined` | Core kind (e.g. `"lift"`, `"stair"`, `"shaft"`) |
+ * | `position` | `{ x; y; z }` | Base position of the core |
+ * | `width` | `number` | Core width, in `lengthUnit` |
+ * | `depth` | `number` | Core depth, in `lengthUnit` |
+ * | `fromStorey` | `number \| undefined` | First storey the core spans |
+ * | `toStorey` | `number \| undefined` | Last storey the core spans |
+ */
+export declare const PluginProgramCoreSpec: z.ZodObject<{
+    type: z.ZodOptional<z.ZodString>;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        z: z.ZodNumber;
+    }, z.core.$strip>;
+    width: z.ZodNumber;
+    depth: z.ZodNumber;
+    fromStorey: z.ZodOptional<z.ZodNumber>;
+    toStorey: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramCoreSpec = z.infer<typeof PluginProgramCoreSpec>;
+/**
+ * Arguments for {@linkcode PluginProgramCoresApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `cores` | {@linkcode PluginProgramCoreSpec}`[]` | The cores to generate |
+ * | `lengthUnit` | `"mm" \| "m" \| "ft" \| undefined` | Unit of the spec dimensions (default project unit) |
+ */
+export declare const PluginProgramCoresCreateArgs: z.ZodObject<{
+    cores: z.ZodArray<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            z: z.ZodNumber;
+        }, z.core.$strip>;
+        width: z.ZodNumber;
+        depth: z.ZodNumber;
+        fromStorey: z.ZodOptional<z.ZodNumber>;
+        toStorey: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    lengthUnit: z.ZodOptional<z.ZodEnum<{
+        ft: "ft";
+        m: "m";
+        mm: "mm";
+    }>>;
+}, z.core.$strip>;
+export type PluginProgramCoresCreateArgs = z.infer<typeof PluginProgramCoresCreateArgs>;
+/**
+ * Result of {@linkcode PluginProgramCoresApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `createdCount` | `number` | Number of core elements created |
+ */
+export declare const PluginProgramCoresCreateResult: z.ZodObject<{
+    createdCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramCoresCreateResult = z.infer<typeof PluginProgramCoresCreateResult>;
+//# sourceMappingURL=cores.d.ts.map

package/dist/api/program/cores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cores.d.ts","sourceRoot":"","sources":["../../../src/api/program/cores.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;GAaG;AACH,8BAAsB,qBAAqB;;IAGzC;;;;;;;;;;;;;;;OAeG;aACa,IAAI,IAAI,eAAe,CAAC,4BAA4B,CAAC;IAErE;;;;;;;;;;;;;;OAcG;aACa,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC;IAE5D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,MAAM,CAAC,EAAE,CACd,KAAK,EAAE,qBAAqB,EAAE,EAC9B,UAAU,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,KAC3B,eAAe,CAAC,8BAA8B,CAAC,CAAA;CACrD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;iBAI5B,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEjE,wDAAwD;AACxD,eAAO,MAAM,4BAA4B;;;;;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B;;iBAEvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;iBAOhC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAA;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B;;iBAEzC,CAAA;AACF,MAAM,MAAM,8BAA8B,GAAG,CAAC,CAAC,KAAK,CAClD,OAAO,8BAA8B,CACtC,CAAA"}