lineadraw 0.9.0 → 0.11.0

package/README.md

@@ -59,9 +59,13 @@ await doc.exportPdf("plan.pdf");
   its objects; an object's own `opacity` overrides it. Paints across canvas,
   SVG, and PDF; DXF/DWG export drops it (no direct mapping).
 - **Annotation scale is per-object**: for a 1:N drawing set the top-level
-  `scale: N` on text, dimensions, and hatches, keeping `textHeight` at
-  paper size (2.5 body / 3.5 / 5 titles). `scale` is NOT a `styleOverride`
-  key; `add`/`update` reject it there.
+  `scale: N` on text, dimensions, and hatches, keeping the text height
+  at paper size (2.5 body / 3.5 / 5 titles). `scale` is NOT a
+  `styleOverride` key; `add`/`update` reject it there.
+- **One shape per field.** Style keys of a text, table or dimension
+  (`textHeight`, `font`, `bold`, `arrowSize`, …) live in `styleOverride`
+  (or a named style via `styleId`), never at the top level; a hidden layer
+  is `visible: false`. Unknown fields throw, naming where they belong.
 - **Reads are detached snapshots**: `doc.document`, `doc.objects`,
   `getObject`, `listObjects()` return deep clones — mutating them does nothing.
 - **New documents are layout-less**; `exportPdf` of a layout-less document
@@ -113,7 +117,9 @@ appended when missing):
   configuration, never written to the file.
 - **Scripts**: `await runScript(source, inputs?, params?)` runs a
   `defineCommand` module (the same one the editor palette runs) headlessly
-  as ONE undo step — its declared `inputs` (points) are supplied up front,
+  as ONE undo step — its declared `inputs` are supplied up front (by name
+  for an inputs table: `{ origin: [0, 0], doors: [id] }`; points in order
+  for labels),
   its declared `params` by name (`{ count: 3 }`; omitted ones take their
   defaults, unknown names and wrong types throw); `runUserCommand(id, inputs?,
   params?)` runs one of the document's own commands. Returns the script's
@@ -144,7 +150,10 @@ Full parameter docs are in the bundled `dist/sdk.d.ts` JSDoc.
 
 `line` (a, b) · `polyline` (points with optional bulge, closed) · `circle` ·
 `arc` (CCW start→end) · `ellipse` (center, majorAxis vector, ratio) ·
-`point` (p) · `hatch` (loops — outer + holes, even-odd; fill solid/pattern/lines) ·
+`point` (p) · `hatch` (loops — outer + holes, even-odd; each loop a closed
+chain of `edges`: `line`, `arc`, `ellipse` or `spline`, with the fields of that
+object type — a circle, ellipse or closed spline is one edge; `hatchLoop(points)`
+builds a polygon / bulged loop; fill solid/pattern/lines) ·
 `text` (position, content; **default alignment center/center**; optional
 leaderLines with the arrowhead at index 0) · `dimension` (linear/angular/
 radial/diameter; linear: `offset` is the signed distance of the dimension
@@ -260,16 +269,32 @@ export default defineBlock({
   params: [
     { name: "kind", type: "enum", default: "rock", options: ["rock", "ground"] },
   ],
-  place: ["Start point", "End point"], // one point pick per label, in order
-  draw: ({ params, inputs: [start, end] }) => {
+  // What the user picks at insertion, read by name in `draw`.
+  inputs: [
+    { name: "start", type: "point", label: "Start point" },
+    { name: "end", type: "point", label: "End point" },
+  ],
+  draw: ({ params, inputs: { start, end } }) => {
     params.kind; // "rock" | "ground" — inferred from the params table
     return [{ type: "line", a: start, b: end }];
   },
 });
 ```
 
-Notable optional members: `place` may instead be an interactive
-`({ params, pickPoint, pickObject })` function run once at insertion;
+Input kinds: `point`; `points` — a chain picked until Enter (`min`,
+`max`, `closed` for a polygon) arriving as `Vec2[]`; `object` / `objects`
+— picked objects filtered by `types` (`["line", "polyline"]`), arriving in
+`draw` as the objects themselves (re-evaluated when they change; a
+deleted one is `null` / dropped). `point` and `object` may be `optional`
+(Enter skips). The first point is the pivot. Instances store their inputs
+by name, so reordering or adding inputs never breaks placed instances —
+removing or renaming one does. (The older `place: ["Start", "End"]` labels
+form, with `draw` reading `inputs` as an array, still works.)
+
+Notable optional members: `place` — an interactive
+`({ params, pickPoint, pickPoints, pickObject, pickObjects })` function run
+once at insertion, for conditional or chained picks; with an `inputs`
+table it returns the inputs by name;
 `dependencies` lists ids of blocks your `draw` emits instances of (installs
 pull them along); `paramVisibility({ params })` hides property rows;
 `previewInputs` curates the inputs used for thumbnails. Units are
@@ -294,6 +319,26 @@ Parameter types (the same rows serve a command's `params`):
 - `label` — a section heading (no value); `row` — 2–3 compact params on one
   panel row (`items`, each label a short prefix like "W"); its items are
   ordinary flat params (`params.w`).
+- `data` — structured data the block owns: any JSON value, typed by its
+  default (`default: {} as Record<string, Wall>`). It has no Properties row;
+  handles, handle menus and actions edit it (agents set it like any param).
+
+Geometry helpers come from `"lineadraw/helpers"` — vector math
+(`add`, `sub`, `scale`, `rotate`, `polar`, …) and polygon booleans:
+`union(...polygons)`, `difference(subject, ...clips)`,
+`intersection(...polygons)`. A polygon is a ring of points, or rings with
+holes (first the outer boundary). The result is a flat list of rings,
+ready for closed polylines or ONE hatch, which fills even-odd so holes
+stay holes:
+
+```ts
+const solid = union(...walls.map(wallRect)); // overlapping walls → clean outlines
+return [
+  { type: "hatch", loops: solid.map(hatchLoop), // a ring → line edges
+    fill: { kind: "pattern", name: "ANSI31", angle: 0, scale: 20 } },
+  ...solid.map((points) => ({ type: "polyline", points, closed: true })),
+];
+```
 
 Every param may carry a `hint` (the label's tooltip). An instance that
 overrides a param shows "Reset" beside it in Properties, back to your
@@ -302,10 +347,94 @@ default. `draw` also receives
 empty or unknown id → the first), for blocks that lay out with real text
 sizes.
 
+#### Hosted blocks
+
+A block can LIVE ON another instance: a door on a floor plan. Give it a
+`host` input; it then draws in the host's frame (moving, rotating and
+copying with it, and deleted with it), and the two talk through
+`expose`, JSON each publishes from its OWN params:
+
+```ts
+// The plan publishes its walls and cuts them where its openings say.
+expose: ({ params }) => ({ walls: wallTable(params) }),
+draw: ({ params, hosted }) => {
+  const cuts = hosted.map((h) => h.exposed?.cut).filter(Boolean);
+  return wallSolids(params, cuts);
+},
+
+// A door: picked by clicking a plan's wall; `attach` turns the click
+// (plan-local) into its params.
+inputs: [{ name: "plan", type: "host", types: ["@my-blocks/floor-plan"] }],
+expose: ({ params }) => ({ cut: { wall: params.wall, at: params.at, width: params.width } }),
+attach: ({ host, point }) => nearestWall(host.walls, point), // → { wall, at }
+draw: ({ params, host }) => doorLeaf(host.walls[params.wall], params),
+```
+
+`expose` never sees the host or what's on it, so the two can't loop
+(ADR 0008). What a host publishes and what its openings read is a
+contract between the modules: document it.
+
+A hosted block has no host in Library / marketplace previews. Give it a
+stand-in with `previewHost`: the JSON a host's `expose` would return.
+The preview runs `attach` as if the host were clicked at its origin, and
+`draw` gets the stand-in as `host` (the save-time dry run uses it too):
+
+```ts
+previewHost: { preview: true, walls: { A: { a: [-1500, 0], b: [1500, 0], t: 200 } } },
+// …and in draw, `host.preview` can add context: a stretch of wall.
+```
+
+#### Handles and actions
+
+`handles({ params, inputs })` returns the handles a selected instance
+shows, in block-local coordinates. It re-runs as values change, so a
+handle can sit at the current width:
+
+```ts
+handles: ({ params }) => [
+  // Drag along local X: the distance becomes `width` (clamped to its min/max).
+  { id: "width", at: [params.width, 0], shape: "triangle",
+    along: { origin: [0, 0], direction: [1, 0] }, param: "width" },
+  // A button: one click, one undo step.
+  { id: "flip", at: [params.width / 2, 150], fixed: true, icon: "flip-horizontal",
+    click: ({ params }) => ({ params: { swing: params.swing === "left" ? "right" : "left" } }) },
+  // A line handle (shown while hovered) with a hover menu.
+  { id: "wall", kind: "line", from: [0, 0], to: [params.width, 0], fixed: true,
+    menu: ["thickness",
+      { field: { type: "boolean", label: "Enabled" }, value: !params.off,
+        set: (on) => ({ params: { off: !on } }) }],
+    actions: [{ label: "Reset", icon: "x", run: () => ({ params: { off: false } }) }] },
+],
+// The instance's context menu (right-click): pick a point, then run.
+actions: [
+  { label: "Add mark", pick: "point",
+    run: ({ params, point }) => ({ params: { marks: [...params.marks, [point.x, point.y]] } }) },
+],
+```
+
+A handle has ONE drag behaviour: `param` (the constrained value → a number
+param), `input` (moves a point input, replacing its default handle), or
+`drag` (a function returning a patch). Otherwise it is `fixed`. The
+constraint is free, `along` an axis (value = distance) or `around` a
+centre (value = angle in radians). A line handle moves along its normal by
+default. `click` turns it into a button. Shapes are `square`, `circle`,
+`diamond`, `triangle`, `arrow`, `double-arrow`, `plus` and `minus`, and `icon` names a
+lucide glyph from a small set. Handle functions and actions return a PATCH
+— `{ params?, inputs? }`, with inputs by name and block-local — and never
+mutate anything. Each applies as one undo step. The save-time dry run
+checks every handle record.
+
 ### Writing a command
 
 A command is a macro with a single `defineCommand` default export. Its
-whole run is one undo step; Esc during a pick reverts cleanly. A
+whole run is one undo step; Esc during a pick reverts cleanly. Its
+`inputs` table is the same one blocks declare; `object` / `objects` inputs
+take the current selection when it fits (types and count) and arrive as
+ids. To ask more DURING the run (the next question depends on the last
+answer), use `editor.pickPoint` / `pickObject` / `prompt`, or
+`editor.ask(paramsTable, { title })` for several fields in one dialog —
+and declare `requiresEditor: true`, so CLI / agent runs refuse the command
+up front instead of failing halfway. A
 `params` table (the same rows a block's `params` uses) is asked for in a
 dialog before the run and arrives typed as `ctx.params`; headless callers
 pass it by name.
@@ -317,11 +446,12 @@ import { defineCommand } from "lineadraw";
 export default defineCommand({
   id: "@my-blocks/circle-here",
   name: "Circle here",
-  inputs: ["Center point"],
+  inputs: [{ name: "center", type: "point", label: "Center point" }],
   params: [{ name: "radius", type: "number", default: 10, min: 0.1 }],
-  // `inputs` are picked in the editor (or passed by a headless caller),
-  // `params` asked for in a dialog; `editor` is absent when headless.
-  run: async ({ document, editor, inputs: [center], params }) => {
+  // `inputs` are picked in the editor (or passed by name by a headless
+  // caller: { center: [0, 0] }), `params` asked for in a dialog; `editor`
+  // is absent when headless.
+  run: async ({ document, editor, inputs: { center }, params }) => {
     document.add([{ type: "circle", center, radius: params.radius }]);
     editor?.toast("Done", "success");
   },
@@ -371,11 +501,11 @@ Collection name and owner come from your package.json:
 
 ### Using a marketplace in the editor
 
-In [the editor](https://lineadraw.com): **Library → Marketplace tab → the
-gear button (Manage marketplaces…) → Add a marketplace** and enter
-`owner/repo` (or `owner/repo@branch`). For a private repository,
+In [Linea](https://lineadraw.com): **App settings → Marketplaces → Add a
+marketplace** (the gear in Library → Marketplace opens the same tab) and
+enter `owner/repo` (or `owner/repo@branch`). For a private repository,
 create a fine-grained personal access token with read-only Contents access
-to just that repository and paste it in the add dialog — it is stored only
+to just that repository and paste it under "Add an access token" — it is stored only
 on that device. Installing embeds the module (and its declared dependency
 closure) in the document, so drawings keep working offline and travel with
 the file.
@@ -386,8 +516,9 @@ the file.
 lineadraw status     App version, port, the open drawings: id, name, path, kind, dirty
 lineadraw open <file.linea>            Open a file in a new window
 lineadraw close [--editor <x>] [--discard]
-lineadraw call <operation> ['<json>'] [--editor <x>]   Run one linea_* operation
-lineadraw tools      The operations the bridge offers
+lineadraw call <operation> ['<json>' | @file.json | -] [--editor <x>]   Run one linea_* operation
+lineadraw tools [<operation>]   The operations the bridge offers, or one's argument schema
+lineadraw --version
 ```
 
 These commands talk to the running Linea desktop app on `127.0.0.1:7431`
@@ -401,6 +532,9 @@ SDK's [`connectEditors()`](#running-editors-the-desktop-bridge).
 npx lineadraw call linea_add_objects '{"objects":[{"type":"circle","center":[0,0],"radius":500}]}'
 ```
 
+The arguments can also come from a file (`@args.json`) or stdin (`-`),
+which spares quoting JSON in PowerShell or cmd.
+
 ## Ecosystem
 
 - [Linea](https://lineadraw.com) — the CAD editor, on the desktop and on

package/bin/lineadraw.mjs

@@ -12,6 +12,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
   buildManifest,
   manifestJson,
@@ -35,12 +36,42 @@ Running editors (the Linea desktop app on 127.0.0.1:7431):
   status                                app version, port, the open drawings (id, name, path, kind, dirty)
   open <file.linea>                     open a file in a window of its own (returns its editor)
   close [--editor <x>] [--discard]      close an editor like its window's x
-  call <operation> ['<json>'] [--editor <x>]
-                                        run one linea_* operation (see tools)
-  tools                                 the operations the bridge offers
+  call <operation> ['<json>' | @file.json | -] [--editor <x>]
+                                        run one linea_* operation (see tools);
+                                        its arguments as JSON text, a file, or stdin
+  tools [<operation>]                   the operations the bridge offers, or
+                                        one operation's argument schema
 
 The desktop's bridge.json (port, agent token) is read automatically;
-LINEA_BRIDGE_TOKEN or --token override the token, --port the port.`;
+LINEA_BRIDGE_TOKEN or --token override the token, --port the port.
+
+  --version  the lineadraw version     --help  this text`;
+
+const VERSION = JSON.parse(
+  readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+    "utf8",
+  ),
+).version;
+
+/** `call`'s arguments: JSON text, `@file.json`, or `-` for stdin (quoting
+ * JSON on a Windows command line is a fight best not picked). */
+const readCallArgs = (spec) => {
+  if (spec === undefined) return {};
+  const text =
+    spec === "-"
+      ? readFileSync(0, "utf8")
+      : spec.startsWith("@")
+        ? readFileSync(resolve(spec.slice(1)), "utf8")
+        : spec;
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new Error(
+      `call: the arguments are not valid JSON (${e instanceof Error ? e.message : e})`,
+    );
+  }
+};
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -90,12 +121,20 @@ const bridgeCommand = async (cmd, positional, flags) => {
       const [operation, json] = positional;
       if (!operation)
         throw new Error("call needs an operation name (see `lineadraw tools`)");
-      return b.call(operation, json === undefined ? {} : JSON.parse(json), {
-        editor,
-      });
+      return b.call(operation, readCallArgs(json), { editor });
+    }
+    case "tools": {
+      const tools = await b.tools();
+      const wanted = positional[0];
+      if (wanted === undefined)
+        return tools.map(({ name, description }) => ({ name, description }));
+      const tool = tools.find((t) => t.name === wanted);
+      if (!tool)
+        throw new Error(
+          `Unknown operation "${wanted}". \`lineadraw tools\` lists them.`,
+        );
+      return tool;
     }
-    case "tools":
-      return b.tools();
     default:
       throw new Error(`Unknown command: ${cmd}\n\n${USAGE}`);
   }
@@ -184,8 +223,19 @@ switch (command) {
     }
     break;
   }
+  case "--version":
+  case "-v":
+    console.log(VERSION);
+    break;
+  case "--help":
+  case "-h":
+  case "help":
+    console.log(USAGE);
+    break;
   default: {
-    if (!BRIDGE_COMMANDS.includes(command)) fail(USAGE);
+    if (command === undefined) fail(USAGE);
+    if (!BRIDGE_COMMANDS.includes(command))
+      fail(`Unknown command "${command}".\n\n${USAGE}`);
     const { positional, flags } = parseArgs(args.slice(1));
     try {
       const result = await bridgeCommand(command, positional, flags);

package/dist/bridge.d.ts

@@ -78,6 +78,7 @@ interface LineaBridge {
     tools(): Promise<{
         name: string;
         description?: string;
+        inputSchema?: unknown;
     }[]>;
     /** Open a `.linea` file in a window of its own (an absolute path, or one
      * relative to the current directory); resolves once it has loaded. */

package/dist/bridge.js

@@ -4,7 +4,7 @@ import {
   bridgeFilePath,
   connectEditors,
   createBridge
-} from "./chunk-L2CWZAKW.js";
+} from "./chunk-RNA2RDGL.js";
 import "./chunk-PZ5AY32C.js";
 export {
   BridgeError,