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

package/src/api/design/visibility.ts

@@ -0,0 +1,143 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginDesignChangeResult } from "./lock"
+
+/**
+ * `snaptrude.design.visibility.*` — hide, isolate, and reveal scene entities.
+ *
+ * Visibility is a per-component user flag (the same one the "Hide" / "Isolate" /
+ * "Show All" toolbar and right-click actions toggle). Every method here commits
+ * an undoable command and echoes the affected entities as
+ * {@linkcode PluginDesignChangeResult}.
+ *
+ * Accessed via `snaptrude.design.visibility`.
+ */
+export abstract class PluginDesignVisibilityApi {
+  constructor() {}
+
+  /**
+   * Hide entities from the viewport — the same as the "Hide" action. Undoable.
+   * Hosted door/window/void children ride along with their wall. Already-hidden
+   * entities stay hidden.
+   *
+   * @param components Entities to hide
+   * @returns The affected entities (echoing the input handles)
+   *
+   * @examplePrompt Hide the selected walls
+   * @examplePrompt Conceal these masses so I can see behind them
+   * @examplePrompt Hide every column on this floor
+   * @examplePrompt Make this furniture disappear from view
+   *
+   * # Example
+   * ```ts
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.visibility.hide(walls)
+   * ```
+   */
+  public abstract hide(
+    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
+   * {@linkcode PluginDesignVisibilityApi.showAll}.
+   *
+   * @param components Entities to keep visible; everything else is hidden
+   * @returns The isolated entities (echoing the input handles)
+   *
+   * @examplePrompt Isolate the selected room so I can focus on it
+   * @examplePrompt Show only these walls and hide the rest
+   * @examplePrompt Solo this mass
+   * @examplePrompt Hide everything except the staircase
+   *
+   * # Example
+   * ```ts
+   * const [room] = await snaptrude.design.selection.get()
+   * await snaptrude.design.visibility.isolate([room])
+   * ```
+   */
+  public abstract isolate(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Reveal everything hidden on the active story — the "Show All" action, which
+   * also exits an isolate. Undoable.
+   *
+   * @returns The entities that were made visible
+   *
+   * @examplePrompt Show everything again
+   * @examplePrompt Unhide all the hidden objects
+   * @examplePrompt Exit isolate mode
+   * @examplePrompt Reveal everything I hid earlier
+   *
+   * # Example
+   * ```ts
+   * const { affected } = await snaptrude.design.visibility.showAll()
+   * console.log(`Revealed ${affected.length} entities`)
+   * ```
+   */
+  public abstract showAll(): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.hide}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to hide |
+ */
+export const PluginDesignVisibilityHideArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+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}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to keep visible |
+ */
+export const PluginDesignVisibilityIsolateArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityIsolateArgs = z.infer<
+  typeof PluginDesignVisibilityIsolateArgs
+>

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

@@ -2,14 +2,21 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../../types"
 import { ComponentHandle } from "../../../handles"
 import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
 
 /**
  * `snaptrude.design.windows` — window-specific reads. Creation lives at
  * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
  * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
  *
- * `listTypes` (UI-const catalog), `getSillHeight` (bounds-derived), and the
- * command-wired `mirror` land in a later pass.
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
+ * browse the placeable window library — plain value records keyed by a library id
+ * (team `_id` or general `fullName`), NOT handles — and feed `design.create.window`.
+ * They are network-backed but carry no `Async` suffix (§6.6) and never throw
+ * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * DTOs are shared with `design.doors` (defined there, re-exported here).
+ *
+ * `getSillHeight` (bounds-derived) and the command-wired `mirror` land in a later pass.
  */
 export abstract class PluginDesignWindowsApi {
   constructor() {}
@@ -148,6 +155,91 @@ export abstract class PluginDesignWindowsApi {
     window: ComponentHandle,
     height: number
   ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the window catalog **groups** — the placement families (Fixed,
+   * Casement, Sliding, Folding, …), built-in groups merged with any
+   * team-custom types.
+   *
+   * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What kinds of windows can I place?
+   * @examplePrompt List the window groups in the catalog
+   * @examplePrompt Show me the window families available in this project
+   * @examplePrompt Which window types does this project support?
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.windows.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable window catalog (team + general libraries), optionally
+   * restricted to one group by its `dbType` token.
+   *
+   * @param group Restrict to one group's `dbType` (optional; e.g. `"casementDouble"`)
+   * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What windows can I place in this project?
+   * @examplePrompt List every window in the library
+   * @examplePrompt Show me the casement windows I can add
+   * @examplePrompt Browse the window catalog
+   *
+   * # Example
+   * ```ts
+   * const [group] = await snaptrude.design.windows.listCatalogGroups()
+   * const items = await snaptrude.design.windows.listCatalog(group?.dbType)
+   * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
+   * ```
+   */
+  public abstract listCatalog(
+    group?: string
+  ): PluginApiReturn<PluginObjectCatalogItem[]>
+
+  /**
+   * Get a single window catalog item by its library id.
+   *
+   * @param id The catalog library id
+   * @returns The item, or `null` if no catalog item matches
+   *
+   * @examplePrompt Get the details of this window from the library
+   * @examplePrompt Look up the catalog entry for this window id
+   * @examplePrompt What is the cost of this window item?
+   * @examplePrompt Show me the family name of this window in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const item = await snaptrude.design.windows.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.dbType)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginObjectCatalogItem | null>
+
+  /**
+   * Test whether a window catalog item exists for the given library id.
+   *
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this window still in the library?
+   * @examplePrompt Check whether a window catalog item with this id exists
+   * @examplePrompt Does my team library have this window?
+   * @examplePrompt Verify the window is available before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const stillAvailable = await snaptrude.design.windows.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
 }
 
 /**
@@ -205,3 +297,37 @@ export const PluginDesignWindowSetHeightArgs = z.object({
   height: z.number(),
 })
 export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>
+
+// ---------------------------------------------------------------------------
+// catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
+// ---------------------------------------------------------------------------
+
+// Re-export the shared catalog DTOs imported at the top of this file.
+export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
+ */
+export const PluginDesignWindowListCatalogArgs = z.object({
+  group: z.string().optional(),
+})
+export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindowListCatalogArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignWindowGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignWindowGetCatalogItemArgs = z.infer<typeof PluginDesignWindowGetCatalogItemArgs>
+
+export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
+export type PluginDesignWindowExistsArgs = z.infer<typeof PluginDesignWindowExistsArgs>

package/src/api/entity/buildableEnvelope.ts

@@ -54,6 +54,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.create.buildableEnvelope`
    */
   public abstract create(
     sitePolygon: PluginBuildableEnvelopePolygonVertex[],
@@ -106,6 +108,8 @@ export abstract class PluginBuildableEnvelopeApi {
    *   12,
    * )
    * ```
+   *
+   * @deprecated Use `design.update.buildableEnvelope`
    */
   public abstract update(
     buildableEnvelopeId: string,

package/src/api/entity/referenceLine.ts

@@ -49,6 +49,8 @@ export abstract class PluginReferenceLineApi {
    *
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
    * ```
+   *
+   * @deprecated Use `design.create.referenceLines`
    */
   public abstract createMulti(
     profile: ProfileHandle
@@ -78,6 +80,8 @@ export abstract class PluginReferenceLineApi {
    * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
    * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
    * ```
+   *
+   * @deprecated Use `design.query.referenceLines.get`
    */
   public abstract get(
     referenceLineId: string,
@@ -104,6 +108,8 @@ export abstract class PluginReferenceLineApi {
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
    * console.log(`Project has ${referenceLineIds.length} reference lines`)
    * ```
+   *
+   * @deprecated Use `design.query.listReferenceLines`
    */
   public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
 
@@ -125,6 +131,8 @@ export abstract class PluginReferenceLineApi {
    * ```ts
    * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
    * ```
+   *
+   * @deprecated Use `design.delete.entities`
    */
   public abstract delete(
     referenceLineId: string