@snaptrude/plugin-core 0.9.4 → 0.9.6

package/src/api/design/query/index.ts

@@ -1041,8 +1041,107 @@ export abstract class PluginDesignQueryApi {
   public abstract getBoundingBox(
     components: ComponentHandle[],
   ): PluginApiReturn<BBoxComponents | null>
+
+  /**
+   * Compute the plan **outline of what is built on a storey** — the union of
+   * the storey's wall (by default) footprints as polygons-with-holes. This is
+   * the footprint-from-the-built-model query: by the time slabs are needed the
+   * walls exist, and the engine's own solids (snapped, joined and mitred at
+   * creation) are the cleanest wall network available — no CAD re-tracing.
+   *
+   * Semantics: the union of wall solids is the wall *material* — a ring-shaped
+   * polygon. The **outer ring is the OUTSIDE wall face** (the slab boundary);
+   * every enclosed region — rooms AND courtyards — appears as a hole. When the
+   * largest hole is ~zero the walls don't enclose anything: the footprint
+   * reports `enclosed: false` (an open wall network), never a garbage outline.
+   * Detached buildings come back as separate footprints.
+   *
+   * A read — nothing is created. Feed a footprint's `outline` to
+   * `core.geom.create.profileFromLinePoints` → `design.create.slab` to build
+   * the floor/roof plate. Coordinates are world-space plan (x, z) in Snaptrude
+   * internal units; `areaSq` values are in squared internal units.
+   *
+   * @param options - storey / included kinds / debris filter; see
+   *   {@linkcode PluginStoreyOutlineOptions}.
+   * @returns the storey's footprints (possibly several for detached buildings)
+   *   plus pieces discarded by `minArea` (`footprints: []` when nothing matches).
+   *
+   * @examplePrompt What is the building footprint on the ground floor?
+   * @examplePrompt Create a floor slab covering the whole storey
+   * @examplePrompt Get the outline of the walls on storey 1
+   * @examplePrompt How much area do the ground-floor walls enclose?
+   *
+   * # Example
+   * ```ts
+   * const r = await snaptrude.design.query.storeyOutline({ storey: 1 })
+   * const main = r.footprints.find((f) => f.enclosed)
+   * if (main) {
+   *   const profile = await snaptrude.core.geom.create.profileFromLinePoints(
+   *     main.outline.map((p) => ({ x: p.x, y: 0, z: p.z })),
+   *   )
+   *   // → design.create.slab with the profile's contour
+   * }
+   * ```
+   */
+  public abstract storeyOutline(
+    options?: PluginStoreyOutlineOptions,
+  ): PluginApiReturn<PluginStoreyOutlineResult>
 }
 
+
+/** A point in the world-space plan (x, z) projection, Snaptrude internal units. */
+export const PluginOutlinePlanPoint = z.object({ x: z.number(), z: z.number() })
+export type PluginOutlinePlanPoint = z.infer<typeof PluginOutlinePlanPoint>
+
+/**
+ * Options for {@link PluginDesignQueryApi.storeyOutline}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storey` | `number`? | Only components on this storey (default: all storeys) |
+ * | `include` | {@link PluginEntityType}`[]`? | Component kinds to union (default `["wall"]`) |
+ * | `minArea` | `number`? | Drop union pieces below this plan area, squared internal units (default `1`) |
+ */
+export const PluginStoreyOutlineOptions = z.object({
+  storey: z.number().int().optional(),
+  include: z.array(PluginEntityType).nonempty().default(["wall"]),
+  minArea: z.number().nonnegative().default(1),
+})
+export type PluginStoreyOutlineOptions = z.input<
+  typeof PluginStoreyOutlineOptions
+>
+
+/**
+ * One connected footprint from {@link PluginDesignQueryApi.storeyOutline}.
+ * `outline` traces the OUTSIDE wall face; `holes` are the enclosed regions
+ * (rooms and courtyards). `enclosed` is `false` when the wall network does not
+ * close around any region (open C-shape) — don't slab an unenclosed outline
+ * without checking it.
+ */
+export const PluginStoreyFootprint = z.object({
+  outline: z.array(PluginOutlinePlanPoint),
+  holes: z.array(
+    z.object({
+      ring: z.array(PluginOutlinePlanPoint),
+      areaSq: z.number().nonnegative(),
+    }),
+  ),
+  areaSq: z.number().nonnegative(),
+  enclosed: z.boolean(),
+})
+export type PluginStoreyFootprint = z.infer<typeof PluginStoreyFootprint>
+
+/** Result of {@link PluginDesignQueryApi.storeyOutline}. */
+export const PluginStoreyOutlineResult = z.object({
+  footprints: z.array(PluginStoreyFootprint),
+  discarded: z.array(
+    z.object({ areaSq: z.number().nonnegative(), reason: z.string() }),
+  ),
+})
+export type PluginStoreyOutlineResult = z.infer<
+  typeof PluginStoreyOutlineResult
+>
+
 export * from "./geometry"
 export * from "./spaces"
 export * from "./referenceLines"

package/src/api/design/visibility.ts

@@ -39,6 +39,26 @@ export abstract class PluginDesignVisibilityApi {
     components: ComponentHandle[],
   ): PluginApiReturn<PluginDesignChangeResult>
 
+  /**
+   * Reveal specific hidden components — the inverse of
+   * {@linkcode PluginDesignVisibilityApi.hide}. Use
+   * {@linkcode PluginDesignVisibilityApi.showAll} to reveal everything.
+   *
+   * @param components - The components to reveal.
+   * @returns A {@linkcode PluginDesignChangeResult} echoing the components shown.
+   *
+   * @examplePrompt Show these walls again
+   * @examplePrompt Unhide the selected furniture
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.visibility.show([wall])
+   * ```
+   */
+  public abstract show(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
   /**
    * Isolate entities — hide everything else so only the given entities remain
    * visible (the "Isolate" / solo action). Undoable. Reverse it with
@@ -94,6 +114,20 @@ export const PluginDesignVisibilityHideArgs = z.object({
 })
 export type PluginDesignVisibilityHideArgs = z.infer<typeof PluginDesignVisibilityHideArgs>
 
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.show}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to reveal |
+ */
+export const PluginDesignVisibilityShowArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityShowArgs = z.infer<
+  typeof PluginDesignVisibilityShowArgs
+>
+
 /**
  * Arguments for {@linkcode PluginDesignVisibilityApi.isolate}.
  *