lineadraw 0.3.0 → 0.4.0

package/README.md

@@ -0,0 +1,133 @@
+# 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.
+
+- **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.
+- **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:
+
+```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.
+
+## 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.
+
+```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
+```
+
+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.
+
+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 → +**
+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.
+
+## Ecosystem
+
+- [Linea editor](https://lineadraw.com) — the browser CAD app that runs
+  these modules.
+- [`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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lineadraw",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Type definitions and marketplace tooling for Linea blocks and commands",
   "license": "MIT",
   "author": "Mikhail Koshelev",
@@ -11,17 +11,14 @@
   },
   "exports": {
     ".": {
-      "types": "./lineadraw.d.ts",
-      "default": "./main.js"
+      "types": "./lineadraw.d.ts"
     },
     "./helpers": {
-      "types": "./lineadraw.d.ts",
-      "default": "./main.js"
+      "types": "./lineadraw.d.ts"
     }
   },
   "files": [
     "lineadraw.d.ts",
-    "main.js",
     "bin",
     "lib",
     "templates"

package/templates/README.md

@@ -12,7 +12,7 @@ catalog (`.lineadraw/marketplace.json`).
 
 ## Using it in the editor
 
-Library → Blocks (or Commands) → Marketplace scope → add this repository
+Library → Marketplace tab → + → add this repository
 as `owner/repo`. For a private repository, create a fine-grained personal
 access token with read-only Contents access to just this repository and
 paste it in the add dialog — it is stored only on that device.