lineadraw 0.3.0 → 0.5.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/bin/lineadraw.mjs

@@ -11,8 +11,9 @@ import {
   manifestJson,
   MANIFEST_PATH,
   verifyWithSdk,
+  withThumbnails,
 } from "../lib/manifest.mjs";
-import { init } from "../lib/init.mjs";
+import { init, tsconfigLibWarning } from "../lib/init.mjs";
 
 const USAGE = `Usage: lineadraw <manifest|check|init> [--dir <path>]
 
@@ -21,7 +22,9 @@ const USAGE = `Usage: lineadraw <manifest|check|init> [--dir <path>]
   init      Add the marketplace structure to the current npm project
 
 With @lineadraw/sdk installed (devDependency), manifest and check also
-dry-run every block. The manifest content is identical either way.`;
+dry-run every block and bake preview thumbnails into the catalog — commit
+the manifest from an environment with the sdk installed (the CI template
+does) so check compares like with like.`;
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -40,16 +43,21 @@ const reportProblems = (problems) => {
 
 /** Validate everything (light + optional sdk dry-run); exits on failure. */
 const validatedManifest = async () => {
-  const { manifest, sources, problems } = buildManifest(dir);
-  const sdkResult = await verifyWithSdk(dir, manifest, sources);
+  const { manifest: base, sources, problems } = buildManifest(dir);
+  const sdkResult = await verifyWithSdk(dir, base, sources);
   const all = [...problems, ...sdkResult.problems];
   if (all.length > 0) {
     reportProblems(all);
     fail(`${all.length} problem(s) — nothing written.`);
   }
+  const manifest = withThumbnails(base, sdkResult.thumbnails);
   if (!sdkResult.ran)
     console.warn(
-      "The contents of blocks/commands were not dry-run because @lineadraw/sdk is not installed. Install it as a devDependency to enable this check.",
+      sdkResult.reason === "load-failed"
+        ? `Blocks were not dry-run: @lineadraw/sdk is installed but failed to load (${sdkResult.detail}). Try reinstalling it.`
+        : sdkResult.reason === "too-old"
+          ? "Blocks were not dry-run: the installed @lineadraw/sdk is too old for module validation. Update it to enable this check."
+          : "Blocks were not dry-run because @lineadraw/sdk is not installed. Install it as a devDependency to enable this check.",
     );
   return manifest;
 };
@@ -75,6 +83,8 @@ switch (command) {
       fail(
         `${MANIFEST_PATH} is ${committed === null ? "missing" : "stale"} — run \`npx lineadraw manifest\` and commit the result.`,
       );
+    const libWarning = tsconfigLibWarning(dir);
+    if (libWarning !== null) console.warn(`warning: ${libWarning}`);
     console.log(
       `OK: ${manifest.entries.length} entries, manifest is current.`,
     );
@@ -82,9 +92,10 @@ switch (command) {
   }
   case "init": {
     try {
-      const { created, skipped } = init(dir);
+      const { created, skipped, warnings } = await init(dir);
       for (const f of created) console.log(`created  ${f}`);
       for (const f of skipped) console.log(`kept     ${f}`);
+      for (const w of warnings) console.warn(`warning  ${w}`);
       console.log(
         "\nDone. Commit, push, then add the repo in the editor: Library → Marketplace.",
       );

package/lib/init.mjs

@@ -12,7 +12,13 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { buildManifest, manifestJson, MANIFEST_PATH } from "./manifest.mjs";
+import {
+  buildManifest,
+  manifestJson,
+  MANIFEST_PATH,
+  verifyWithSdk,
+  withThumbnails,
+} from "./manifest.mjs";
 
 const templatesDir = join(
   dirname(fileURLToPath(import.meta.url)),
@@ -33,8 +39,29 @@ export const collectionSlug = (pkgName) => {
   return slug === "" ? "my-collection" : slug;
 };
 
-/** Run init in `dir`. Returns `{ created, skipped }` path lists. */
-export const init = (dir) => {
+/**
+ * Warn when an existing tsconfig lets TypeScript default `lib` to include
+ * DOM: lib.dom's globals collide with lineadraw's global DTO aliases —
+ * DOM's `interface Text` (a Node) silently wins over lineadraw's `Text`
+ * (skipLibCheck hides the duplicate-identifier error). Repos scaffolded
+ * before lineadraw 0.3.1 carry such a tsconfig. Cheap string test on
+ * purpose: tsconfig is JSONC, so JSON.parse can't be trusted here.
+ * Returns the warning text, or null when the config is fine or absent.
+ */
+export const tsconfigLibWarning = (dir) => {
+  const p = join(dir, "tsconfig.json");
+  if (!existsSync(p)) return null;
+  const text = readFileSync(p, "utf8");
+  if (/"lib"\s*:/.test(text)) return null;
+  return (
+    'tsconfig.json has no "lib" — TypeScript then includes DOM types, and ' +
+    "DOM's global Text/Image/... shadow the lineadraw script types " +
+    '(Text becomes a DOM Node). Add to compilerOptions: "lib": ["ES2022"], "types": []'
+  );
+};
+
+/** Run init in `dir`. Returns `{ created, skipped, warnings }` lists. */
+export const init = async (dir) => {
   const pkgPath = join(dir, "package.json");
   if (!existsSync(pkgPath))
     throw new Error(
@@ -112,16 +139,26 @@ export const init = (dir) => {
   write(".gitignore", "node_modules/\n");
 
   // Generate the catalog last, over whatever modules now exist.
-  const { manifest, problems } = buildManifest(dir);
+  const { manifest: base, sources, problems } = buildManifest(dir);
   if (problems.length > 0) {
     const detail = problems
       .map((p) => `${p.file}: ${p.problems.join("; ")}`)
       .join("\n");
     throw new Error(`existing modules failed validation:\n${detail}`);
   }
+  // Bake thumbnails when the sdk is installed, so the very first commit's
+  // manifest matches what CI's `check` (sdk installed) regenerates.
+  const sdkResult = await verifyWithSdk(dir, base, sources);
+  const manifest = withThumbnails(base, sdkResult.thumbnails);
   mkdirSync(join(dir, dirname(MANIFEST_PATH)), { recursive: true });
   writeFileSync(join(dir, MANIFEST_PATH), manifestJson(manifest));
   created.push(`${MANIFEST_PATH} (${manifest.entries.length} entries)`);
 
-  return { created, skipped };
+  // A kept (pre-existing) tsconfig may carry the DOM-collision footgun the
+  // template avoids — surface it instead of silently leaving it broken.
+  const warnings = [];
+  const libWarning = tsconfigLibWarning(dir);
+  if (libWarning !== null) warnings.push(libWarning);
+
+  return { created, skipped, warnings };
 };

package/lib/manifest.mjs

@@ -5,7 +5,7 @@
 // bytes, so `check` is a plain diff.
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // sucrase is this package's own dependency — the light path needs nothing
@@ -202,24 +202,96 @@ export const MANIFEST_PATH = ".lineadraw/marketplace.json";
  * `{ ran, problems }` — `ran: false` when the sdk (or a new enough one) is
  * absent; validation-only, so manifest CONTENT never depends on it.
  */
-export const verifyWithSdk = async (repoDir, manifest, sources) => {
-  let sdk;
+/**
+ * Locate the repo's installed @lineadraw/sdk entry module. require.resolve
+ * alone is NOT enough: sdk ≤ 0.11 exports only the `import` condition,
+ * which a CJS resolver refuses (ERR_PACKAGE_PATH_NOT_EXPORTED) even though
+ * the package is installed — that mislabeled installed sdks as missing.
+ * On any resolve failure, fall back to walking node_modules by hand (the
+ * same directory climb Node performs) and reading the entry from the sdk's
+ * own package.json. Returns an absolute path, or null when truly absent.
+ */
+const resolveSdkEntry = (repoDir) => {
   try {
     const repoRequire = createRequire(join(repoDir, "package.json"));
-    sdk = await import(
-      pathToFileURL(repoRequire.resolve("@lineadraw/sdk")).href
-    );
+    return repoRequire.resolve("@lineadraw/sdk");
   } catch {
-    return { ran: false, problems: [] };
+    for (let d = resolve(repoDir); ; d = dirname(d)) {
+      const pkgPath = join(d, "node_modules", "@lineadraw", "sdk", "package.json");
+      if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const dot = pkg.exports?.["."];
+        const entry =
+          (typeof dot === "string" ? dot : (dot?.import ?? dot?.default)) ??
+          pkg.main ??
+          "./dist/index.js";
+        return join(dirname(pkgPath), entry);
+      }
+      if (dirname(d) === d) return null;
+    }
+  }
+};
+
+export const verifyWithSdk = async (repoDir, manifest, sources) => {
+  const entryPath = resolveSdkEntry(repoDir);
+  if (entryPath === null)
+    return { ran: false, problems: [], reason: "not-installed" };
+  let sdk;
+  try {
+    sdk = await import(pathToFileURL(entryPath).href);
+  } catch (e) {
+    // Installed but not loadable (broken install, incompatible Node, …) —
+    // must never be reported as "not installed".
+    return {
+      ran: false,
+      problems: [],
+      reason: "load-failed",
+      detail: e instanceof Error ? e.message : String(e),
+    };
   }
   if (typeof sdk.testBlockDefinition !== "function")
-    return { ran: false, problems: [] }; // sdk predates module validation
+    return { ran: false, problems: [], reason: "too-old" };
   const problems = [];
+  // All block sources double as the resolution set for thumbnails, so a
+  // block emitting instances of its catalog siblings previews complete.
+  const blockSources = manifest.entries
+    .filter((e) => e.kind === "block")
+    .map((e) => sources.get(e.id));
+  const thumbnails = new Map();
   for (const entry of manifest.entries) {
     if (entry.kind !== "block") continue; // commands are interactive — no dry run
     const result = await sdk.testBlockDefinition(sources.get(entry.id));
-    if (!result.ok)
+    if (!result.ok) {
       problems.push({ file: entry.source, problems: [result.error] });
+      continue;
+    }
+    // Bake the preview thumbnail (sdk ≥ 0.12; older sdks still validate).
+    // The render is deterministic, so the manifest stays byte-stable.
+    if (typeof sdk.renderBlockThumbnailSvg === "function") {
+      try {
+        const svg = await sdk.renderBlockThumbnailSvg(sources.get(entry.id), {
+          definitions: blockSources,
+        });
+        if (typeof svg === "string") thumbnails.set(entry.id, svg);
+      } catch {
+        // A block that validates but can't render just ships no thumbnail.
+      }
+    }
   }
-  return { ran: true, problems };
+  return { ran: true, problems, thumbnails };
+};
+
+/**
+ * Manifest with `thumbnailSvg` baked onto the block entries that have one —
+ * appended as the LAST key of each entry so serialization stays stable.
+ */
+export const withThumbnails = (manifest, thumbnails) => {
+  if (!thumbnails || thumbnails.size === 0) return manifest;
+  return {
+    ...manifest,
+    entries: manifest.entries.map((entry) => {
+      const svg = thumbnails.get(entry.id);
+      return svg === undefined ? entry : { ...entry, thumbnailSvg: svg };
+    }),
+  };
 };

package/lineadraw.d.ts

@@ -86,6 +86,12 @@ declare module "lineadraw" {
           kind: "lines";
           angle: number;
           spacing: number;
+      } | {
+          kind: "gradient";
+          shape?: "linear" | "radial";
+          color1?: string;
+          color2?: string;
+          angle?: number;
       };
       /** Pattern spacing multiplier. */
       scale?: number;
@@ -219,6 +225,12 @@ declare module "lineadraw" {
       kind: "lines";
       angle: number;
       spacing: number;
+  } | {
+      kind: "gradient";
+      shape: "linear" | "radial";
+      color1: string;
+      color2: string;
+      angle: number;
   };
   export type StoredHatch = StoredShape<{
       type: "hatch";
@@ -345,6 +357,14 @@ declare module "lineadraw" {
       type: "enum";
       default: string;
       options: readonly ParameterOption[];
+  }
+  /** A section label between rows in the properties panel. Carries no
+   * value: it never appears in the `params` record `draw` receives.
+   * `name` stays the unique key (paramVisibility can hide it by name). */
+   | {
+      name: string;
+      label?: string;
+      type: "label";
   };
   /**
    * The block's parameters table — what the `params` member of a BlockSpec
@@ -375,7 +395,9 @@ declare module "lineadraw" {
    * passes through unchanged.
    */
   export type ParamValues<P> = P extends () => infer R ? ParamValues<R> : P extends readonly (infer Q extends ParamDef)[] ? {
-      readonly [E in Q as E["name"]]: ParamValue<E>;
+      readonly [E in Q as E extends {
+          type: "label";
+      } ? never : E["name"]]: ParamValue<E>;
   } : P;
 
   // ——— Script contract ———
@@ -865,6 +887,12 @@ type Hatch = Styled<{
         kind: "lines";
         angle: number;
         spacing: number;
+    } | {
+        kind: "gradient";
+        shape?: "linear" | "radial";
+        color1?: string;
+        color2?: string;
+        angle?: number;
     };
     /** Pattern spacing multiplier. */
     scale?: number;
@@ -998,6 +1026,12 @@ type StoredHatchFill = {
     kind: "lines";
     angle: number;
     spacing: number;
+} | {
+    kind: "gradient";
+    shape: "linear" | "radial";
+    color1: string;
+    color2: string;
+    angle: number;
 };
 type StoredHatch = StoredShape<{
     type: "hatch";
@@ -1124,6 +1158,14 @@ type ParamDef = {
     type: "enum";
     default: string;
     options: readonly ParameterOption[];
+}
+/** A section label between rows in the properties panel. Carries no
+ * value: it never appears in the `params` record `draw` receives.
+ * `name` stays the unique key (paramVisibility can hide it by name). */
+ | {
+    name: string;
+    label?: string;
+    type: "label";
 };
 /**
  * The block's parameters table — what the `params` member of a BlockSpec
@@ -1154,7 +1196,9 @@ type ParamValue<Q extends ParamDef> = Q extends {
  * passes through unchanged.
  */
 type ParamValues<P> = P extends () => infer R ? ParamValues<R> : P extends readonly (infer Q extends ParamDef)[] ? {
-    readonly [E in Q as E["name"]]: ParamValue<E>;
+    readonly [E in Q as E extends {
+        type: "label";
+    } ? never : E["name"]]: ParamValue<E>;
 } : P;
 
 // Script-contract globals: aliases into the module (not re-declarations),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lineadraw",
-  "version": "0.3.0",
+  "version": "0.5.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"
@@ -30,9 +27,9 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "sucrase": "^3.35.0"
+    "sucrase": "^3.35.1"
   },
   "devDependencies": {
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   }
 }

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.

package/templates/tsconfig.json

@@ -1,11 +1,18 @@
 {
   "compilerOptions": {
     "target": "ES2022",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [],
     "module": "ESNext",
     "moduleResolution": "bundler",
     "strict": true,
     "noEmit": true,
     "skipLibCheck": true
   },
-  "include": ["blocks", "commands"]
-}
+  "include": [
+    "blocks",
+    "commands"
+  ]
+}