lineadraw 0.7.0 → 0.9.0

package/README.md

@@ -1,177 +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 }];
-  },
-});
+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
 ```
 
-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`):
+Requires Node.js >= 20. Units everywhere are millimeters, Y-up, angles in
+radians CCW.
 
-- `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` is a byte-for-byte diff — 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" } }
-```
-
-## 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.
-
-## 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";
 
@@ -180,7 +32,7 @@ const walls = doc.addLayer({ name: "walls", color: "#e8e8e8", lineWidth: 0.5 });
 doc.add([
   { type: "polyline", layerId: walls, closed: true,
     points: [[0, 0], [6000, 0], [6000, 3000], [0, 3000]] },
-  { type: "dimension", points: [[0, 0], [6000, 0]], offset: [0, -500],
+  { type: "dimension", points: [[0, 0], [6000, 0]], offset: -500,
     scale: 50 },                                 // annotations × drawing scale
 ]);
 doc.addLayout("Plan 1:50", { sheet: "A3", viewport: { scale: "1:50" } });
@@ -221,7 +73,11 @@ await doc.exportPdf("plan.pdf");
 
 ### API surface
 
-`newDrawing(name?)` / `drawingFromJson(text)` / `openDrawing(path)` → `Drawing`:
+`newDrawing(name?, options?)` / `drawingFromJson(text)` / `openDrawing(path, options?)`
+→ `Drawing`; `options.marketplaces` lists the marketplaces to search and
+install from (`{ kind: "github", spec: "owner/repo[@branch]", token? }` or
+`{ kind: "folder", folder }`, priority order; the public collection is
+appended when missing):
 
 - **Name**: `drawing.name` is the file name (set on `openDrawing`, updated
   by `save(path)`); `newDrawing(name)` names it until it is saved. The
@@ -238,11 +94,23 @@ await doc.exportPdf("plan.pdf");
   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)`,
+  `removeLineType(name)`; `listHatchPatterns()`,
+  `addHatchPatterns([{name, lines}])`, `updateHatchPattern(name, patch)`,
+  `removeHatchPattern(name)`
 - **Modules**: `await addBlockDefinitions(sources)` / `removeBlockDefinition(id)`,
   `await addUserCommands(sources)` / `removeUserCommand(id)`,
   `await setBlockDefinitions(sources)`, `await setCommands(sources)`
+- **Marketplaces**: `listMarketplaces()`, `await addMarketplaces(list)`
+  (verifies each catalog), `removeMarketplaces(names)`,
+  `await searchMarketplaces({ query?, kind?, marketplace? })` (entries with
+  install status), `await installMarketplaceEntries(ids, marketplace?)`
+  (declared block dependencies first, one undo step) — then insert a block
+  with `add([{ type: "block", definitionId }])`. Marketplaces are process
+  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,
@@ -253,8 +121,10 @@ await doc.exportPdf("plan.pdf");
 - **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`,
@@ -268,57 +138,85 @@ await doc.exportPdf("plan.pdf");
   `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; `offset` is a vector from points[0] to the dimension line;
-linear with >2 points = chain) · `block` (instances of script definitions) ·
-`viewport` (layouts only) · `image` (placement of an asset).
-
-### Block scripts
-
-`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:
+radial/diameter; linear: `offset` is the signed distance of the dimension
+line from points[0] (left of the measuring direction positive) and
+`rotation` an optional locked measuring direction; angular: `offset` is the
+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) ·
+`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.
+
+### Running editors (the desktop bridge)
+
+`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
@@ -330,10 +228,185 @@ 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"] },
+  ],
+  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",
+  inputs: ["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 }) => {
+    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 [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.
+
+## 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.