@snaptrude/plugin-core 0.9.17 → 0.9.18-networks-20261020.1

package/src/api/presentation/views.ts

@@ -2,7 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
 /**
- * Presentation views — read the saved 2D/3D views used to prepare presentations.
+ * Presentation views — read the saved plan, 3D, and elevation views used to prepare presentations.
  *
  * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
  * A plugin can list and read views, capture them to images, activate one (move
@@ -24,10 +24,10 @@ export abstract class PluginPresentationViewsApi {
    * List the saved views in the active project.
    *
    * @returns A {@linkcode PluginPresentationViewsListResult} with a `views` array
-   *   of 2D and 3D views (empty when the project has none).
+   *   of plan, 3D, and elevation views (empty when the project has none).
    *
    * @examplePrompt List all the saved views
-   * @examplePrompt What 2D and 3D views are in this project?
+   * @examplePrompt What plan, 3D, and elevation views are in this project?
    * @examplePrompt Which view is currently active?
    * @examplePrompt Get the names of every presentation view
    * @examplePrompt Show me the 3D views I can put on a sheet
@@ -115,6 +115,10 @@ export abstract class PluginPresentationViewsApi {
    * Applies the view's camera, visibility, and storey state to the live scene.
    * Paired with {@linkcode PluginPresentationViewsApi.getActive}.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param viewId - The id of the view to activate.
    * @returns The id of the now-active view.
    * @throws If no view has the given id.
@@ -138,6 +142,15 @@ export abstract class PluginPresentationViewsApi {
    *
    * Creates a camera bookmark (not geometry) from where the camera is now.
    *
+   * Works while Present mode is open. Present draws its drawings on the same
+   * 3D scene, so a view saved in Present takes its framing (camera, 2D or 3D
+   * mode, projection, storey, building) from the Design frame instead: the one
+   * the user had when Present opened, or one a plugin set since with
+   * `setActive`, `updateSettings({ viewMode })`, `core.camera`, `core.zoom`,
+   * `core.storeys.setActive`, `core.storeys.layers.setActive` or
+   * `core.buildings.setActive`. It never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param name - Name for the new view (a default is used when omitted).
    * @param options - Optional `kind` (what kind of view to save, default
    *   `"view"`) and `storey` (save the view on a specific storey — the storey is
@@ -171,12 +184,16 @@ export abstract class PluginPresentationViewsApi {
    *
    * @param viewId - The id of the view to read settings for.
    * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
-   *   no view has that id.
+   *   no view has that id. A plan view also reports its `cutPlaneHeight`,
+   *   `viewDepthStorey` and `showOverheadObjects` (saved values, or the product
+   *   defaults for a plan saved before cut ranges existed); other views omit them.
    *
    * @examplePrompt What color mode is the Ground Floor view using?
    * @examplePrompt Get the display settings for this view
    * @examplePrompt Does the site plan view show axes and labels?
    * @examplePrompt Read the background color of the active view
+   * @examplePrompt What is the cut height of this plan?
+   * @examplePrompt How deep does this plan look below the cut?
    *
    * # Example
    * ```ts
@@ -226,14 +243,24 @@ export abstract class PluginPresentationViewsApi {
    * toggle the view-settings modal runs); on other views the mode is applied
    * the next time the view is activated.
    *
+   * `cutPlaneHeight`, `viewDepthStorey` and `showOverheadObjects` set the plan's
+   * cut range and apply to **plan views only** (patching them on a 3D, elevation
+   * or site-plan view is rejected). `cutPlaneHeight` is in engine units, the same
+   * unit as `story.height`, and must be greater than 0 and less than the plan
+   * storey's height. `viewDepthStorey` must be an existing storey at or below the
+   * plan's storey. A sparse patch leaves the other two range fields as they
+   * were; on the active plan the canvas redraws live.
+   *
    * @param viewId - The id of the view to update.
    * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
    *   omitted field is left unchanged.
    * @returns The updated view's `id`.
    * @throws If writes are disabled, no view has the given id, the patch is
    *   contradictory (`showLabels: false` with a non-empty `labels`, or
-   *   `showLabels: true` with an explicitly empty `labels` list), or
-   *   `viewMode: "perspective"` is patched on a 2D plan view.
+   *   `showLabels: true` with an explicitly empty `labels` list),
+   *   `viewMode: "perspective"` is patched on a 2D plan view, a plan-range
+   *   field is patched on a view that is not a plan, or the cut height / depth
+   *   is out of range.
    *
    * @examplePrompt Switch this view to monochrome color mode
    * @examplePrompt Turn off the axis in the Ground Floor view
@@ -241,6 +268,9 @@ export abstract class PluginPresentationViewsApi {
    * @examplePrompt Show area labels on this view
    * @examplePrompt Enable hidden-line mode for the section view
    * @examplePrompt Make the 3D view orthographic instead of perspective
+   * @examplePrompt Raise the cut plane of the Ground Floor plan to 1.8 m
+   * @examplePrompt Show the basement below in this plan
+   * @examplePrompt Hide the overhead objects in this plan
    *
    * # Example
    * ```ts
@@ -252,6 +282,12 @@ export abstract class PluginPresentationViewsApi {
    * await snaptrude.presentation.views.updateSettings("view_123", {
    *   viewMode: "isometric",
    * })
+   * // set a plan's range: cut 1.2 m up, show the basement below, no overhead
+   * await snaptrude.presentation.views.updateSettings("plan_1", {
+   *   cutPlaneHeight: 4.72,
+   *   viewDepthStorey: -1,
+   *   showOverheadObjects: false,
+   * })
    * ```
    */
   public abstract updateSettings(
@@ -315,13 +351,36 @@ export abstract class PluginPresentationViewsApi {
 }
 
 /**
- * The kind of a saved view: a 2D plan view or a 3D view.
+ * The rendering category of a saved view. Existing plan/3D values are preserved;
+ * elevations are identified independently of their orthographic 3D camera.
  */
-export const PluginPresentationViewType = z.enum(["2d", "3d"])
+export const PluginPresentationViewType = z.enum(["2d", "3d", "elevation"])
 export type PluginPresentationViewType = z.infer<
   typeof PluginPresentationViewType
 >
 
+/** The native semantic kind persisted for a saved view. */
+export const PluginPresentationViewKind = z.enum([
+  "plan",
+  "sitePlan",
+  "threeD",
+  "elevation",
+])
+export type PluginPresentationViewKind = z.infer<
+  typeof PluginPresentationViewKind
+>
+
+/** Cardinal direction for an elevation; non-elevation views return `null`. */
+export const PluginPresentationElevationDirection = z.enum([
+  "north",
+  "east",
+  "south",
+  "west",
+])
+export type PluginPresentationElevationDirection = z.infer<
+  typeof PluginPresentationElevationDirection
+>
+
 /**
  * A saved presentation view.
  *
@@ -329,7 +388,9 @@ export type PluginPresentationViewType = z.infer<
  * |---|---|---|
  * | `id` | `string` | Unique view id |
  * | `name` | `string` | Display name |
- * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
+ * | `type` | `"2d" \| "3d" \| "elevation"` | Rendering category; elevations are distinct from ordinary 3D views |
+ * | `kind` | {@linkcode PluginPresentationViewKind} | Native semantic view kind |
+ * | `direction` | {@linkcode PluginPresentationElevationDirection}` \| null` | Cardinal direction for elevations; otherwise `null` |
  * | `isActive` | `boolean` | Whether this view is the currently active view |
  * | `storey` | `number \| null` | The storey this view was saved on (`null` on older views saved without one) |
  */
@@ -337,6 +398,8 @@ export const PluginPresentationView = z.object({
   id: z.string(),
   name: z.string(),
   type: PluginPresentationViewType,
+  kind: PluginPresentationViewKind,
+  direction: PluginPresentationElevationDirection.nullable(),
   isActive: z.boolean(),
   storey: z.number().nullable(),
 })
@@ -533,6 +596,9 @@ export type PluginPresentationViewMode = z.infer<
  * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
  * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
  * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
+ * | `cutPlaneHeight` | `number`? | **Plan views only.** Height of the plan's cut plane above its storey base, in engine units (the unit `story.height` uses). Absent on 3D and elevation views |
+ * | `viewDepthStorey` | `number`? | **Plan views only.** The lowest storey the plan shows below the cut; defaults to the plan's own storey. Absent on 3D and elevation views |
+ * | `showOverheadObjects` | `boolean`? | **Plan views only.** Whether objects above the cut are drawn as dashed overhead linework. Absent on 3D and elevation views |
  */
 export const PluginPresentationViewSettings = z.object({
   backgroundColor: z.string(),
@@ -542,6 +608,9 @@ export const PluginPresentationViewSettings = z.object({
   showEdges: z.boolean(),
   showLabels: z.boolean(),
   labels: z.array(PluginPresentationViewLabel),
+  cutPlaneHeight: z.number().finite().positive().optional(),
+  viewDepthStorey: z.number().int().optional(),
+  showOverheadObjects: z.boolean().optional(),
 })
 export type PluginPresentationViewSettings = z.infer<
   typeof PluginPresentationViewSettings

package/src/errors/codes.ts

@@ -7,6 +7,8 @@
  * (`HANDLE_INVALID`) so error responses cannot be used as an existence /
  * ownership oracle (PLUGIN_HANDLE_MIGRATION_HLD §6). `HANDLE_KIND_MISMATCH`
  * stays distinct because the kind is information the caller already holds.
+ * `HANDLE_STALE` is the one deliberate exception: a handle the caller
+ * legitimately held whose entity was since retired (deleted or rebuilt).
  */
 export const PLUGIN_ERROR_CODES = [
   "VALIDATION",
@@ -34,6 +36,7 @@ export const PLUGIN_ERROR_CODES = [
   "PROPOSAL_SWITCH_BLOCKED",
   "INTERNAL",
   "UNKNOWN",
+  "HANDLE_STALE",
 ] as const
 
 export type PluginErrorCode = (typeof PLUGIN_ERROR_CODES)[number]
@@ -85,6 +88,10 @@ export const CODE_META: Record<PluginErrorCode, CodeMeta> = {
     hintTemplate: "Re-query the entity; do not cache handles across undo/reload.",
   },
   HANDLE_KIND_MISMATCH: { category: "handle" },
+  HANDLE_STALE: {
+    category: "handle",
+    hintTemplate: "The entity was deleted or rebuilt; re-query it for a fresh handle.",
+  },
   RESOURCE_QUOTA_EXCEEDED: {
     category: "quota",
     hintTemplate: "Release unused handles (core.handles.release) or use scopes.",

package/test/drawingContract.test.mjs

@@ -0,0 +1,288 @@
+// The drawing tool contract the agent reads: export file names are base names
+// without an extension, and architectural scales are standard denominators only.
+// Run: node --test test/
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import { readFileSync } from "node:fs"
+import {
+  STANDARD_DRAWING_SCALES,
+  METRIC_DRAWING_SCALES,
+  IMPERIAL_DRAWING_SCALES,
+  IMPERIAL_DETAIL_DRAWING_SCALES,
+  IMPERIAL_SITE_DRAWING_SCALES,
+  PluginDrawingCreateOptions,
+  PluginDrawingCreateArgs,
+  PluginDrawingScaleArgs,
+  PluginDrawingExportOptions,
+  PluginDrawingExportArgs,
+  PluginPresentationExportArgs,
+  PluginPresentationSheetsPlaceArgs,
+  PluginPresentationSheetsPlaceDrawingArgs,
+  PluginPresentationSheetsPlaceDrawingResult,
+  PluginPresentationSheetsPlaceResult,
+  PluginPresentationPlacedViewsSetScaleArgs,
+} from "../dist/index.js"
+import { buildManifest } from "../scripts/generate-manifest.mjs"
+
+// The Scale dropdown's values in the frontend (ALL_SCALES_DICTIONARY in
+// src/app/common/utils/scaleMeasurements.ts): metric, imperial detail, imperial site.
+const METRIC = [10, 20, 50, 100, 150, 200, 250, 500, 1000]
+const IMPERIAL_DETAIL = [12, 16, 24, 32, 48, 64, 96, 128, 192, 384, 768, 1536]
+const IMPERIAL_SITE = [120, 240, 360, 480, 600, 1200, 2400, 3600, 4800]
+
+const messagesOf = (result) => result.error.issues.map((issue) => issue.message)
+
+// --- standard scales ---------------------------------------------------------
+
+test("STANDARD_DRAWING_SCALES is the frontend's metric and imperial list, ascending", () => {
+  const expected = [...METRIC, ...IMPERIAL_DETAIL, ...IMPERIAL_SITE].sort((a, b) => a - b)
+  assert.deepEqual([...STANDARD_DRAWING_SCALES], expected)
+  assert.deepEqual([...METRIC_DRAWING_SCALES], METRIC)
+  assert.deepEqual([...IMPERIAL_DRAWING_SCALES], [...IMPERIAL_DETAIL, ...IMPERIAL_SITE].sort((a, b) => a - b))
+  assert.deepEqual([...IMPERIAL_DETAIL_DRAWING_SCALES], IMPERIAL_DETAIL)
+  assert.deepEqual([...IMPERIAL_SITE_DRAWING_SCALES], IMPERIAL_SITE)
+})
+
+const scaleSchemas = [
+  ["drawings.create options", (scale) => PluginDrawingCreateOptions.safeParse({ scale })],
+  ["drawings.create args", (scale) => PluginDrawingCreateArgs.safeParse({ viewId: "v1", scale })],
+  ["drawings.setScale", (scale) => PluginDrawingScaleArgs.safeParse({ drawingId: "d1", scale })],
+  ["sheets.place", (scale) => PluginPresentationSheetsPlaceArgs.safeParse({ sheetId: "s1", viewId: "v1", scale })],
+  ["placedViews.setScale", (scale) => PluginPresentationPlacedViewsSetScaleArgs.safeParse({ shapeId: "p1", scale })],
+]
+
+for (const [name, parse] of scaleSchemas) {
+  test(`${name} accepts every standard scale`, () => {
+    for (const scale of STANDARD_DRAWING_SCALES) {
+      assert.equal(parse(scale).success, true, `${name} rejected ${scale}`)
+    }
+  })
+
+  test(`${name} rejects a non-standard scale and lists the allowed ones`, () => {
+    for (const scale of [137, 75, 1, 99.5]) {
+      const result = parse(scale)
+      assert.equal(result.success, false, `${name} accepted ${scale}`)
+      const message = messagesOf(result).join("\n")
+      assert.match(message, /standard/i)
+      assert.ok(message.includes(`Metric: ${METRIC.join(", ")}`), message)
+      assert.ok(message.includes(`imperial detail: ${IMPERIAL_DETAIL.join(", ")}`), message)
+      assert.ok(message.includes(`imperial site: ${IMPERIAL_SITE.join(", ")}`), message)
+      assert.match(message, /largest/i)
+    }
+  })
+}
+
+test("create options still allow omitting the scale", () => {
+  assert.equal(PluginDrawingCreateOptions.safeParse({}).success, true)
+  assert.equal(PluginPresentationSheetsPlaceArgs.safeParse({ sheetId: "s", viewId: "v" }).success, true)
+})
+
+// --- placing a drawing on a sheet -------------------------------------------
+
+test("sheets.placeDrawing takes an optional boolean fit", () => {
+  const base = { sheetId: "s", drawingId: "d" }
+  assert.equal(PluginPresentationSheetsPlaceDrawingArgs.safeParse(base).success, true)
+  assert.equal(PluginPresentationSheetsPlaceDrawingArgs.safeParse({ ...base, fit: true }).success, true)
+  assert.equal(PluginPresentationSheetsPlaceDrawingArgs.safeParse({ ...base, fit: false }).success, true)
+  assert.equal(PluginPresentationSheetsPlaceDrawingArgs.safeParse({ ...base, fit: "yes" }).success, false)
+})
+
+test("sheets.placeDrawing reports the scale it used and whether it rescaled", () => {
+  const ok = (value) => PluginPresentationSheetsPlaceDrawingResult.safeParse(value).success
+  assert.equal(ok({ shapeId: "shape:a", scale: 192, rescaled: true }), true)
+  assert.equal(ok({ shapeId: "shape:a", scale: null, rescaled: false }), true)
+  assert.equal(ok({ shapeId: "shape:a" }), false)
+  assert.equal(ok({ shapeId: "shape:a", scale: 100 }), false)
+  assert.equal(ok({ shapeId: "shape:a", scale: 100, rescaled: false, overlaps: true }), true)
+  assert.equal(ok({ shapeId: "shape:a", scale: 100, rescaled: false, overlaps: "yes" }), false)
+})
+
+test("sheets.place may report the scale, whether it rescaled and whether it overlaps", () => {
+  const ok = (value) => PluginPresentationSheetsPlaceResult.safeParse(value).success
+  assert.equal(ok({ shapeId: "shape:a" }), true)
+  assert.equal(ok({ shapeId: "shape:a", scale: 192, rescaled: true, overlaps: false }), true)
+  assert.equal(ok({ shapeId: "shape:a", scale: null, rescaled: false }), true)
+  assert.equal(ok({ shapeId: "shape:a", overlaps: "no" }), false)
+  assert.equal(ok({ shapeId: "shape:a", rescaled: 1 }), false)
+})
+
+test("sheets.place may report that a drawing at an explicit scale overflows the sheet; placeDrawing never does", () => {
+  const place = (value) => PluginPresentationSheetsPlaceResult.safeParse(value).success
+  assert.equal(place({ shapeId: "shape:a", scale: 100, rescaled: false, overflows: true }), true)
+  assert.equal(place({ shapeId: "shape:a", scale: 100, rescaled: false, overflows: "yes" }), false)
+  const placeDrawing = PluginPresentationSheetsPlaceDrawingResult.safeParse({
+    shapeId: "shape:a",
+    scale: 100,
+    rescaled: false,
+    overflows: true,
+  })
+  assert.equal(placeDrawing.success, true)
+  assert.equal("overflows" in placeDrawing.data, false)
+})
+
+// --- file names --------------------------------------------------------------
+
+const fileNameSchemas = [
+  ["drawings.export options", (fileName) => PluginDrawingExportOptions.safeParse({ fileName })],
+  ["drawings.export args", (fileName) => PluginDrawingExportArgs.safeParse({ drawingId: "d1", format: "pdf", fileName })],
+  ["presentation.export", (fileName) => PluginPresentationExportArgs.safeParse({ format: "pdf", fileName })],
+]
+
+for (const [name, parse] of fileNameSchemas) {
+  test(`${name} rejects a file name with an extension`, () => {
+    for (const fileName of ["Floor Pattern View.pdf", "plan.PDF", "a.svg", "a.png", "a.jpg", "a.JPEG"]) {
+      const result = parse(fileName)
+      assert.equal(result.success, false, `${name} accepted ${fileName}`)
+      assert.match(messagesOf(result).join("\n"), /without an extension/i)
+    }
+  })
+
+  test(`${name} rejects a file name ending in a dot or whitespace`, () => {
+    // The host appends the extension, so "a.pdf." would become "a.pdf..pdf".
+    for (const fileName of ["a.pdf.", "plan.", "plan..", "plan ", "plan\t", "a.pdf .", "a.pdf. "]) {
+      const result = parse(fileName)
+      assert.equal(result.success, false, `${name} accepted ${JSON.stringify(fileName)}`)
+      assert.match(messagesOf(result).join("\n"), /without an extension/i)
+    }
+  })
+
+  test(`${name} accepts a base name`, () => {
+    for (const fileName of ["Floor Pattern View", "Level 1.2 plan", "pdf plan", "notes.v2"]) {
+      assert.equal(parse(fileName).success, true, `${name} rejected ${fileName}`)
+    }
+  })
+}
+
+// --- the contract the agent reads (api-manifest summaries) -------------------
+
+// Overloaded methods produce one leaf per signature; the documented one comes first.
+const manifest = new Map()
+for (const leaf of buildManifest()) if (!manifest.has(leaf.path)) manifest.set(leaf.path, leaf)
+const summaryOf = (path) => {
+  const leaf = manifest.get(path)
+  assert.ok(leaf, `no manifest leaf ${path}`)
+  return leaf.summary
+}
+
+test("export summaries tell the agent to pass fileName without an extension", () => {
+  for (const path of ["presentation.drawings.export", "presentation.export"]) {
+    assert.match(summaryOf(path), /fileName[^.]*without (an|its) extension/i, path)
+  }
+})
+
+test("scale summaries list the standard scales and say how to choose one", () => {
+  for (const path of [
+    "presentation.drawings.create",
+    "presentation.drawings.setScale",
+    "presentation.sheets.place",
+    "presentation.placedViews.setScale",
+  ]) {
+    const summary = summaryOf(path)
+    assert.ok(summary.includes(`Metric: ${METRIC.join(", ")}.`), `${path}: ${summary}`)
+    assert.ok(summary.includes(`Imperial detail: ${IMPERIAL_DETAIL.join(", ")}`), `${path}: ${summary}`)
+    assert.ok(summary.includes(`Imperial site: ${IMPERIAL_SITE.join(", ")}`), `${path}: ${summary}`)
+    assert.match(summary, /Pick the LARGEST standard scale \(smallest denominator\)/, path)
+    assert.match(summary, /fits its frame or sheet/i, path)
+    assert.match(summary, /usually 1:50 to 1:200/, path)
+    assert.match(summary, /Never use a site-sized scale/, path)
+    assert.match(summary, /project's unit system/, path)
+  }
+})
+
+test("drawings.create tells the agent to omit position and follow the label layout's suggested scale", () => {
+  const summary = summaryOf("presentation.drawings.create")
+  assert.match(summary, /Omit `position` unless the user asked for a specific place/, summary)
+  assert.match(summary, /next to its source view/, summary)
+  assert.match(summary, /labels\.getLayout\(drawingId\)/, summary)
+  assert.match(summary, /suggestedScale/, summary)
+})
+
+test("drawing writes send the agent to presentation.camera instead of promising to frame the camera", () => {
+  for (const path of [
+    "presentation.drawings.create",
+    "presentation.drawings.setScale",
+    "presentation.drawings.setCrop",
+  ]) {
+    const summary = summaryOf(path)
+    assert.doesNotMatch(summary, /frames the camera/i, path)
+    assert.match(summary, /Changes the drawing, not the Present camera/, path)
+    assert.match(summary, /presentation\.camera\.zoomTo\(drawing\.id\)/, path)
+    assert.match(summary, /presentation\.camera\.capture\(\)/, path)
+  }
+  for (const path of ["presentation.drawings.setScale", "presentation.drawings.setCrop"]) {
+    assert.match(summaryOf(path), /moves\s+to the nearest free spot/, path)
+  }
+})
+
+test("drawings.create says it never puts a drawing on a sheet and names the sheet calls", () => {
+  const summary = summaryOf("presentation.drawings.create")
+  assert.match(summary, /beside its source view/, summary)
+  assert.match(summary, /never on a sheet/, summary)
+  assert.match(summary, /sheets\.place\(sheetId, viewId\)/, summary)
+  assert.match(summary, /sheets\.placeDrawing\(sheetId, drawingId\)/, summary)
+})
+
+test("sheets.placeDrawing documents fitting, fit: false and one sheet per drawing", () => {
+  const summary = summaryOf("presentation.sheets.placeDrawing")
+  assert.match(summary, /scaled down to fit/, summary)
+  assert.match(summary, /never scaled up/, summary)
+  assert.match(summary, /`fit: false`/, summary)
+  assert.match(summary, /naming the\s+drawing, the sheet and the scale/, summary)
+  assert.match(summary, /without\s+`fit: false`\s+to fit it, or\s+use a larger sheet/, summary)
+  assert.doesNotMatch(summary, /use\s+`?sheets\.place`?\s+to\s+fit/, summary)
+  assert.match(summary, /reports the architectural scale/, summary)
+})
+
+// Without a position the host puts the drawing at the sheet centre or the nearest free spot,
+// and only centres it over other drawings (reporting overlaps: true) when there is none.
+const NO_STACK = /lands\s+on\s+top/
+const FREE_SPOT = /nearest\s+free\s+spot/
+const CENTRED_WHEN_FULL = /no\s+free\s+spot[^.]*centred[^.]*`overlaps:\s*true`/
+const EXPLICIT_POSITION = /`position`[^.]*placed\s+as\s+given[^.]*`overlaps:\s*true`[^.]*not\s+moved/
+const DRAWINGS_ONLY = /only\s+other\s+drawings\s+count[^.]*text,\s+images\s+and\s+other\s+shapes/
+
+const assertPlacementLayout = (summary) => {
+  assert.doesNotMatch(summary, NO_STACK, summary)
+  assert.match(summary, FREE_SPOT, summary)
+  assert.match(summary, CENTRED_WHEN_FULL, summary)
+  assert.match(summary, EXPLICIT_POSITION, summary)
+  assert.match(summary, DRAWINGS_ONLY, summary)
+}
+
+test("sheets.placeDrawing says where a drawing goes without a position and when it overlaps", () => {
+  assertPlacementLayout(summaryOf("presentation.sheets.placeDrawing"))
+})
+
+test("sheets.place says it is the call that puts a view on a sheet and fits it to that sheet", () => {
+  const summary = summaryOf("presentation.sheets.place")
+  assert.match(summary, /This is the call that puts a view on a\s+sheet/, summary)
+  assert.match(summary, /largest\s+standard scale at which it fits inside the target sheet's margin/, summary)
+  assert.match(summary, /never at a larger scale than the normal view drop/, summary)
+  assert.match(summary, /3D view[^.]*shrunk\s+evenly/, summary)
+  assertPlacementLayout(summary)
+})
+
+// The full JSDoc of sheets.place, for the @returns and @throws tags the summary leaves out.
+const placeJsDoc = () => {
+  const source = readFileSync(new URL("../src/api/presentation/sheets.ts", import.meta.url), "utf8")
+  const end = source.indexOf("public abstract place(")
+  const start = source.lastIndexOf("/**", end)
+  return source
+    .slice(start, end)
+    .replace(/\{@linkcode (\w+)\}/g, "$1")
+    .replace(/\s*\*\s*/g, " ")
+}
+
+test("sheets.place documents the scale and rescaled it returns", () => {
+  const doc = placeJsDoc()
+  assert.match(doc, /@returns[^@]*`scale` used \(`null` for a 3D view\)/, doc)
+  assert.match(doc, /@returns[^@]*`rescaled`/, doc)
+  assert.doesNotMatch(doc, /a host that reports them/, doc)
+})
+
+test("sheets.place documents PRECONDITION_FAILED for a view that does not fit", () => {
+  const doc = placeJsDoc()
+  assert.match(doc, /@throws[^@]*`PRECONDITION_FAILED`[^@]*smallest standard scale/, doc)
+  assert.match(doc, /@throws[^@]*`PRECONDITION_FAILED`[^@]*title block alone/, doc)
+})

package/test/errors.test.mjs

@@ -180,5 +180,6 @@ test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)",
     "PROPOSAL_SWITCH_BLOCKED",
     "INTERNAL",
     "UNKNOWN",
+    "HANDLE_STALE",
   ])
 })

package/test/presentationViewSettings.test.mjs

@@ -0,0 +1,85 @@
+// Node built-in test runner suite for the presentation view settings schemas.
+// Run: node --test test/
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import {
+  PluginPresentationViewSettings,
+  PluginPresentationViewsGetSettingsResult,
+  PluginPresentationViewsUpdateSettingsArgs,
+} from "../dist/index.js"
+
+const base = {
+  backgroundColor: "#ffffff",
+  colorMode: "monochrome",
+  viewMode: "isometric",
+  showAxis: true,
+  showEdges: true,
+  showLabels: false,
+  labels: [],
+}
+
+test("a plan's settings read back its cut range", () => {
+  const range = { cutPlaneHeight: 5.9055, viewDepthStorey: -1, showOverheadObjects: false }
+  assert.deepEqual(PluginPresentationViewsGetSettingsResult.parse({ ...base, ...range }), {
+    ...base,
+    ...range,
+  })
+})
+
+test("a view that is not a plan omits the range, and legacy callers still parse", () => {
+  const parsed = PluginPresentationViewSettings.parse(base)
+  for (const key of ["cutPlaneHeight", "viewDepthStorey", "showOverheadObjects"])
+    assert.equal(key in parsed, false)
+})
+
+test("a range patch survives the update args instead of being stripped", () => {
+  const parsed = PluginPresentationViewsUpdateSettingsArgs.parse({
+    id: "plan_1",
+    settings: { cutPlaneHeight: 4.72, viewDepthStorey: 0, showOverheadObjects: false },
+  })
+  assert.deepEqual(parsed.settings, {
+    cutPlaneHeight: 4.72,
+    viewDepthStorey: 0,
+    showOverheadObjects: false,
+  })
+})
+
+test("depth 0 is a real storey; depth null is rejected", () => {
+  const ground = PluginPresentationViewsUpdateSettingsArgs.parse({
+    id: "plan_1",
+    settings: { viewDepthStorey: 0 },
+  })
+  assert.equal(ground.settings.viewDepthStorey, 0)
+  assert.throws(() =>
+    PluginPresentationViewsUpdateSettingsArgs.parse({
+      id: "plan_1",
+      settings: { viewDepthStorey: null },
+    }),
+  )
+})
+
+test("a range patch rejects values no plan could use", () => {
+  for (const settings of [
+    { cutPlaneHeight: 0 },
+    { cutPlaneHeight: -3 },
+    { cutPlaneHeight: Number.POSITIVE_INFINITY },
+    { cutPlaneHeight: Number.NaN },
+    { viewDepthStorey: 1.5 },
+    { showOverheadObjects: "no" },
+  ])
+    assert.throws(
+      () => PluginPresentationViewsUpdateSettingsArgs.parse({ id: "plan_1", settings }),
+      undefined,
+      JSON.stringify(settings),
+    )
+})
+
+test("the existing label contradiction checks still apply beside a range patch", () => {
+  assert.throws(() =>
+    PluginPresentationViewsUpdateSettingsArgs.parse({
+      id: "plan_1",
+      settings: { showLabels: false, labels: ["areas"], cutPlaneHeight: 10 },
+    }),
+  )
+})