create-imagine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# create-imagine
+
+Scaffold a new Imagine project (React → scientific figures).
+
+## Usage
+
+```bash
+# Recommended
+npx create-imagine@latest my-figures
+
+# Also works (because the package name is create-imagine)
+npm create imagine@latest my-figures
+```
+
+## Templates
+
+- `blank`: minimal starter project (no preview images)
+- `example`: full starter project (includes example figures + preview PNGs)
+
+## Options
+
+```bash
+create-imagine [targetDir]
+
+--template blank|example
+--pm npm|pnpm|yarn|bun
+--install / --no-install
+--skills / --no-skills
+--yes
+--force
+--help
+```
+
+## Optional: install agent skills
+
+This scaffolder can optionally install the `imagine-best-practices` skill into your project:
+
+```bash
+npx skills add https://github.com/midhunxavier/imagine-skills --skill imagine-best-practices
+```

package/bin/create-imagine.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function usage() {
+  const text = `
+create-imagine
+
+Usage:
+  create-imagine [targetDir] [options]
+
+Options:
+  --template blank|example
+  --pm npm|pnpm|yarn|bun
+  --install / --no-install
+  --skills / --no-skills
+  --yes
+  --force
+  --help
+`.trim();
+  // eslint-disable-next-line no-console
+  console.log(text);
+}
+
+function parseArgs(argv) {
+  /** @type {{ targetDir?: string; template?: string; pm?: string; install?: boolean; skills?: boolean; yes: boolean; force: boolean; help: boolean }} */
+  const out = { yes: false, force: false, help: false };
+  /** @type {string[]} */
+  const positional = [];
+  /** @type {string[]} */
+  const unknown = [];
+
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+
+    if (a === '--') {
+      positional.push(...argv.slice(i + 1).filter(Boolean));
+      break;
+    }
+
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+      continue;
+    }
+    if (a === '--yes' || a === '-y') {
+      out.yes = true;
+      continue;
+    }
+    if (a === '--force') {
+      out.force = true;
+      continue;
+    }
+    if (a === '--install') {
+      out.install = true;
+      continue;
+    }
+    if (a === '--no-install') {
+      out.install = false;
+      continue;
+    }
+    if (a === '--skills') {
+      out.skills = true;
+      continue;
+    }
+    if (a === '--no-skills') {
+      out.skills = false;
+      continue;
+    }
+
+    if (a === '--template') {
+      const v = argv[i + 1];
+      if (!v) unknown.push(a);
+      else out.template = v;
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--template=')) {
+      out.template = a.slice('--template='.length);
+      continue;
+    }
+
+    if (a === '--pm') {
+      const v = argv[i + 1];
+      if (!v) unknown.push(a);
+      else out.pm = v;
+      i += 1;
+      continue;
+    }
+    if (a.startsWith('--pm=')) {
+      out.pm = a.slice('--pm='.length);
+      continue;
+    }
+
+    if (a.startsWith('-')) {
+      unknown.push(a);
+      continue;
+    }
+
+    positional.push(a);
+  }
+
+  if (unknown.length) {
+    const msg = `Unknown option(s): ${unknown.join(', ')}`;
+    const err = new Error(msg);
+    // @ts-ignore
+    err.code = 'USAGE';
+    throw err;
+  }
+
+  if (positional.length > 1) {
+    const err = new Error(`Too many arguments. Expected at most 1 targetDir, got: ${positional.join(' ')}`);
+    // @ts-ignore
+    err.code = 'USAGE';
+    throw err;
+  }
+
+  if (positional.length === 1) out.targetDir = positional[0];
+  return out;
+}
+
+function isNonEmptyDir(entries) {
+  return entries.some((e) => e !== '.' && e !== '..');
+}
+
+async function dirExists(p) {
+  return fs
+    .stat(p)
+    .then((s) => s.isDirectory())
+    .catch(() => false);
+}
+
+async function fileExists(p) {
+  return fs
+    .stat(p)
+    .then((s) => s.isFile())
+    .catch(() => false);
+}
+
+async function isDirEmpty(p) {
+  const entries = await fs.readdir(p).catch(() => null);
+  if (!entries) return true;
+  return !isNonEmptyDir(entries);
+}
+
+function toKebabCase(input) {
+  return String(input)
+    .trim()
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+}
+
+function toValidPackageName(baseName) {
+  let name = toKebabCase(baseName);
+  name = name.replace(/^[_\\.]+/, '');
+  name = name.replace(/[^a-z0-9-]+/g, '');
+  name = name.replace(/^-+|-+$/g, '');
+  if (!name) name = 'imagine-project';
+  return name;
+}
+
+function toTitle(input) {
+  const words = String(input)
+    .trim()
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .split(' ')
+    .filter(Boolean);
+  if (!words.length) return 'Imagine Project';
+  return words.map((w) => w.slice(0, 1).toUpperCase() + w.slice(1)).join(' ');
+}
+
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? '';
+  const m = ua.match(/^(npm|pnpm|yarn|bun)\//);
+  return m?.[1] ?? null;
+}
+
+function platformBin(cmd) {
+  if (process.platform !== 'win32') return cmd;
+  return `${cmd}.cmd`;
+}
+
+function run(cmd, args, opts) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd: opts?.cwd ?? process.cwd(),
+      stdio: 'inherit',
+      env: process.env
+    });
+    child.on('error', reject);
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+async function copyDirContents(srcDir, destDir) {
+  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+  for (const e of entries) {
+    const src = path.join(srcDir, e.name);
+    const dest = path.join(destDir, e.name);
+    await fs.cp(src, dest, { recursive: true });
+  }
+}
+
+function ensureTemplate(value) {
+  if (value !== 'blank' && value !== 'example') {
+    const err = new Error(`Invalid --template: ${value}. Expected "blank" or "example".`);
+    // @ts-ignore
+    err.code = 'USAGE';
+    throw err;
+  }
+  return value;
+}
+
+function ensurePm(value) {
+  if (value !== 'npm' && value !== 'pnpm' && value !== 'yarn' && value !== 'bun') {
+    const err = new Error(`Invalid --pm: ${value}. Expected npm|pnpm|yarn|bun.`);
+    // @ts-ignore
+    err.code = 'USAGE';
+    throw err;
+  }
+  return value;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+
+  try {
+    const imagineSkillsRepo = 'https://github.com/midhunxavier/imagine-skills';
+    const imagineSkillsName = 'imagine-best-practices';
+
+    const cwdBase = path.basename(process.cwd());
+    const defaultTargetDir = cwdBase && cwdBase !== path.parse(process.cwd()).root ? cwdBase : 'imagine-project';
+
+    let targetDirInput = args.targetDir;
+    if (!targetDirInput) {
+      if (args.yes || !interactive) {
+        targetDirInput = defaultTargetDir;
+      } else {
+        const answer = await rl.question(`Project directory (${defaultTargetDir}): `);
+        targetDirInput = answer.trim() || defaultTargetDir;
+      }
+    }
+
+    const targetPath = path.resolve(process.cwd(), targetDirInput);
+    const targetBaseName = path.basename(targetPath);
+
+    const template = ensureTemplate(
+      args.template ??
+        (args.yes || !interactive
+          ? 'blank'
+          : ensureTemplate((await rl.question('Template (blank/example) (blank): ')).trim() || 'blank'))
+    );
+
+    const install =
+      args.install ??
+      (args.yes || !interactive
+        ? true
+        : (() => {
+            return null;
+          })());
+
+    let shouldInstall = install;
+    if (shouldInstall === null) {
+      const answer = (await rl.question('Install dependencies? (Y/n): ')).trim().toLowerCase();
+      shouldInstall = answer === '' || answer === 'y' || answer === 'yes';
+    }
+
+    let pm = args.pm ?? null;
+    if (shouldInstall) {
+      if (!pm) pm = args.yes || !interactive ? detectPackageManager() ?? 'npm' : null;
+      if (!pm && interactive) {
+        const answer = (await rl.question('Package manager (npm/pnpm/yarn/bun) (npm): ')).trim().toLowerCase();
+        pm = answer || 'npm';
+      }
+      pm = ensurePm(pm ?? 'npm');
+    }
+
+    const skills =
+      args.skills ??
+      (args.yes || !interactive
+        ? false
+        : (() => {
+            return null;
+          })());
+
+    let shouldInstallSkills = skills;
+    if (shouldInstallSkills === null) {
+      const answer = (await rl.question(`Add Imagine agent skill "${imagineSkillsName}"? (y/N): `)).trim().toLowerCase();
+      shouldInstallSkills = answer === 'y' || answer === 'yes';
+    }
+
+    const existsDir = await dirExists(targetPath);
+    if (existsDir) {
+      const empty = await isDirEmpty(targetPath);
+      if (!empty) {
+        if (!args.force) {
+          throw new Error(`Target directory is not empty: ${targetPath}\nUse --force to overwrite.`);
+        }
+        await fs.rm(targetPath, { recursive: true, force: true });
+      }
+    } else {
+      const existsFile = await fileExists(targetPath);
+      if (existsFile) throw new Error(`Target path exists and is a file: ${targetPath}`);
+    }
+
+    await fs.mkdir(targetPath, { recursive: true });
+
+    const templateDir = path.resolve(__dirname, '..', 'templates', template);
+    await copyDirContents(templateDir, targetPath);
+
+    const gitignoreSrc = path.join(targetPath, 'gitignore');
+    const gitignoreDest = path.join(targetPath, '.gitignore');
+    if (await fileExists(gitignoreSrc)) {
+      await fs.rename(gitignoreSrc, gitignoreDest).catch(async (err) => {
+        if (String(err?.code ?? '') === 'EEXIST') {
+          await fs.rm(gitignoreDest, { force: true });
+          await fs.rename(gitignoreSrc, gitignoreDest);
+          return;
+        }
+        throw err;
+      });
+    }
+
+    const pkgPath = path.join(targetPath, 'package.json');
+    const pkgRaw = await fs.readFile(pkgPath, 'utf8');
+    const pkg = JSON.parse(pkgRaw);
+    pkg.name = toValidPackageName(targetBaseName);
+    await fs.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+
+    const readmePath = path.join(targetPath, 'README.md');
+    if (await fileExists(readmePath)) {
+      const raw = await fs.readFile(readmePath, 'utf8');
+      const lines = raw.split(/\\r?\\n/);
+      lines[0] = `# ${toTitle(targetBaseName)}`;
+      await fs.writeFile(readmePath, lines.join('\n'), 'utf8');
+    }
+
+    if (shouldInstall) {
+      const bin = platformBin(pm);
+      await run(bin, ['install'], { cwd: targetPath });
+    }
+
+    if (shouldInstallSkills) {
+      const npx = platformBin('npx');
+      try {
+        await run(
+          npx,
+          ['--yes', 'skills', 'add', imagineSkillsRepo, '--skill', imagineSkillsName, '-y'],
+          { cwd: targetPath }
+        );
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.error('\nFailed to install skills (optional). You can run this later:\n');
+        // eslint-disable-next-line no-console
+        console.error(`  npx skills add ${imagineSkillsRepo} --skill ${imagineSkillsName}\n`);
+      }
+    }
+
+    const cdPath = path.isAbsolute(targetDirInput) ? targetPath : targetDirInput;
+
+    // eslint-disable-next-line no-console
+    console.log('\nDone.\n');
+    // eslint-disable-next-line no-console
+    console.log('Next steps:');
+    // eslint-disable-next-line no-console
+    console.log(`  cd ${cdPath}`);
+    if (!shouldInstall) {
+      // eslint-disable-next-line no-console
+      console.log('  npm install');
+    }
+    // eslint-disable-next-line no-console
+    console.log('  npm run dev');
+    // eslint-disable-next-line no-console
+    console.log('  npm run render -- --project example');
+    // eslint-disable-next-line no-console
+    console.log(`\nOptional: npx skills add ${imagineSkillsRepo} --skill ${imagineSkillsName}`);
+  } finally {
+    if (rl) rl.close();
+  }
+}
+
+main().catch((err) => {
+  if (String(err?.code ?? '') === 'USAGE') usage();
+  // eslint-disable-next-line no-console
+  console.error(err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "create-imagine",
+  "version": "0.1.0",
+  "description": "Scaffold a new Imagine project (React → scientific figures).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-imagine": "bin/create-imagine.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/blank/README.md

@@ -0,0 +1,96 @@
+# Imagine
+
+React → scientific figures (PNG + SVG) with a live Studio and a Playwright renderer.
+
+## Quickstart
+
+```bash
+npm install
+npm run dev
+```
+
+Open the Studio at http://localhost:5173
+
+## Projects
+
+Figures are organized into projects under `projects/<id>/`.
+
+The Studio home shows projects. Clicking a project shows:
+- a preview gallery (static images from `public/`)
+- the live React-generated figures for that project
+
+```bash
+npm run list
+```
+
+List one project’s figures:
+
+```bash
+npm run list -- --project example
+```
+
+## Render exports
+
+```bash
+npm run render -- --project example
+```
+
+By default outputs are written to `out/<projectId>/`:
+- `out/<projectId>/<figure>--<variant>.png`
+- `out/<projectId>/<figure>--<variant>.svg`
+- `out/<projectId>/manifest.json`
+
+### Render options
+
+```bash
+# Only one figure
+npm run render -- --project example --fig line-chart
+
+# Only one variant
+npm run render -- --project example --fig hello-world --variant transparent
+
+# Dev-mode rendering (requires `npm run dev` already running)
+npm run render:dev -- --project example
+```
+
+Common flags:
+- `--project <id>`
+- `--fig <id>` (repeatable or comma-separated)
+- `--variant <id>` (repeatable or comma-separated)
+- `--formats png,svg`
+- `--out <dir>`
+- `--mode build|dev`
+- `--url http://localhost:5173` (dev mode)
+- `--no-props` (ignore Studio-saved overrides)
+
+## Text editing (Studio Controls)
+
+When you edit figure text in Studio, it saves overrides into:
+- `projects/<projectId>/props.json`
+
+`npm run render` automatically uses those overrides (unless `--no-props`).
+
+## Create a new project
+
+1. Copy `projects/example/` to `projects/<your-id>/`
+2. Update `projects/<your-id>/project.ts` and `projects/<your-id>/manifest.ts`
+3. Restart `npm run dev` (project discovery is build-time)
+
+## Create a new figure (inside a project)
+
+1. Add a new file in `projects/<projectId>/figures/` that default-exports a React component whose root is an `<svg>`.
+2. Register it in `projects/<projectId>/manifest.ts` with an `id`, `title`, `moduleKey`, and at least one variant.
+3. Optionally add preview images under `public/projects/<projectId>/previews/` and reference them from `projects/<projectId>/project.ts`.
+
+Notes:
+- `moduleKey` must match the figure filename (without `.tsx`). Example: `projects/example/figures/line-chart.tsx` → `moduleKey: "line-chart"`.
+- Sizes can be specified as pixels or paper-friendly `mm + dpi` (converted to px for rendering).
+- MathJax is loaded on-demand from CDN by default. Override with `VITE_MATHJAX_URL` if needed.
+
+## Generate example previews
+
+```bash
+npm run render:previews
+```
+
+This writes PNGs to `public/projects/example/previews/`.

package/templates/blank/gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+out
+.DS_Store
+*.log
+

package/templates/blank/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Imagine Studio</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+

package/templates/blank/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "imagine-project",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "list": "tsx scripts/list.ts",
+    "render": "tsx scripts/render.ts",
+    "render:dev": "tsx scripts/render.ts --mode dev",
+    "render:previews": "tsx scripts/render.ts --project example --variant default --formats png --no-props --no-manifest --out public/projects/example/previews",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "d3-array": "^3.2.4",
+    "d3-format": "^3.1.0",
+    "d3-scale": "^4.0.2",
+    "d3-shape": "^3.2.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0"
+  },
+  "devDependencies": {
+    "@types/d3-array": "^3.2.2",
+    "@types/d3-format": "^3.0.4",
+    "@types/d3-scale": "^4.0.9",
+    "@types/d3-shape": "^3.1.8",
+    "@types/node": "^22.10.7",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "playwright": "^1.49.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.6",
+    "vitest": "^2.1.8"
+  }
+}

package/templates/blank/projects/example/figures/hello-world.tsx

@@ -0,0 +1,45 @@
+import { Figure } from '@/framework/Figure';
+import type { FigureComponentBaseProps } from '@/framework/types';
+import { theme } from '@/framework/theme';
+
+export default function HelloWorldFigure({
+  width,
+  height,
+  background,
+  heading = 'Imagine',
+  subtitle = 'React components → scientific figures (PNG + SVG)',
+  tipHeading = 'Tips',
+  tip1 = 'Edit the figure component and watch this update live.',
+  tip2 = 'Use the Controls panel to adjust text, then export via `npm run render`.'
+}: FigureComponentBaseProps & {
+  heading?: string;
+  subtitle?: string;
+  tipHeading?: string;
+  tip1?: string;
+  tip2?: string;
+}) {
+  return (
+    <Figure width={width} height={height} background={background} title="Hello world">
+      <g>
+        <text x={40} y={70} fontSize={34} fontWeight={700} fill={theme.colors.text}>
+          {heading}
+        </text>
+        <text x={40} y={110} fontSize={16} fill={theme.colors.subtleText}>
+          {subtitle}
+        </text>
+
+        <rect x={40} y={150} width={width - 80} height={height - 190} rx={theme.radii.md} fill={theme.colors.panel} />
+
+        <text x={70} y={210} fontSize={16} fill={theme.colors.text} fontWeight={600}>
+          {tipHeading}
+        </text>
+        <text x={70} y={245} fontSize={14} fill={theme.colors.text}>
+          • {tip1}
+        </text>
+        <text x={70} y={270} fontSize={14} fill={theme.colors.text}>
+          • {tip2}
+        </text>
+      </g>
+    </Figure>
+  );
+}