lineadraw 0.2.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/bin/lineadraw.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// The `lineadraw` CLI — marketplace tooling for Linea block/command repos.
+//   lineadraw manifest [--dir <path>]   generate .lineadraw/marketplace.json
+//   lineadraw check    [--dir <path>]   validate + fail if the manifest is stale
+//   lineadraw init     [--dir <path>]   add the marketplace structure here
+// See docs/marketplace-devx.md in the linea repo for the design.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+  buildManifest,
+  manifestJson,
+  MANIFEST_PATH,
+  verifyWithSdk,
+} from "../lib/manifest.mjs";
+import { init } from "../lib/init.mjs";
+
+const USAGE = `Usage: lineadraw <manifest|check|init> [--dir <path>]
+
+  manifest  Validate all modules and write ${MANIFEST_PATH}
+  check     Validate without writing; fail if the committed manifest is stale
+  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.`;
+
+const args = process.argv.slice(2);
+const command = args[0];
+const dirFlag = args.indexOf("--dir");
+const dir = resolve(dirFlag === -1 ? "." : (args[dirFlag + 1] ?? "."));
+
+const fail = (message) => {
+  console.error(message);
+  process.exit(1);
+};
+
+const reportProblems = (problems) => {
+  for (const p of problems)
+    console.error(`REJECTED ${p.file}: ${p.problems.join("; ")}`);
+};
+
+/** 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 all = [...problems, ...sdkResult.problems];
+  if (all.length > 0) {
+    reportProblems(all);
+    fail(`${all.length} problem(s) — nothing written.`);
+  }
+  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.",
+    );
+  return manifest;
+};
+
+switch (command) {
+  case "manifest": {
+    const manifest = await validatedManifest();
+    const outPath = join(dir, MANIFEST_PATH);
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, manifestJson(manifest));
+    console.log(`${MANIFEST_PATH}: ${manifest.entries.length} entries`);
+    for (const e of manifest.entries)
+      console.log(`  ${e.kind}  ${e.id}  v${e.version}`);
+    break;
+  }
+  case "check": {
+    const manifest = await validatedManifest();
+    const committedPath = join(dir, MANIFEST_PATH);
+    const committed = existsSync(committedPath)
+      ? readFileSync(committedPath, "utf8")
+      : null;
+    if (committed !== manifestJson(manifest))
+      fail(
+        `${MANIFEST_PATH} is ${committed === null ? "missing" : "stale"} — run \`npx lineadraw manifest\` and commit the result.`,
+      );
+    console.log(
+      `OK: ${manifest.entries.length} entries, manifest is current.`,
+    );
+    break;
+  }
+  case "init": {
+    try {
+      const { created, skipped } = init(dir);
+      for (const f of created) console.log(`created  ${f}`);
+      for (const f of skipped) console.log(`kept     ${f}`);
+      console.log(
+        "\nDone. Commit, push, then add the repo in the editor: Library → Marketplace.",
+      );
+    } catch (e) {
+      fail(e instanceof Error ? e.message : String(e));
+    }
+    break;
+  }
+  default:
+    fail(USAGE);
+}

package/lib/init.mjs

@@ -0,0 +1,127 @@
+// `lineadraw init` — add the marketplace structure to the CURRENT npm
+// project, whatever it is. Non-destructive: existing files and package.json
+// keys are never overwritten; everything it creates is reported. Ends by
+// generating `.lineadraw/marketplace.json`, so the repo is addable in the
+// editor from the first push.
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildManifest, manifestJson, MANIFEST_PATH } from "./manifest.mjs";
+
+const templatesDir = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "templates",
+);
+const template = (name) => readFileSync(join(templatesDir, name), "utf8");
+
+/** Lowercase-kebab collection slug from a package name (`@scope/` and
+ * illegal characters dropped, per the `@collection/slug` id grammar). */
+export const collectionSlug = (pkgName) => {
+  const slug = String(pkgName ?? "")
+    .replace(/^@[^/]+\//, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return slug === "" ? "my-collection" : slug;
+};
+
+/** Run init in `dir`. Returns `{ created, skipped }` path lists. */
+export const init = (dir) => {
+  const pkgPath = join(dir, "package.json");
+  if (!existsSync(pkgPath))
+    throw new Error(
+      "no package.json here — run `npm init` first (or start from an empty folder with `npm create lineadraw`)",
+    );
+  const created = [];
+  const skipped = [];
+  const write = (relPath, content) => {
+    const abs = join(dir, relPath);
+    if (existsSync(abs)) {
+      skipped.push(relPath);
+      return;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    created.push(relPath);
+  };
+
+  // package.json: fill the marketplace config and scripts, never replacing
+  // what is already there.
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  let pkgChanged = false;
+  if (pkg.lineadraw === undefined) {
+    pkg.lineadraw = {
+      marketplaceName: pkg.description ?? pkg.name ?? "Marketplace",
+      marketplaceOwner:
+        typeof pkg.author === "string" ? pkg.author : (pkg.author?.name ?? ""),
+    };
+    pkgChanged = true;
+  }
+  pkg.scripts ??= {};
+  for (const [script, cmd] of [
+    ["manifest", "lineadraw manifest"],
+    ["check", "lineadraw check"],
+  ]) {
+    if (pkg.scripts[script] === undefined) {
+      pkg.scripts[script] = cmd;
+      pkgChanged = true;
+    }
+  }
+  if (pkgChanged) {
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    created.push("package.json (lineadraw config + scripts merged)");
+  }
+
+  const blocksDir = pkg.lineadraw?.blocks ?? "blocks";
+  const commandsDir = pkg.lineadraw?.commands ?? "commands";
+  mkdirSync(join(dir, blocksDir), { recursive: true });
+  mkdirSync(join(dir, commandsDir), { recursive: true });
+
+  // A sample block only when the blocks folder is empty — init on an
+  // existing collection must not inject content.
+  const hasModules = readdirSync(join(dir, blocksDir)).some(
+    (f) => f.endsWith(".ts") || f.endsWith(".js"),
+  );
+  if (!hasModules) {
+    const author = pkg.lineadraw?.marketplaceOwner || "Your Name";
+    write(
+      join(blocksDir, "sample-box.block.ts"),
+      template("sample.block.ts")
+        .replaceAll("__COLLECTION__", collectionSlug(pkg.name))
+        .replaceAll("__AUTHOR__", author),
+    );
+  }
+
+  write(".github/workflows/marketplace.yml", template("workflow.yml"));
+  write("tsconfig.json", template("tsconfig.json"));
+  write(
+    "README.md",
+    template("README.md").replaceAll(
+      "__NAME__",
+      pkg.lineadraw?.marketplaceName ?? pkg.name ?? "Marketplace",
+    ),
+  );
+  write(".gitignore", "node_modules/\n");
+
+  // Generate the catalog last, over whatever modules now exist.
+  const { manifest, 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}`);
+  }
+  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 };
+};

package/lib/manifest.mjs

@@ -0,0 +1,225 @@
+// Minimal-manifest generator (docs/marketplace-devx.md in the linea repo).
+// Pure filesystem walk — no git: rows carry repo-RELATIVE `source` paths
+// that the editor resolves against the repo the user added, at the ref the
+// manifest itself was fetched from. Deterministic: same content, same
+// 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 { pathToFileURL } from "node:url";
+
+// sucrase is this package's own dependency — the light path needs nothing
+// else installed.
+const require_ = createRequire(import.meta.url);
+
+const ID_RE = /^@[a-z0-9-]{1,64}\/[a-z0-9-]{1,64}$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+
+/** Marketplace config resolved from the repo's package.json. */
+export const readConfig = (repoDir) => {
+  const pkgPath = join(repoDir, "package.json");
+  if (!existsSync(pkgPath))
+    throw new Error(`no package.json in ${repoDir} — run \`lineadraw init\` in an npm project`);
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const cfg = pkg.lineadraw ?? {};
+  return {
+    name: cfg.marketplaceName ?? pkg.description ?? pkg.name ?? "Marketplace",
+    owner:
+      cfg.marketplaceOwner ??
+      (typeof pkg.author === "string" ? pkg.author : (pkg.author?.name ?? "")),
+    blocksDir: cfg.blocks ?? "blocks",
+    commandsDir: cfg.commands ?? "commands",
+  };
+};
+
+// Same execution model as @lineadraw/core's transpiler: ESM→CJS, run
+// against a require shim. Helpers resolve to no-op function proxies —
+// top-level code only needs the imports to EXIST; draw()/run() never run
+// here (that is the optional sdk dry-run's job).
+const helperProxy = new Proxy({}, { get: () => () => ({}) });
+
+const executeModule = (source) => {
+  const { transform } = require_("sucrase");
+  const code = transform(source, {
+    transforms: ["typescript", "imports"],
+  }).code;
+  const moduleShim = { exports: {} };
+  new Function("exports", "require", "module", code)(
+    moduleShim.exports,
+    (spec) => {
+      if (spec === "lineadraw" || spec === "linea")
+        return {
+          helpers: helperProxy,
+          defineBlock: (s) => s,
+          defineCommand: (s) => s,
+        };
+      if (spec === "lineadraw/helpers" || spec === "linea/helpers")
+        return helperProxy;
+      throw new Error(`illegal import "${spec}"`);
+    },
+    moduleShim,
+  );
+  const exported = moduleShim.exports;
+  const spec = exported.default;
+  return spec !== null && typeof spec === "object" && !Array.isArray(spec)
+    ? { ...exported, ...spec }
+    : exported;
+};
+
+const entryOf = (kind, repoDir, folder, file) => {
+  const source = readFileSync(join(repoDir, folder, file), "utf8");
+  let mod;
+  try {
+    mod = executeModule(source);
+  } catch (e) {
+    return { file, problems: [`does not compile: ${e.message}`] };
+  }
+  const problems = [];
+  if (typeof mod.id !== "string" || !ID_RE.test(mod.id))
+    problems.push(`id ${JSON.stringify(mod.id)} is not @collection/slug`);
+  if (typeof mod.name !== "string" || mod.name.trim() === "")
+    problems.push("missing name");
+  if (typeof mod.version !== "string" || !SEMVER_RE.test(mod.version))
+    problems.push(`version ${JSON.stringify(mod.version)} is not semver`);
+  if (
+    kind === "block" &&
+    typeof mod.draw !== "function" &&
+    typeof mod.main !== "function"
+  )
+    problems.push("no draw export");
+  if (kind === "command" && typeof mod.run !== "function")
+    problems.push("no run export");
+  if (problems.length > 0) return { file, problems };
+  return {
+    file,
+    source,
+    entry: {
+      kind,
+      id: mod.id,
+      name: mod.name,
+      version: mod.version,
+      ...(typeof mod.description === "string"
+        ? { description: mod.description }
+        : {}),
+      tags: Array.isArray(mod.tags)
+        ? mod.tags.filter((t) => typeof t === "string")
+        : [],
+      authors: Array.isArray(mod.authors)
+        ? mod.authors.filter((a) => typeof a === "string")
+        : [],
+      dependencies:
+        kind === "block" && Array.isArray(mod.dependencies)
+          ? mod.dependencies.filter((d) => typeof d === "string")
+          : [],
+      // POSIX-relative, unencoded — the editor percent-encodes segments
+      // when it builds the fetch URL.
+      source: `${folder}/${file}`,
+    },
+  };
+};
+
+const listModules = (repoDir, folder) =>
+  existsSync(join(repoDir, folder))
+    ? readdirSync(join(repoDir, folder))
+        .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
+        .sort()
+    : [];
+
+/**
+ * Build the manifest for a marketplace repo. Returns
+ * `{ manifest, sources, problems }`; `problems` is a list of
+ * `{ file, problems }` — a non-empty list means the repo must not publish
+ * (callers fail instead of writing a partial catalog). `sources` maps
+ * entry id → module source (for the optional sdk dry-run).
+ */
+export const buildManifest = (repoDir) => {
+  const cfg = readConfig(repoDir);
+  const results = [
+    ...listModules(repoDir, cfg.blocksDir).map((f) =>
+      entryOf("block", repoDir, cfg.blocksDir, f),
+    ),
+    ...listModules(repoDir, cfg.commandsDir).map((f) =>
+      entryOf("command", repoDir, cfg.commandsDir, f),
+    ),
+  ];
+  const problems = results.filter((r) => r.problems).map((r) => ({
+    file: r.file,
+    problems: r.problems,
+  }));
+  const entries = results.filter((r) => r.entry).map((r) => r.entry);
+
+  const dupes = [
+    ...new Set(
+      entries
+        .map((e) => e.id)
+        .filter((id, i, all) => all.indexOf(id) !== i),
+    ),
+  ];
+  if (dupes.length > 0)
+    problems.push({
+      file: "(catalog)",
+      problems: [`duplicate ids: ${dupes.join(", ")}`],
+    });
+
+  // The catalog must be dependency-CLOSED: every declared dependency
+  // resolves to a block entry in this same manifest.
+  const blockIds = new Set(
+    entries.filter((e) => e.kind === "block").map((e) => e.id),
+  );
+  const dangling = entries.flatMap((e) =>
+    e.dependencies
+      .filter((d) => !blockIds.has(d))
+      .map((d) => `${e.id} → ${d}`),
+  );
+  if (dangling.length > 0)
+    problems.push({
+      file: "(catalog)",
+      problems: [`dangling dependencies: ${dangling.join(", ")}`],
+    });
+
+  const sources = new Map(
+    results.filter((r) => r.entry).map((r) => [r.entry.id, r.source]),
+  );
+  return {
+    manifest: {
+      name: cfg.name,
+      owner: { name: cfg.owner },
+      entries,
+    },
+    sources,
+    problems,
+  };
+};
+
+export const manifestJson = (manifest) =>
+  JSON.stringify(manifest, null, 2) + "\n";
+
+export const MANIFEST_PATH = ".lineadraw/marketplace.json";
+
+/**
+ * Optional execution-level verification: dry-run every block through
+ * @lineadraw/sdk when the repo has it installed. Returns
+ * `{ 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;
+  try {
+    const repoRequire = createRequire(join(repoDir, "package.json"));
+    sdk = await import(
+      pathToFileURL(repoRequire.resolve("@lineadraw/sdk")).href
+    );
+  } catch {
+    return { ran: false, problems: [] };
+  }
+  if (typeof sdk.testBlockDefinition !== "function")
+    return { ran: false, problems: [] }; // sdk predates module validation
+  const problems = [];
+  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)
+      problems.push({ file: entry.source, problems: [result.error] });
+  }
+  return { ran: true, problems };
+};

package/package.json

@@ -1,19 +1,35 @@
-{
-  "name": "lineadraw",
-  "version": "0.2.0",
-  "description": "Type definitions for Linea block and command scripts",
-  "license": "MIT",
-  "author": "Mikhail Koshelev",
-  "type": "module",
-  "types": "./lineadraw.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lineadraw.d.ts",
-      "default": "./main.js"
-    },
-    "./helpers": {
-      "types": "./lineadraw.d.ts",
-      "default": "./main.js"
-    }
-  }
+{
+  "name": "lineadraw",
+  "version": "0.4.0",
+  "description": "Type definitions and marketplace tooling for Linea blocks and commands",
+  "license": "MIT",
+  "author": "Mikhail Koshelev",
+  "type": "module",
+  "types": "./lineadraw.d.ts",
+  "bin": {
+    "lineadraw": "./bin/lineadraw.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./lineadraw.d.ts"
+    },
+    "./helpers": {
+      "types": "./lineadraw.d.ts"
+    }
+  },
+  "files": [
+    "lineadraw.d.ts",
+    "bin",
+    "lib",
+    "templates"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "sucrase": "^3.35.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  }
 }

package/templates/README.md

@@ -0,0 +1,18 @@
+# __NAME__
+
+A [Linea](https://github.com/lineadraw/lineadraw) marketplace:
+`blocks/*.block.ts` and `commands/*.cmd.ts` modules plus a generated
+catalog (`.lineadraw/marketplace.json`).
+
+## Authoring
+
+- Add or edit modules under `blocks/` and `commands/`.
+- Regenerate the catalog: `npm run manifest` — CI fails when it is stale.
+- Validate without writing: `npm run check`.
+
+## Using it in the editor
+
+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/sample.block.ts

@@ -0,0 +1,35 @@
+// Sample block — a parametric rectangle centered on the picked point.
+// Replace it with your own; the public collection at
+// github.com/lineadraw/lineadraw is full of real examples.
+import { defineBlock } from "lineadraw";
+import type { Polyline } from "lineadraw";
+
+export default defineBlock({
+  // The id is the block's identity everywhere: @<collection>/<slug>,
+  // lowercase kebab. Re-publishing the same id updates in place.
+  id: "@__COLLECTION__/sample-box",
+  name: "Sample box",
+  version: "1.0.0",
+  description: "A parametric rectangle centered on the picked point.",
+  tags: ["sample"],
+  authors: ["__AUTHOR__"],
+  params: [
+    { name: "width", label: "Width", type: "number", default: 100, min: 1 },
+    { name: "height", label: "Height", type: "number", default: 50, min: 1 },
+  ],
+  draw: ({ params }) => {
+    const w = params.width / 2;
+    const h = params.height / 2;
+    const box: Polyline = {
+      type: "polyline",
+      closed: true,
+      points: [
+        [-w, -h],
+        [w, -h],
+        [w, h],
+        [-w, h],
+      ],
+    };
+    return [box];
+  },
+});

package/templates/tsconfig.json

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

package/templates/workflow.yml

@@ -0,0 +1,18 @@
+# Validates every block/command module and checks the committed catalog
+# (.lineadraw/marketplace.json) matches the sources in this commit.
+# Stale catalog? Run `npx lineadraw manifest` and commit the result.
+name: Marketplace
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npx lineadraw check