lineadraw 0.4.0 → 0.5.0

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.4.0",
+  "version": "0.5.0",
   "description": "Type definitions and marketplace tooling for Linea blocks and commands",
   "license": "MIT",
   "author": "Mikhail Koshelev",
@@ -27,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/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"
+  ]
+}