@snaptrude/plugin-core 0.3.0 → 0.6.0

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

@@ -0,0 +1,69 @@
+import { PluginProgramDepartmentsApi } from "./departments";
+import { PluginProgramAdjacencyApi } from "./adjacency";
+import { PluginProgramLayoutApi } from "./layout";
+import { PluginProgramMetricsApi } from "./metrics";
+import { PluginProgramSpreadsheetApi } from "./spreadsheet";
+import { PluginProgramSiteApi } from "./site";
+import { PluginProgramCoresApi } from "./cores";
+import { PluginProgramClassificationApi } from "./classification";
+import { PluginProgramAreasApi } from "./areas";
+/**
+ * Program-mode planning APIs.
+ *
+ * The program is the space-planning layer: department groupings with area targets,
+ * the metrics that track allocated area against those targets, and the reports
+ * that render program/takeoff data to spreadsheet sheets. Reads describe the
+ * *plan* (intent + targets); the geometry that realizes the plan is authored
+ * through the geometry namespaces.
+ *
+ * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
+ * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope (authored ahead)
+ * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
+ * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
+ * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets and read it back
+ * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
+ * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
+ * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
+ *
+ * Sub-namespaces typed as optional (`?`) are **authored ahead of the host** —
+ * declared so plugins and codegen can see the shape, but not required of host
+ * implementations and kept out of the discovery manifest until the host lands
+ * them (at which point they are promoted to required `abstract` members).
+ *
+ * Accessed via `snaptrude.program`.
+ */
+export declare abstract class PluginProgramApi {
+    /** Program departments — groupings, area targets, and space assignment. See {@linkcode PluginProgramDepartmentsApi}. */
+    abstract departments: PluginProgramDepartmentsApi;
+    /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
+    abstract adjacency: PluginProgramAdjacencyApi;
+    /**
+     * Arrange/pack spaces in the envelope. See {@linkcode PluginProgramLayoutApi}.
+     * _(authored ahead — optional until the host lands it next increment.)_
+     */
+    layout?: PluginProgramLayoutApi;
+    /** Area-program summary — targets vs allocated area. See {@linkcode PluginProgramMetricsApi}. */
+    abstract metrics: PluginProgramMetricsApi;
+    /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */
+    abstract areas: PluginProgramAreasApi;
+    /** Spreadsheet reports — render tables to sheets, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
+    abstract spreadsheet: PluginProgramSpreadsheetApi;
+    /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
+    abstract site: PluginProgramSiteApi;
+    /** Vertical-circulation cores — read & predicate (live); generation trigger is optional. See {@linkcode PluginProgramCoresApi}. */
+    abstract cores: PluginProgramCoresApi;
+    /** Classification catalog (space/area/mass types) + display tags. See {@linkcode PluginProgramClassificationApi}. */
+    abstract classification: PluginProgramClassificationApi;
+    constructor();
+}
+export * from "./departments";
+export * from "./adjacency";
+export * from "./layout";
+export * from "./metrics";
+export * from "./spreadsheet";
+export * from "./site";
+export * from "./cores";
+export * from "./classification";
+export * from "./areas";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/program/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAC/C,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAA;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAA;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8BAAsB,gBAAgB;IACpC,wHAAwH;IACxH,SAAgB,WAAW,EAAE,2BAA2B,CAAA;IACxD,4GAA4G;IAC5G,SAAgB,SAAS,EAAE,yBAAyB,CAAA;IACpD;;;OAGG;IACI,MAAM,CAAC,EAAE,sBAAsB,CAAA;IACtC,iGAAiG;IACjG,SAAgB,OAAO,EAAE,uBAAuB,CAAA;IAChD,uFAAuF;IACvF,SAAgB,KAAK,EAAE,qBAAqB,CAAA;IAC5C,2HAA2H;IAC3H,SAAgB,WAAW,EAAE,2BAA2B,CAAA;IACxD,mHAAmH;IACnH,SAAgB,IAAI,EAAE,oBAAoB,CAAA;IAC1C,mIAAmI;IACnI,SAAgB,KAAK,EAAE,qBAAqB,CAAA;IAC5C,qHAAqH;IACrH,SAAgB,cAAc,EAAE,8BAA8B,CAAA;;CAG/D;AAED,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,kBAAkB,CAAA;AAChC,cAAc,SAAS,CAAA"}

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

@@ -0,0 +1,63 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program layout — arrange and pack spaces inside the envelope.
+ *
+ * These wrap the product's **Arrange in envelope** / **Pack in envelope**
+ * tools (engine: `Planner.pack_arrange` in the react host) — stages two and
+ * three of the space-planning workflow that starts with
+ * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
+ *
+ * _(Authored ahead — both methods are optional until the host lands them in
+ * the next increment, and are kept out of the discovery manifest until then.)_
+ *
+ * Accessed via `snaptrude.program.layout`.
+ */
+export declare abstract class PluginProgramLayoutApi {
+    constructor();
+    /**
+     * Arrange the spaces inside the envelope using the computed adjacency data.
+     * _(Authored ahead — optional until the host lands.)_
+     *
+     * @examplePrompt Arrange the rooms in the envelope
+     * @examplePrompt Lay out the departments inside the building envelope
+     * @examplePrompt Auto-arrange the program spaces
+     *
+     * # Example
+     * ```ts
+     * const { success, error } = await snaptrude.program.layout.arrange()
+     * if (!success) console.log("Arrange failed:", error)
+     * ```
+     */
+    arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
+    /**
+     * Pack the spaces into the envelope (a tighter fit than arrange).
+     * _(Authored ahead — optional until the host lands.)_
+     *
+     * @examplePrompt Pack the rooms into the envelope
+     * @examplePrompt Fit the program spaces tightly into the building
+     * @examplePrompt Run pack-in-envelope on this storey
+     *
+     * # Example
+     * ```ts
+     * const { success, error } = await snaptrude.program.layout.pack()
+     * if (!success) console.log("Pack failed:", error)
+     * ```
+     */
+    pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>;
+}
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.arrange} /
+ * {@linkcode PluginProgramLayoutApi.pack}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the layout run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export declare const PluginProgramLayoutRunResult: z.ZodObject<{
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PluginProgramLayoutRunResult = z.infer<typeof PluginProgramLayoutRunResult>;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/api/program/layout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;GAYG;AACH,8BAAsB,sBAAsB;;IAG1C;;;;;;;;;;;;;OAaG;IACI,OAAO,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;IAEpE;;;;;;;;;;;;;OAaG;IACI,IAAI,CAAC,EAAE,MAAM,eAAe,CAAC,4BAA4B,CAAC,CAAA;CAClE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;iBAGvC,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,4BAA4B,CACpC,CAAA"}

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

@@ -0,0 +1,108 @@
+import * as z from "zod";
+import { PluginApiReturn } from "../../types";
+/**
+ * Program metrics — the area-program summary of the active project.
+ *
+ * Aggregate planning numbers: total target versus allocated area, plus a
+ * per-department breakdown. This is the program-mode "am I hitting my area
+ * targets?" read; per-entity geometry measurements (a single space's area,
+ * volume, bounding box) live under the geometry namespaces, not here.
+ *
+ * Every area is reported in the summary's `units` (ft² or m²). This is a read:
+ * it never throws and returns an empty breakdown with zero totals when the
+ * project has no program.
+ *
+ * Accessed via `snaptrude.program.metrics`.
+ */
+export declare abstract class PluginProgramMetricsApi {
+    constructor();
+    /**
+     * Get the area-program summary for the active project.
+     *
+     * @returns A {@linkcode PluginProgramMetricsSummary} with project-level totals
+     *   and a per-department area breakdown.
+     *
+     * @examplePrompt How much area have I allocated versus my targets?
+     * @examplePrompt Give me the program area summary
+     * @examplePrompt Which departments are over or under their target area?
+     * @examplePrompt What's the total built area in the program?
+     * @examplePrompt Show the area breakdown per department
+     * @examplePrompt Am I within my area program?
+     *
+     * # Example
+     * ```ts
+     * const m = await snaptrude.program.metrics.get()
+     * console.log(`${m.totalAllocatedArea} / ${m.totalTargetArea} ${m.units}`)
+     * console.log("unassigned:", m.unassignedArea)
+     * for (const d of m.departments) {
+     *   console.log(d.name, d.allocatedArea, d.targetArea)
+     * }
+     * ```
+     */
+    abstract get(): PluginApiReturn<PluginProgramMetricsSummary>;
+}
+/**
+ * The unit areas are reported in: square feet (`"ft2"`) or square metres (`"m2"`).
+ *
+ * **Area-units convention (applies to every area-returning method).** A result
+ * carries exactly one `units` field, at the **top level of the value the method
+ * returns**: on the response **envelope** for `list`/multi/composite results, and
+ * on the **record itself** only for a single `.get` that returns a bare record.
+ * Inner/leaf records never repeat it.
+ */
+export declare const PluginAreaUnit: z.ZodEnum<{
+    ft2: "ft2";
+    m2: "m2";
+}>;
+export type PluginAreaUnit = z.infer<typeof PluginAreaUnit>;
+/**
+ * Per-department area figures within the program summary. Areas are in the
+ * enclosing {@linkcode PluginProgramMetricsSummary}'s `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | Department id |
+ * | `name` | `string` | Department name |
+ * | `targetArea` | `number \| null` | Target area in project units, or `null` if no target is set |
+ * | `allocatedArea` | `number` | Area currently allocated to this department, in project units |
+ */
+export declare const PluginProgramDepartmentMetric: z.ZodObject<{
+    departmentId: z.ZodString;
+    name: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    allocatedArea: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramDepartmentMetric = z.infer<typeof PluginProgramDepartmentMetric>;
+/**
+ * Result of {@linkcode PluginProgramMetricsApi.get}.
+ *
+ * Reconciliation invariant: `totalAllocatedArea === unassignedArea` plus the sum
+ * of every `departments[].allocatedArea`. `totalTargetArea` is the sum of every
+ * `departments[].targetArea` (a `null` target counts as 0); unassigned area has
+ * no target. Every area is in `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every area in this summary is reported in |
+ * | `totalTargetArea` | `number` | Sum of all department target areas |
+ * | `totalAllocatedArea` | `number` | Total allocated area = departments + `unassignedArea` |
+ * | `unassignedArea` | `number` | Allocated area not attributed to any listed department (site/unassigned) — the delta that reconciles the total |
+ * | `departments` | {@linkcode PluginProgramDepartmentMetric}`[]` | Per-department area breakdown |
+ */
+export declare const PluginProgramMetricsSummary: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    totalTargetArea: z.ZodNumber;
+    totalAllocatedArea: z.ZodNumber;
+    unassignedArea: z.ZodNumber;
+    departments: z.ZodArray<z.ZodObject<{
+        departmentId: z.ZodString;
+        name: z.ZodString;
+        targetArea: z.ZodNullable<z.ZodNumber>;
+        allocatedArea: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramMetricsSummary = z.infer<typeof PluginProgramMetricsSummary>;
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/api/program/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAA;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;GAaG;AACH,8BAAsB,uBAAuB;;IAG3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;aACa,GAAG,IAAI,eAAe,CAAC,2BAA2B,CAAC;CACpE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;EAAwB,CAAA;AACnD,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B;;;;;iBAKxC,CAAA;AACF,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,6BAA6B,CACrC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;iBAqBrC,CAAA;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,2BAA2B,CACnC,CAAA"}