lineadraw 0.9.0 → 0.10.0

package/README.md

@@ -113,7 +113,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
@@ -260,16 +262,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 +312,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((points) => ({ points })),
+    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 +340,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 +439,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 +494,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.