create-imagine 0.1.0

package/templates/example/projects/example/manifest.ts

@@ -0,0 +1,161 @@
+import type { FigureManifestItem } from '../../src/core/manifest';
+
+export const figures: FigureManifestItem[] = [
+  {
+    id: 'hello-world',
+    title: 'Hello world',
+    moduleKey: 'hello-world',
+    size: { unit: 'px', width: 900, height: 520 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          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`.'
+        },
+        controls: [
+          { kind: 'text', key: 'heading', label: 'Heading' },
+          { kind: 'text', key: 'subtitle', label: 'Subtitle' },
+          { kind: 'text', key: 'tipHeading', label: 'Tips heading' },
+          { kind: 'text', key: 'tip1', label: 'Tip #1' },
+          { kind: 'text', key: 'tip2', label: 'Tip #2' }
+        ]
+      },
+      {
+        id: 'transparent',
+        title: 'Transparent',
+        background: 'transparent',
+        props: {
+          heading: 'Imagine',
+          subtitle: 'Transparent background variant',
+          tipHeading: 'Notes',
+          tip1: 'Checkerboard mode helps preview transparency.',
+          tip2: 'PNG export uses omitBackground for transparency.'
+        }
+      }
+    ]
+  },
+  {
+    id: 'line-chart',
+    title: 'Line chart',
+    moduleKey: 'line-chart',
+    size: { unit: 'mm', width: 85, height: 60, dpi: 600 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          title: 'Example: signal over time',
+          xLabel: 'Time (a.u.)',
+          yLabel: 'Response',
+          seriesALabel: 'Condition A',
+          seriesBLabel: 'Condition B'
+        }
+      }
+    ]
+  },
+  {
+    id: 'pipeline-diagram',
+    title: 'Pipeline diagram',
+    moduleKey: 'pipeline-diagram',
+    size: { unit: 'px', width: 1000, height: 380 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          title: 'Example: analysis pipeline',
+          subtitle: 'Pure-SVG boxes/arrows + theme tokens',
+          step1: 'Ingest',
+          step2: 'Process',
+          step3: 'Publish',
+          callout: 'Edit labels in Controls'
+        }
+      }
+    ]
+  },
+  {
+    id: 'multi-panel',
+    title: 'Multi-panel layout',
+    moduleKey: 'multi-panel',
+    size: { unit: 'px', width: 1100, height: 650 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          title: 'Example: multi-panel figure',
+          subtitle: 'Use PanelGrid to compose sub-panels (a, b, c…)',
+          panelA: 'Panel: raw',
+          panelB: 'Panel: processed',
+          panelC: 'Panel: ablation',
+          panelD: 'Panel: summary'
+        }
+      }
+    ]
+  },
+  {
+    id: 'equation',
+    title: 'Equation (MathJax SVG)',
+    moduleKey: 'equation',
+    size: { unit: 'px', width: 900, height: 260 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          title: 'Example: equation (MathJax SVG)',
+          subtitle: 'Uses MathJax tex2svg (pure SVG; no foreignObject)',
+          tex: String.raw`\\hat{\\beta}=\\arg\\min_{\\beta}\\;\\|y-X\\beta\\|_2^2+\\lambda\\|\\beta\\|_1`
+        },
+        controls: [{ kind: 'text', key: 'tex', label: 'LaTeX', multiline: true }]
+      }
+    ]
+  },
+  {
+    id: 'ai-agent-architecture',
+    title: 'AI Agent Architecture',
+    moduleKey: 'ai-agent-architecture',
+    size: { unit: 'px', width: 1100, height: 700 },
+    variants: [
+      {
+        id: 'default',
+        title: 'Default',
+        background: 'white',
+        props: {
+          title: 'AI Agent Architecture',
+          subtitle: 'Multi-agent system with tool use and memory',
+          userInput: 'User Input',
+          orchestrator: 'Orchestrator',
+          memory: 'Memory / Context',
+          llm: 'LLM / Model',
+          tools1: 'Tool A',
+          tools2: 'Tool B',
+          tools3: 'Tool C',
+          output: 'Response',
+          notes: 'Components communicate via function calling'
+        },
+        controls: [
+          { kind: 'text', key: 'userInput', label: 'User Input Label' },
+          { kind: 'text', key: 'orchestrator', label: 'Orchestrator Label' },
+          { kind: 'text', key: 'llm', label: 'LLM Label' },
+          { kind: 'text', key: 'memory', label: 'Memory Label' },
+          { kind: 'text', key: 'tools1', label: 'Tool 1 Label' },
+          { kind: 'text', key: 'tools2', label: 'Tool 2 Label' },
+          { kind: 'text', key: 'tools3', label: 'Tool 3 Label' },
+          { kind: 'text', key: 'output', label: 'Output Label' }
+        ]
+      }
+    ]
+  }
+];
+

package/templates/example/projects/example/project.ts

@@ -0,0 +1,31 @@
+import type { ProjectDefinition } from '../../src/core/manifest';
+import { validateProject } from '../../src/core/manifest';
+import { figures } from './manifest';
+
+const project: ProjectDefinition = {
+  id: 'example',
+  title: 'Example project',
+  description: 'Starter figures (charts/diagrams/layout/math) with editable text controls.',
+  examples: [
+    {
+      figureId: 'hello-world',
+      variantId: 'default',
+      src: '/projects/example/previews/hello-world--default.png',
+      caption: 'Hello world'
+    },
+    { figureId: 'line-chart', variantId: 'default', src: '/projects/example/previews/line-chart--default.png', caption: 'Line chart' },
+    {
+      figureId: 'pipeline-diagram',
+      variantId: 'default',
+      src: '/projects/example/previews/pipeline-diagram--default.png',
+      caption: 'Pipeline diagram'
+    },
+    { figureId: 'multi-panel', variantId: 'default', src: '/projects/example/previews/multi-panel--default.png', caption: 'Multi-panel' },
+    { figureId: 'equation', variantId: 'default', src: '/projects/example/previews/equation--default.png', caption: 'Equation' }
+  ],
+  figures
+};
+
+validateProject(project);
+
+export default project;

package/templates/example/projects/example/props.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "overrides": {
+    "pipeline-diagram": {
+      "default": {
+        "step1": "Ingest"
+      }
+    }
+  }
+}

package/templates/example/scripts/list.ts

@@ -0,0 +1,46 @@
+import { loadAllProjects, loadProjectDefinition } from './projects';
+
+function hasFlag(name: string) {
+  return process.argv.includes(name);
+}
+
+function getFlag(name: string): string | undefined {
+  const idx = process.argv.findIndex((a) => a === name || a.startsWith(`${name}=`));
+  if (idx === -1) return undefined;
+  const a = process.argv[idx]!;
+  if (a.startsWith(`${name}=`)) return a.slice(name.length + 1);
+  return process.argv[idx + 1];
+}
+
+if (hasFlag('--json')) {
+  const projectId = getFlag('--project');
+  if (projectId) {
+    const project = await loadProjectDefinition(projectId);
+    process.stdout.write(JSON.stringify({ project }, null, 2) + '\n');
+    process.exit(0);
+  } else {
+    const projects = await loadAllProjects();
+    process.stdout.write(JSON.stringify({ projects }, null, 2) + '\n');
+    process.exit(0);
+  }
+}
+
+const projectId = getFlag('--project');
+if (!projectId) {
+  const projects = await loadAllProjects();
+  for (const p of projects) {
+    // eslint-disable-next-line no-console
+    console.log(`${p.id}  —  ${p.title}  (${p.figures.length} figure${p.figures.length === 1 ? '' : 's'})`);
+  }
+  process.exit(0);
+}
+
+const project = await loadProjectDefinition(projectId);
+for (const fig of project.figures) {
+  // eslint-disable-next-line no-console
+  console.log(`${fig.id}  —  ${fig.title}  (${fig.variants.length} variant${fig.variants.length === 1 ? '' : 's'})`);
+  for (const v of fig.variants) {
+    // eslint-disable-next-line no-console
+    console.log(`  - ${v.id}${v.title ? `  —  ${v.title}` : ''}`);
+  }
+}

package/templates/example/scripts/projects.ts

@@ -0,0 +1,43 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ProjectDefinition } from '../src/core/manifest';
+import { PROJECT_ID_RE } from '../src/core/manifest';
+
+async function fileExists(filePath: string): Promise<boolean> {
+  return fs
+    .stat(filePath)
+    .then((s) => s.isFile())
+    .catch(() => false);
+}
+
+export async function discoverProjectIds(): Promise<string[]> {
+  const projectsDir = path.resolve(process.cwd(), 'projects');
+  const entries = await fs.readdir(projectsDir, { withFileTypes: true }).catch(() => []);
+  const ids: string[] = [];
+
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!PROJECT_ID_RE.test(e.name)) continue;
+    const p = path.join(projectsDir, e.name, 'project.ts');
+    if (await fileExists(p)) ids.push(e.name);
+  }
+
+  return ids.sort();
+}
+
+export async function loadProjectDefinition(projectId: string): Promise<ProjectDefinition> {
+  if (!PROJECT_ID_RE.test(projectId)) throw new Error(`Invalid project id: ${projectId}`);
+  const projectPath = path.resolve(process.cwd(), 'projects', projectId, 'project.ts');
+  const mod = await import(pathToFileURL(projectPath).href);
+  const project = (mod as any).default as ProjectDefinition | undefined;
+  if (!project) throw new Error(`Project did not default-export a ProjectDefinition: ${projectPath}`);
+  return project;
+}
+
+export async function loadAllProjects(): Promise<ProjectDefinition[]> {
+  const ids = await discoverProjectIds();
+  const projects = await Promise.all(ids.map((id) => loadProjectDefinition(id)));
+  return projects.slice().sort((a, b) => a.title.localeCompare(b.title));
+}
+

package/templates/example/scripts/render.ts

@@ -0,0 +1,288 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { chromium } from 'playwright';
+import type { FigureManifestItem, FigureVariant } from '../src/core/manifest';
+import { resolveSize } from '../src/framework/sizing';
+import { startStaticServer } from './server';
+import { emptyPropsFile, validatePropsFileV1 } from '../src/core/manifest';
+import { loadProjectDefinition } from './projects';
+
+type Mode = 'build' | 'dev';
+
+function platformNpmBin() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function base64UrlEncode(input: string): string {
+  return Buffer.from(input, 'utf8')
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+function run(cmd: string, args: string[], opts: { cwd?: string } = {}) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      cwd: opts.cwd ?? process.cwd(),
+      stdio: 'inherit',
+      env: process.env
+    });
+    child.on('exit', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
+function splitList(value: string | undefined): string[] {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function collectFlagValues(name: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < process.argv.length; i++) {
+    const a = process.argv[i]!;
+    if (a === name) {
+      const v = process.argv[i + 1];
+      out.push(...splitList(v));
+      i += 1;
+      continue;
+    }
+    if (a.startsWith(`${name}=`)) {
+      out.push(...splitList(a.slice(name.length + 1)));
+    }
+  }
+  return out;
+}
+
+function getFlag(name: string): string | undefined {
+  const idx = process.argv.findIndex((a) => a === name || a.startsWith(`${name}=`));
+  if (idx === -1) return undefined;
+  const a = process.argv[idx]!;
+  if (a.startsWith(`${name}=`)) return a.slice(name.length + 1);
+  return process.argv[idx + 1];
+}
+
+function hasFlag(name: string): boolean {
+  return process.argv.includes(name);
+}
+
+function safeFilePart(input: string): string {
+  return input.replace(/[^a-zA-Z0-9_-]+/g, '-');
+}
+
+function usage() {
+  const text = `
+Imagine renderer
+
+Usage:
+  npm run render -- [options]
+
+Options:
+  --project <id>       Project id. Defaults to "example".
+  --fig <id>           Limit to figure id(s). Repeatable or comma-separated.
+  --variant <id>       Limit to variant id(s). Repeatable or comma-separated.
+  --formats png,svg    Defaults to "png,svg".
+  --out <dir>          Defaults to "out/<projectId>".
+  --mode build|dev     Defaults to "build".
+  --url <url>          Dev server URL (dev mode). Defaults to http://localhost:5173
+  --props-file <path>  Defaults to "projects/<projectId>/props.json" (if exists).
+  --no-props           Ignore props overrides file.
+  --no-manifest        Do not write out/manifest.json.
+  --help
+`.trim();
+  // eslint-disable-next-line no-console
+  console.log(text);
+}
+
+type RenderTarget = {
+  figure: FigureManifestItem;
+  variant: FigureVariant;
+};
+
+function selectTargets({
+  figures,
+  figureIds,
+  variantIds
+}: {
+  figures: FigureManifestItem[];
+  figureIds: string[];
+  variantIds: string[];
+}): RenderTarget[] {
+  const figSet = new Set(figureIds);
+  const varSet = new Set(variantIds);
+
+  const selectedFigures = figureIds.length ? figures.filter((f) => figSet.has(f.id)) : figures;
+  const out: RenderTarget[] = [];
+
+  for (const f of selectedFigures) {
+    const variants = variantIds.length ? f.variants.filter((v) => varSet.has(v.id)) : f.variants;
+    for (const v of variants) out.push({ figure: f, variant: v });
+  }
+  return out;
+}
+
+async function main() {
+  if (hasFlag('--help') || hasFlag('-h')) {
+    usage();
+    return;
+  }
+
+  const projectId = getFlag('--project') ?? 'example';
+  const figureIds = collectFlagValues('--fig');
+  const variantIds = collectFlagValues('--variant');
+  const formats = new Set(splitList(getFlag('--formats') ?? 'png,svg').map((s) => s.toLowerCase()));
+  const outDir = path.resolve(process.cwd(), getFlag('--out') ?? path.join('out', projectId));
+  const mode = ((getFlag('--mode') ?? 'build') as Mode) satisfies Mode;
+  const url = getFlag('--url') ?? 'http://localhost:5173';
+  const noProps = hasFlag('--no-props');
+  const noManifest = hasFlag('--no-manifest');
+  const propsFilePath = getFlag('--props-file') ?? path.join('projects', projectId, 'props.json');
+
+  if (mode !== 'build' && mode !== 'dev') {
+    throw new Error(`Invalid --mode: ${mode}`);
+  }
+
+  if (![...formats].every((f) => f === 'png' || f === 'svg')) {
+    throw new Error(`Invalid --formats: ${[...formats].join(',')}`);
+  }
+
+  const project = await loadProjectDefinition(projectId);
+  const targets = selectTargets({ figures: project.figures, figureIds, variantIds });
+  if (!targets.length) {
+    throw new Error(`No render targets matched. --fig=${figureIds.join(',')} --variant=${variantIds.join(',')}`);
+  }
+
+  await fs.mkdir(outDir, { recursive: true });
+
+  const propsFile = noProps
+    ? emptyPropsFile()
+    : await fs
+        .readFile(propsFilePath, 'utf8')
+        .then((raw) => validatePropsFileV1(JSON.parse(raw)))
+        .catch(() => emptyPropsFile());
+
+  let baseUrl = url;
+  let closeServer: (() => Promise<void>) | null = null;
+
+  if (mode === 'build') {
+    await run(platformNpmBin(), ['run', 'build']);
+    const srv = await startStaticServer({ rootDir: 'dist', port: 0 });
+    baseUrl = srv.url;
+    closeServer = srv.close;
+  }
+
+  const browser = await chromium.launch();
+  const results: Array<{
+    figureId: string;
+    variantId: string;
+    size: { width: number; height: number };
+    mm?: { width: number; height: number; dpi: number };
+    outputs: { png?: string; svg?: string };
+  }> = [];
+
+  try {
+    for (const t of targets) {
+      const effectiveSize = t.variant.size ?? t.figure.size;
+      const resolved = resolveSize(effectiveSize);
+      const bg = t.variant.background ?? 'white';
+      const overrides = (propsFile.overrides[t.figure.id]?.[t.variant.id] ?? {}) as Record<string, unknown>;
+      const propsParam =
+        overrides && typeof overrides === 'object' && Object.keys(overrides).length
+          ? `?props=${encodeURIComponent(base64UrlEncode(JSON.stringify(overrides)))}`
+          : '';
+      const route = `/#/render/${encodeURIComponent(projectId)}/${encodeURIComponent(t.figure.id)}/${encodeURIComponent(t.variant.id)}${propsParam}`;
+      const pageUrl = `${baseUrl}${route}`;
+
+      // eslint-disable-next-line no-console
+      console.log(`Rendering ${t.figure.id}/${t.variant.id} (${resolved.width}×${resolved.height}px) …`);
+
+      const context = await browser.newContext({
+        viewport: { width: resolved.width, height: resolved.height },
+        deviceScaleFactor: 1
+      });
+      const page = await context.newPage();
+      page.on('pageerror', (err) => {
+        // eslint-disable-next-line no-console
+        console.error(`[pageerror] ${t.figure.id}/${t.variant.id}:`, err);
+      });
+      page.on('console', (msg) => {
+        if (msg.type() !== 'error') return;
+        // eslint-disable-next-line no-console
+        console.error(`[console.${msg.type()}] ${t.figure.id}/${t.variant.id}: ${msg.text()}`);
+      });
+      await page.goto(pageUrl, { waitUntil: 'domcontentloaded' });
+      await page.waitForFunction(() => (window as any).__IMAGINE_READY__ === true, null, { timeout: 30_000 });
+      await page.locator('#figure-root').waitFor({ state: 'attached', timeout: 30_000 });
+
+      const outputs: { png?: string; svg?: string } = {};
+      const baseName = `${safeFilePart(t.figure.id)}--${safeFilePart(t.variant.id)}`;
+
+      if (formats.has('png')) {
+        const outPath = path.join(outDir, `${baseName}.png`);
+        const locator = page.locator('#figure-root');
+        await locator.screenshot({
+          path: outPath,
+          omitBackground: bg === 'transparent',
+          animations: 'disabled'
+        });
+        outputs.png = path.relative(outDir, outPath);
+      }
+
+      if (formats.has('svg')) {
+        const outPath = path.join(outDir, `${baseName}.svg`);
+        const svg = await page.$eval('#figure-root svg', (el) => (el as SVGElement).outerHTML);
+        await fs.writeFile(outPath, `${svg}\n`, 'utf8');
+        outputs.svg = path.relative(outDir, outPath);
+      }
+
+      results.push({
+        figureId: t.figure.id,
+        variantId: t.variant.id,
+        size: { width: resolved.width, height: resolved.height },
+        mm: resolved.mm && resolved.dpi ? { width: resolved.mm.width, height: resolved.mm.height, dpi: resolved.dpi } : undefined,
+        outputs
+      });
+
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+    if (closeServer) await closeServer();
+  }
+
+  const manifestPath = path.join(outDir, 'manifest.json');
+  if (!noManifest) {
+    await fs.writeFile(
+      manifestPath,
+      JSON.stringify(
+        {
+          generatedAt: new Date().toISOString(),
+          projectId,
+          mode,
+          baseUrl,
+          results
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    // eslint-disable-next-line no-console
+    console.log(`Wrote ${manifestPath}`);
+  }
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exitCode = 1;
+});