lineadraw 0.5.0 → 0.6.0

package/README.md

@@ -1,13 +1,15 @@
 # lineadraw
 
-Type definitions and marketplace tooling for [Linea](https://lineadraw.com)
-blocks and commands — the one devDependency a block/command repository
-needs. Zero runtime: your modules import types from `"lineadraw"`, and the
-Linea editor provides the real implementation when it runs them.
+[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.
 
 - **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.
@@ -65,10 +67,40 @@ 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.
+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
@@ -95,13 +127,24 @@ helpers) — the editor resolves both when executing your module.
 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     Is the Linea desktop app serving agents? port, open editors
+lineadraw editors    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. With `@lineadraw/sdk` installed as a devDependency,
-`manifest`/`check` additionally **dry-run every block** and render
-thumbnails; without it the CLI still fully works.
+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:
 
@@ -111,14 +154,179 @@ Collection name and owner come from your package.json:
 
 ## Using a marketplace in the editor
 
-In [the editor](https://lineadraw.com): **Library → Marketplace tab → +**
-and enter `owner/repo` (or `owner/repo@branch`). For a private repository,
+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`)
+
+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";
+
+const doc = newDrawing();
+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],
+    scale: 50 },                                 // annotations × drawing scale
+]);
+doc.createLayout("Plan 1:50", { sheet: "A3", viewport: { scale: "1:50" } });
+await doc.exportPng("check.png", { width: 1600 });  // verify by LOOKING at it
+await doc.save("plan.linea");
+await doc.exportPdf("plan.pdf");
+```
+
+### Conventions (read once, avoid every common bug)
+
+- **Units are millimeters, Y-up. Angles are radians CCW** — everywhere in the
+  object model and in `rotate()`. Draw 1:1 (a 6 m wall is 6000 mm); paper
+  scale lives in layout viewports (`"1:50"` strings via `parseScale`).
+- **Never write `.linea` JSON by hand.** Every mutation goes through
+  kernel-validated ops (`add`/`update`/`remove`/transforms); invalid input
+  throws with the failing object and field named.
+- **Style by layer**: unset `color`/`lineWidth`/`lineType` on objects inherit
+  from the layer. Layer names are unique (`addLayer` throws on duplicates)
+  and can be used instead of ids (`layer: "walls"`, query filters). Note:
+  `locked` layers are an editor-UI concept — the SDK does not block edits.
+- **Layer `print: false`** (plot flag) keeps a layer visible on screen and in
+  SVG/PNG but excludes it from PDF output — construction/guide layers.
+- **Opacity is byLayer too**: `opacity` (0..1) on a layer is the default for
+  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.
+- **Reads are detached snapshots**: `doc.document`, `doc.objects`,
+  `getObject`, `query()` return deep clones — mutating them does nothing.
+- **New documents are layout-less**; `exportPdf` of a layout-less document
+  falls back to one auto-fitted A3 page.
+- `transaction(fn)` groups edits into one undo step. `array(ids, count,
+  delta)`: `count` INCLUDES the originals; the returned ids are the copies.
+- An arc with `startAngle === endAngle` renders as a full circle.
+- There is no rectangle type — use a closed 4-point polyline.
+
+### API surface
+
+`newDrawing(name?)` / `drawingFromJson(text)` / `openDrawing(path)` → `Drawing`:
+
+- **Name**: `drawing.name` is the file name (set on `openDrawing`, updated
+  by `save(path)`); `newDrawing(name)` names it until it is saved. The
+  `.linea` JSON itself carries no name.
+
+- **Read**: `summary()`, `objects`, `layers`, `layouts`, `getObject`,
+  `query({ids, type, layer, color, lineType, content, bbox, inside, near, layout})`,
+  `measure(id)` (`bboxOf(ids)`, `length(id)`, `area(id)`), `listLayers()`,
+  `listLayouts()`, `listBlocks()`, `listCommands()`, `revision`
+- **Edit**: `add(objects, {layout?})`, `update(ids, patch)` or
+  `update([{id, ...patch}])`, `remove(ids)` (→ count), `reorder(ids,
+  "front" | "back" | {above} | {below})`, `transaction(fn)` (sync or async;
+  a throw rolls back), `undo()`, `redo()`, `setDimStyle`,
+  `setTextStyle`, `applyOps(ops)`, `ready()`
+- **Modules**: `await installBlocks(sources)` / `removeBlock(id)`,
+  `await installCommands(sources)` / `removeCommand(id)`,
+  `await setBlockDefinitions(sources)`, `await setCommands(sources)`
+- **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,
+  its declared `params` by name (`{ count: 3 }`; omitted ones take their
+  defaults, unknown names and wrong types throw); `runCommand(id, inputs?,
+  params?)` runs one of the document's own commands. Returns the script's
+  return value.
+- **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)
+- **Transform**: `move`, `rotate` (radians), `scale`, `mirror`, `copy`, `array`
+- **Layouts**: `createLayout(name, {sheet, scale, viewport, index})`,
+  `updateLayout(nameOrId, {name, sheet, printPalette})`, `removeLayout`,
+  `reorderLayouts`, `parseScale("1:50")`. `sheet` is `"A3"` (landscape when
+  creating, the current orientation when patching), `{ name: "A3",
+  orientation: "portrait" }`, or `{ width, height }` in mm.
+- **Export**: `renderSvg`/`exportSvg`, `renderPng`/`exportPng`, `await toDxf()`/`exportDxf`,
+  `toDwg`/`exportDwg` (DWG R2000–2018, default AC1027), `renderPdf`/`exportPdf`,
+  `toJson`/`save`
+- **Import (merge)**: `importDxf(path)`/`importDxfText(text)` (with
+  `unitOverride`), `importDwg(path)`/`importDwgData(bytes)` (DWG R13–R2018),
+  `importPdfData(arrayBuffer)`
+
+Full parameter docs are in the bundled `dist/index.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) ·
+`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:
+
+```ts
+import { defineBlock } from "lineadraw";
+import { polar, add } from "lineadraw/helpers";      // vector-math helpers
+
+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 } },
+  ],
+});
+```
+
+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.)
+
+### 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
+  `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
+  rasterizer (native resvg) and the DWG transcoder (bundled WebAssembly).
+- `renderSvg({ bbox })` culls objects outside the box (they are absent from the
+  file, not merely outside the viewBox).
+- Opening a document written by a NEWER Linea version throws instead of
+  loading lossily.
+- Dimensions validate their point counts per kind (linear ≥ 2, angular ≥ 3,
+  radial/diameter ≥ 2).
+
 ## Ecosystem
 
 - [Linea editor](https://lineadraw.com) — the browser CAD app that runs
@@ -126,8 +334,5 @@ the file.
 - [`lineadraw/lineadraw`](https://github.com/lineadraw/lineadraw) — the
   public collection: real blocks/commands to learn from, agent skill, and
   guides.
-- [`@lineadraw/sdk`](https://www.npmjs.com/package/@lineadraw/sdk) —
-  headless Node API over the same kernel (open/edit/render/export
-  `.linea` documents; also powers the CLI's block dry-runs).
 - [`@lineadraw/mcp`](https://www.npmjs.com/package/@lineadraw/mcp) — MCP
   server with the full editor as an in-chat app.