lineadraw 0.8.0 → 0.10.0

package/README.md

@@ -1,178 +1,29 @@
 # lineadraw
 
-[Linea](https://lineadraw.com) for Node: the headless drawing SDK, the
-typings for blocks and commands, and the marketplace CLI — the one
-dependency a script, an agent, or a block/command repository needs.
+[Linea](https://lineadraw.com) for Node — one package, four jobs:
 
-- **Typings** — `lineadraw.d.ts` makes `import { defineBlock } from
-  "lineadraw"` and `import { … } from "lineadraw/helpers"` type-check in
-  any editor/CI, with parameter types inferred into your `draw` function.
-- **SDK** — `import { openDrawing } from "lineadraw/sdk"`: open, edit,
-  render and export `.linea` documents headlessly
-  ([below](#headless-sdk-lineadrawsdk)).
-- **CLI** — `lineadraw manifest | check | init` turns any repository into
-  a Linea **marketplace**: a git repo the editor can browse and install
-  blocks/commands from.
-
-## Quick start
-
-Scaffold a fresh marketplace repository:
-
-```bash
-npm create lineadraw my-blocks
-```
-
-Or add the structure to an existing project:
+| Job | What you get | Entry point |
+| --- | --- | --- |
+| [**Drawing SDK**](#1-drawing-sdk) | Open, create, edit, render and export `.linea` / DXF / DWG / PDF / SVG / PNG headlessly — for scripts, agents and batch tools. Also drives drawings open in the desktop app. | `import { openDrawing } from "lineadraw/sdk"` |
+| [**Extension development**](#2-extension-development) | Typings for parametric **blocks** and macro **commands**: `defineBlock` / `defineCommand` type-check in any editor, with parameter types inferred. | `import { defineBlock } from "lineadraw"` |
+| [**Marketplace management**](#3-marketplace-management) | Turn a git repo into a Linea **marketplace** the editor can browse and install from: scaffold it, validate every module, generate the catalog, check it in CI. | `lineadraw init` · `manifest` · `check` |
+| [**CLI for the desktop app**](#4-cli-for-the-running-desktop-app) | Talk to the running Linea desktop app from a terminal: list open drawings, open and close files, run any `linea_*` operation. | `lineadraw status` · `open` · `close` · `call` · `tools` |
 
 ```bash
-npm i -D lineadraw
-npx lineadraw init
-```
-
-Either way you get `blocks/` and `commands/` folders, a `tsconfig.json`
-wired to the typings, a sample block, a CI workflow, and a generated
-catalog (`.lineadraw/marketplace.json`) — the repo is addable in the
-editor from the first push.
-
-## Writing a block
-
-A block is one module with a single `defineBlock` default export:
-typed parameters in, geometry out.
-
-```ts
-// blocks/surface.block.ts
-import { defineBlock } from "lineadraw";
-
-export default defineBlock({
-  // The id is the block's identity everywhere: @<collection>/<slug>.
-  // Re-publishing the same id updates installed copies in place.
-  id: "@my-blocks/surface",
-  name: "Surface",
-  version: "1.0.0",
-  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] }) => {
-    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;
-`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
-millimeters, Y-up, angles in radians CCW.
-
-Parameter types (the same rows serve a command's `params`):
-
-- `number` — `min`/`max`, `integer`, `step`, `prefix`/`suffix` ("1:",
-  "mm"), `presets` (standard values in the field's dropdown).
-- `string` — `placeholder`, `multiline`, `presets`.
-- `boolean` (`display: "toggle"` — a toggle button showing the label,
-  compact in a row), `enum` (`options`, each optionally with a `swatch:
-  "#rrggbb"` color square; `display: "buttons"` — a segmented toggle group
-  for short choices, falling back to a dropdown when it doesn't fit),
-  `color` (`"#rrggbb"`, `presets` = a palette).
-- `numberList` (`number[]`, typed Tekla-style: `"0 2*7200"` →
-  `[0, 7200, 7200]`) and `stringList` (`string[]`: `'A "B 2"'` →
-  `["A", "B 2"]`), both with `presets` and `placeholder` (shown while
-  empty).
-- Pickers over the document's resources, valued by id / name:
-  `textStyle`, `dimStyle`, `font`, `lineType`, `hatchPattern`.
-- `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`).
-
-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
-default. `draw` also receives
-`styles`: `styles.text(id)` / `styles.dim(id)` give a document style (an
-empty or unknown id → the first), for blocks that lay out with real text
-sizes.
-
-## 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
-`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.
-
-```ts
-// commands/circle-here.cmd.ts
-import { defineCommand } from "lineadraw";
-
-export default defineCommand({
-  id: "@my-blocks/circle-here",
-  name: "Circle here",
-  run: async ({ document, pickPoint, prompt, showToast }) => {
-    const center = await pickPoint("Center point");
-    const r = await prompt("Radius");
-    document.add([{ type: "circle", center, radius: Number.parseFloat(r) }]);
-    showToast("Done", "success");
-  },
-});
-```
-
-Imports are limited to `"lineadraw"` and `"lineadraw/helpers"` (geometry
-helpers) — the editor resolves both when executing your module.
-
-## The CLI
-
-```
-lineadraw manifest   Validate all modules and write .lineadraw/marketplace.json
-lineadraw check      Validate without writing; fail if the committed manifest is stale
-lineadraw init       Add the marketplace structure to the current npm project
-
-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_* tool
-lineadraw tools      The operations the bridge offers
-```
-
-The bridge commands talk to the running Linea desktop app on
-`127.0.0.1:7431` (the app's `bridge.json` supplies the port and the agent
-token; `--port`, `--token` and `LINEA_BRIDGE_TOKEN` override) — see
-docs/desktop-bridge.md in the linea repo.
-
-The manifest is deterministic (repo-relative paths, no git metadata), so
-`check` compares the parsed JSON (formatting, a trailing newline or CRLF
-line endings never make it stale) — the included CI workflow runs it on every
-push and PR. `manifest`/`check` also **dry-run every block** through
-`lineadraw/sdk` and render thumbnails.
-
-Collection name and owner come from your package.json:
-
-```json
-{ "lineadraw": { "marketplaceName": "My blocks", "marketplaceOwner": "Me" } }
+npm i lineadraw                  # the SDK in a script or tool
+npm i -D lineadraw               # typings + CLI in a block/command repository
+npm create lineadraw my-blocks   # a fresh marketplace repository
 ```
 
-## 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,
-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
-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.
+Requires Node.js >= 20. Units everywhere are millimeters, Y-up, angles in
+radians CCW.
 
-## Headless SDK (`lineadraw/sdk`)
+## 1. Drawing SDK
 
 A script-friendly API over the Linea CAD kernel: open, create, query, edit,
 render, and import/export `.linea` documents headlessly in Node — no browser,
 no server. Built for agents, CLIs, and batch tooling.
 
-```bash
-npm i lineadraw
-```
-
 ```js
 import { newDrawing, openDrawing } from "lineadraw/sdk";
 
@@ -243,8 +94,7 @@ appended when missing):
   a throw rolls back), `undo()`, `redo()`, `applyOps(ops)`, `ready()`
 - **Styles** (by name or id): `listTextStyles()`, `addTextStyle({name, …})`,
   `updateTextStyle(nameOrId, patch)`, `removeTextStyle(nameOrId)` (refused
-  while objects use it) — the same four for `DimStyle`; `setTextStyle` /
-  `setDimStyle` remain as deprecated aliases of update
+  while objects use it) — the same four for `DimStyle`
 - **Line types / hatch patterns** (the document's own definitions, by
   name, resolved ahead of the built-in catalogue): `listLineTypes()`,
   `addLineTypes([{name, dashesMm}])`, `updateLineType(name, patch)`,
@@ -263,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
@@ -271,8 +123,10 @@ appended when missing):
 - **Layers**: `addLayer`, `updateLayer(nameOrId, patch)`,
   `removeLayer(nameOrId)` (must be empty and not current),
   `reorderLayers(order)`, `setCurrentLayer(nameOrId)`
-- **Assets**: `addAsset(dataUrl) → assetId` (for `image` objects;
-  content-keyed), `removeAsset(id)` (refused while referenced)
+- **Assets**: `addAsset(dataUrl) → assetId` (content-keyed; an embedded
+  reference names it), `listAssets()`, `removeAsset(id)` (refused while
+  referenced)
+- **Settings**: `updateSettings(patch)` (document settings, e.g. units)
 - **Transform**: `move`, `rotate` (radians), `scale`, `mirror`, `copy`, `array`
 - **Layouts**: `addLayout(name, {sheet, scale, viewport, index})`,
   `updateLayout(nameOrId, {name, sheet, printPalette})`, `removeLayout`,
@@ -286,13 +140,13 @@ appended when missing):
   `unitOverride`), `importDwg(path)`/`importDwgData(bytes)` (DWG R13–R2018),
   `importPdfData(arrayBuffer)`
 
-Full parameter docs are in the bundled `dist/index.d.ts` JSDoc.
+Full parameter docs are in the bundled `dist/sdk.d.ts` JSDoc.
 
 ### Object types
 
 `line` (a, b) · `polyline` (points with optional bulge, closed) · `circle` ·
 `arc` (CCW start→end) · `ellipse` (center, majorAxis vector, ratio) ·
-`hatch` (loops — outer + holes, even-odd; fill solid/pattern/lines) ·
+`point` (p) · `hatch` (loops — outer + holes, even-odd; 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
@@ -301,46 +155,70 @@ line from points[0] (left of the measuring direction positive) and
 signed arc radius; `labels[i]` place and word each segment's text —
 `along`/`across` in mm, unset = automatic, `content` with `{value}` for the
 measurement; linear with >2 points = chain) · `block` (instances of script definitions) ·
-`viewport` (layouts only) · `image` (placement of an asset).
+`table` (columns, rows, cells) · `comment` (a review bubble, never
+printed) · `reference` (a linked or embedded file: `.linea`, DXF, DWG,
+PDF, PNG/JPEG — a picture is a reference whose `source` is
+`{ kind: "asset", assetId }`) · `viewport` (layouts only).
+
+### Block definitions in a document
+
+`document.blockDefinitions` is an array of ES-module **source strings** —
+the same `defineBlock` modules described under
+[Extension development](#2-extension-development). Load them with
+`await doc.setBlockDefinitions([...sources])` or `addBlockDefinitions`
+(async, so the script transpiler is loaded and block geometry is
+definitive when it resolves), then place instances with
+`add([{ type: "block", definitionId }])`. An instance's first point input
+is its pivot: `draw` sees inputs localized to it, and the instance's
+`rotation`/`scale` apply about it.
 
-### Block scripts
+### Running editors (the desktop bridge)
 
-`document.blockDefinitions` is an array of ES-module **source strings**
-(`await doc.setBlockDefinitions([...sources])` — async so the script
-transpiler is loaded and block geometry is definitive when it resolves).
-A block is one `defineBlock` call:
+`Drawing` works on a document in your own process. To work on a drawing
+that is OPEN in the Linea desktop app (or a web tab paired with it), connect
+to the app's bridge on `127.0.0.1:7431`:
 
 ```ts
-import { defineBlock } from "lineadraw";
-import { polar, add } from "lineadraw/helpers";      // vector-math helpers
+import { connectEditors } from "lineadraw/sdk";
 
-export default defineBlock({
-  id: "chair",                                   // instances reference this
-  name: "Chair",
-  params: [{ name: "width", type: "number", default: 450 }],
-  draw: ({ params }) => [
-    // Plain object DTOs in block-local coordinates; params.width: number.
-    { type: "line", a: { x: 0, y: 0 }, b: { x: params.width, y: 0 } },
-  ],
+const linea = await connectEditors(); // port + agent token from the app's bridge.json
+const [first] = await linea.editors(); // { id, name, path, kind, readOnly, dirty }
+const plan = linea.editor(first.id); // by document id, file path or unique name
+
+// One linea_* operation = one undo step in that editor.
+await plan.call("linea_add_objects", {
+  objects: [{ type: "circle", center: [0, 0], radius: 500 }],
 });
+
+// A whole command module, run INSIDE the editor against the full Drawing
+// API: one round trip, one undo step. `inputs` / `params` answer the
+// module's declared ones.
+const result = await plan.runScript(
+  `import { defineCommand } from "lineadraw";
+   export default defineCommand({
+     id: "count-lines",
+     name: "Count lines",
+     run: ({ document }) => document.listObjects({ type: "line" }).length,
+   });`,
+);
+
+const other = await linea.open("details.linea"); // a window of its own
+await linea.editor(other.id).close({ discard: true });
 ```
 
-Optional members: `place` — an array of point labels (one pick per label)
-or an interactive `({ params, pickPoint, pickObject })` function run once
-at insertion (default is one insertion point) — and
-`paramVisibility({ params })` (hides property rows). `params` may be the
-table literal or a zero-arg function returning it. Imports are limited to
-`"lineadraw"` and `"lineadraw/helpers"`. The instance's first point input
-is its pivot: `draw` sees inputs localized to it, and instance
-`rotation`/`scale` apply about it. (Plain named exports — incl. the
-pre-rename `main`/`defineInput` names — remain evaluatable as the frozen
-wire form.)
+The operations are the same `linea_*` catalog the MCP server and the CLI
+offer (`await linea.tools()` lists them). Failures throw a `BridgeError`
+whose `code` says why: `unreachable` (the app isn't running),
+`ambiguous` (several editors are open and none was named — `details`
+lists them), `noSuchEditor`, `readOnly`, `validation`… The connection
+options (`port`, `token`, `bridgeFile`) override what bridge.json says;
+`LINEA_BRIDGE_TOKEN` supplies a token too.
 
 ### Interchange notes
 
 - DXF/DWG export flattens semantics: block instances are exported as their
-  evaluated geometry (no `INSERT` reuse) and `image` objects are skipped
-  (DXF images reference external files). The export result reports both in
+  evaluated geometry (no `INSERT` reuse), and embedded references are
+  skipped (DXF can't embed a file). The export result reports both in
   `skipped`.
 - PDF import extracts vector strokes and text runs (dimensions arrive as
   exploded geometry). pdf.js loads lazily on first use, as do the PNG
@@ -352,10 +230,306 @@ wire form.)
 - Dimensions validate their point counts per kind (linear ≥ 2, angular ≥ 3,
   radial/diameter ≥ 2).
 
+## 2. Extension development
+
+Blocks and commands are plain TypeScript (or JavaScript) modules. The
+package's `lineadraw.d.ts` types the two module names a script may import —
+`"lineadraw"` (`defineBlock`, `defineCommand`) and `"lineadraw/helpers"`
+(geometry helpers) — so authoring type-checks in VS Code, any other
+TypeScript-aware editor, and CI. The editor resolves both names when it
+runs your module; nothing else can be imported. `lineadraw init` writes a
+`tsconfig.json` wired to the typings.
+
+A module works on its own too: drop a `.block.ts` / `.cmd.ts` file onto the
+editor, or exercise it headlessly with the SDK
+(`await doc.addBlockDefinitions([source])`, `await doc.runScript(source)`).
+
+### Writing a block
+
+A block is one module with a single `defineBlock` default export:
+typed parameters in, geometry out.
+
+```ts
+// blocks/surface.block.ts
+import { defineBlock } from "lineadraw";
+
+export default defineBlock({
+  // The id is the block's identity everywhere: @<collection>/<slug>.
+  // Re-publishing the same id updates installed copies in place.
+  id: "@my-blocks/surface",
+  name: "Surface",
+  version: "1.0.0",
+  params: [
+    { name: "kind", type: "enum", default: "rock", options: ["rock", "ground"] },
+  ],
+  // 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 }];
+  },
+});
+```
+
+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
+millimeters, Y-up, angles in radians CCW.
+
+Parameter types (the same rows serve a command's `params`):
+
+- `number` — `min`/`max`, `integer`, `step`, `prefix`/`suffix` ("1:",
+  "mm"), `presets` (standard values in the field's dropdown).
+- `string` — `placeholder`, `multiline`, `presets`.
+- `boolean` (`display: "toggle"` — a toggle button showing the label,
+  compact in a row), `enum` (`options`, each optionally with a `swatch:
+  "#rrggbb"` color square; `display: "buttons"` — a segmented toggle group
+  for short choices, falling back to a dropdown when it doesn't fit),
+  `color` (`"#rrggbb"`, `presets` = a palette).
+- `numberList` (`number[]`, typed Tekla-style: `"0 2*7200"` →
+  `[0, 7200, 7200]`) and `stringList` (`string[]`: `'A "B 2"'` →
+  `["A", "B 2"]`), both with `presets` and `placeholder` (shown while
+  empty).
+- Pickers over the document's resources, valued by id / name:
+  `textStyle`, `dimStyle`, `font`, `lineType`, `hatchPattern`.
+- `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
+default. `draw` also receives
+`styles`: `styles.text(id)` / `styles.dim(id)` give a document style (an
+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. 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.
+
+```ts
+// commands/circle-here.cmd.ts
+import { defineCommand } from "lineadraw";
+
+export default defineCommand({
+  id: "@my-blocks/circle-here",
+  name: "Circle here",
+  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 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");
+  },
+});
+```
+
+## 3. Marketplace management
+
+A marketplace is a git repository of blocks and commands plus a generated
+catalog (`.lineadraw/marketplace.json`) that the editor reads.
+
+Scaffold a fresh one:
+
+```bash
+npm create lineadraw my-blocks
+```
+
+Or add the structure to an existing npm project:
+
+```bash
+npm i -D lineadraw
+npx lineadraw init
+```
+
+Either way you get `blocks/` and `commands/` folders, a `tsconfig.json`
+wired to the typings, a sample block, a CI workflow, the catalog, and
+`npm run manifest` / `npm run check` scripts — the repo is addable in the
+editor from the first push.
+
+```
+lineadraw manifest [--dir <path>]   Validate all modules and write .lineadraw/marketplace.json
+lineadraw check    [--dir <path>]   Validate without writing; fail if the committed manifest is stale
+lineadraw init     [--dir <path>]   Add the marketplace structure to the current npm project
+```
+
+`manifest` and `check` **dry-run every block** through `lineadraw/sdk` and
+bake preview thumbnails into the catalog. The manifest is deterministic
+(repo-relative paths, no git metadata), so `check` compares the parsed JSON
+— formatting, a trailing newline or CRLF line endings never make it stale.
+The included CI workflow runs it on every push and PR.
+
+Collection name and owner come from your package.json:
+
+```json
+{ "lineadraw": { "marketplaceName": "My blocks", "marketplaceOwner": "Me" } }
+```
+
+### Using a marketplace in the editor
+
+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 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.
+
+## 4. CLI for the running desktop app
+
+```
+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
+```
+
+These commands talk to the running Linea desktop app on `127.0.0.1:7431`
+(the app's `bridge.json` supplies the port and the agent token; `--port`,
+`--token` and `LINEA_BRIDGE_TOKEN` override). `--editor` names a drawing by
+document id, file path or unique name, and may be left out while only one
+is open. Each `call` is one undo step in that editor. From code, use the
+SDK's [`connectEditors()`](#running-editors-the-desktop-bridge).
+
+```bash
+npx lineadraw call linea_add_objects '{"objects":[{"type":"circle","center":[0,0],"radius":500}]}'
+```
+
 ## Ecosystem
 
-- [Linea editor](https://lineadraw.com) — the browser CAD app that runs
-  these modules.
+- [Linea](https://lineadraw.com) — the CAD editor, on the desktop and on
+  the web, that runs these modules.
+- [`create-lineadraw`](https://www.npmjs.com/package/create-lineadraw) —
+  `npm create lineadraw`, the marketplace scaffolder.
 - [`lineadraw/lineadraw`](https://github.com/lineadraw/lineadraw) — the
   public collection: real blocks/commands to learn from, agent skill, and
   guides.