@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/types.ts

@@ -1,16 +1,16 @@
-/**
- * A unique identifier for a component in the Snaptrude scene.
- *
- * Component IDs are returned by entity creation methods (e.g.
- * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
- * query and transform methods throughout the API.
- */
-export type ComponentId = string
-
-/**
- * Return type for a plugin API method.
- *
- * Methods that require a host round-trip return `Promise<T>`,
- * while pure local computations may return `T` directly.
- */
-export type PluginApiReturn<T> = Promise<T> | T
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string
+
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T

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)
+})