create-imagine 0.1.0

package/templates/blank/src/framework/math/mathjax.ts

@@ -0,0 +1,64 @@
+type MathJaxGlobal = {
+  startup?: { promise?: Promise<unknown> };
+  tex2svgPromise?: (tex: string, options?: unknown) => Promise<unknown>;
+};
+
+declare global {
+  interface Window {
+    MathJax?: MathJaxGlobal;
+    __IMAGINE_MATH_PENDING__?: number;
+    __IMAGINE_MATH_WAITERS__?: Array<() => void>;
+  }
+}
+
+let loadPromise: Promise<void> | null = null;
+
+export async function loadMathJax(): Promise<void> {
+  if (typeof window === 'undefined') return;
+  if (window.MathJax?.tex2svgPromise) return;
+  if (loadPromise) return loadPromise;
+
+  loadPromise = new Promise<void>((resolve, reject) => {
+    const url = import.meta.env.VITE_MATHJAX_URL ?? 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js';
+
+    window.MathJax = {
+      ...window.MathJax,
+      svg: { ...(window.MathJax as any)?.svg, fontCache: 'global' }
+    } as MathJaxGlobal;
+
+    const script = document.createElement('script');
+    script.async = true;
+    script.src = url;
+    script.addEventListener('load', () => resolve());
+    script.addEventListener('error', () => reject(new Error(`Failed to load MathJax from ${url}`)));
+    document.head.appendChild(script);
+  }).then(async () => {
+    await window.MathJax?.startup?.promise?.catch(() => undefined);
+  });
+
+  return loadPromise;
+}
+
+export function trackMathTask(task: Promise<unknown>): void {
+  if (typeof window === 'undefined') return;
+  window.__IMAGINE_MATH_PENDING__ = (window.__IMAGINE_MATH_PENDING__ ?? 0) + 1;
+
+  task.finally(() => {
+    window.__IMAGINE_MATH_PENDING__ = Math.max(0, (window.__IMAGINE_MATH_PENDING__ ?? 1) - 1);
+    if (window.__IMAGINE_MATH_PENDING__ === 0 && window.__IMAGINE_MATH_WAITERS__?.length) {
+      const waiters = window.__IMAGINE_MATH_WAITERS__;
+      window.__IMAGINE_MATH_WAITERS__ = [];
+      waiters.forEach((w) => w());
+    }
+  });
+}
+
+export function waitForMathTasks(): Promise<void> {
+  if (typeof window === 'undefined') return Promise.resolve();
+  if ((window.__IMAGINE_MATH_PENDING__ ?? 0) === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    window.__IMAGINE_MATH_WAITERS__ = window.__IMAGINE_MATH_WAITERS__ ?? [];
+    window.__IMAGINE_MATH_WAITERS__.push(resolve);
+  });
+}

package/templates/blank/src/framework/sizing.ts

@@ -0,0 +1,28 @@
+import type { FigureSize, ResolvedSize } from './types';
+
+export const MM_PER_INCH = 25.4;
+
+export function mmToPx(mm: number, dpi: number): number {
+  return Math.round((mm / MM_PER_INCH) * dpi);
+}
+
+export function pxToMm(px: number, dpi: number): number {
+  return (px / dpi) * MM_PER_INCH;
+}
+
+export function resolveSize(size: FigureSize): ResolvedSize {
+  if (size.unit === 'px') {
+    return { width: size.width, height: size.height, source: size };
+  }
+
+  const width = mmToPx(size.width, size.dpi);
+  const height = mmToPx(size.height, size.dpi);
+  return {
+    width,
+    height,
+    dpi: size.dpi,
+    mm: { width: size.width, height: size.height },
+    source: size
+  };
+}
+

package/templates/blank/src/framework/theme.ts

@@ -0,0 +1,35 @@
+export const theme = {
+  fontFamily:
+    "ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Arial, 'Noto Sans', 'Liberation Sans', sans-serif",
+  monoFontFamily:
+    "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
+  colors: {
+    text: '#111827',
+    subtleText: '#4B5563',
+    grid: '#E5E7EB',
+    axis: '#111827',
+    bg: '#FFFFFF',
+    panel: '#F9FAFB',
+    blue: '#2563EB',
+    teal: '#0F766E',
+    orange: '#C2410C',
+    red: '#B91C1C'
+  },
+  strokes: {
+    thin: 1,
+    normal: 1.5,
+    thick: 2.5
+  },
+  radii: {
+    sm: 6,
+    md: 10
+  },
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 24
+  }
+} as const;
+

package/templates/blank/src/framework/types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+
+export type FigureId = string;
+
+export type FigureSize =
+  | { unit: 'px'; width: number; height: number }
+  | { unit: 'mm'; width: number; height: number; dpi: number };
+
+export type FigureVariant = {
+  id: string;
+  title?: string;
+  props?: unknown;
+  size?: FigureSize;
+  background?: 'white' | 'transparent';
+};
+
+export type FigureManifestItem = {
+  id: FigureId;
+  title: string;
+  moduleKey: string;
+  size: FigureSize;
+  variants: FigureVariant[];
+};
+
+export type FigureComponentBaseProps = {
+  width: number;
+  height: number;
+  background?: 'white' | 'transparent';
+};
+
+export type FigureComponent<Props extends Record<string, unknown> = Record<string, unknown>> = (
+  props: FigureComponentBaseProps & Props
+) => ReactNode;
+
+export type ResolvedSize = {
+  width: number;
+  height: number;
+  dpi?: number;
+  mm?: { width: number; height: number };
+  source: FigureSize;
+};
+

package/templates/blank/src/main.tsx

@@ -0,0 +1,11 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { StudioRoot } from './studio/StudioRoot';
+import './studio/studio.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <StudioRoot />
+  </React.StrictMode>
+);
+

package/templates/blank/src/studio/StudioApp.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Link, Route, Routes, useMatch, useNavigate } from 'react-router-dom';
+import type { ProjectDefinition } from '../core/manifest';
+import { loadAllProjects } from './projectLoader';
+import { ProjectsHome } from './routes/ProjectsHome';
+import { ProjectHome } from './routes/ProjectHome';
+import { FigureView } from './routes/FigureView';
+
+function useActiveProjectId(): string | null {
+  const match = useMatch('/project/:projectId/*');
+  return match?.params.projectId ?? null;
+}
+
+function useActiveFigureId(): string | null {
+  const match = useMatch('/project/:projectId/figure/:figureId/*');
+  return match?.params.figureId ?? null;
+}
+
+export function StudioApp() {
+  const navigate = useNavigate();
+  const activeId = useActiveFigureId();
+  const activeProjectId = useActiveProjectId();
+  const [query, setQuery] = useState('');
+  const [projects, setProjects] = useState<ProjectDefinition[] | null>(null);
+  const [projectsError, setProjectsError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadAllProjects().then(setProjects, (err) => setProjectsError(String(err?.message ?? err)));
+  }, []);
+
+  const activeProject = useMemo(() => {
+    if (!projects || !activeProjectId) return null;
+    return projects.find((p) => p.id === activeProjectId) ?? null;
+  }, [projects, activeProjectId]);
+
+  const filteredFigures = useMemo(() => {
+    if (!activeProject) return [];
+    const q = query.trim().toLowerCase();
+    if (!q) return activeProject.figures;
+    return activeProject.figures.filter((f) => f.id.toLowerCase().includes(q) || f.title.toLowerCase().includes(q));
+  }, [activeProject, query]);
+
+  return (
+    <div className="studio">
+      <aside className="sidebar">
+        <div className="sidebarHeader">
+          <div className="sidebarTitleRow">
+            <div className="sidebarTitle">Imagine Studio</div>
+            <button className="btn btnSmall" onClick={() => navigate('/')}>
+              Home
+            </button>
+          </div>
+        </div>
+
+        <div className="sidebarSection">
+          <div className="sidebarSectionTitle">Projects</div>
+          <nav className="projectList" aria-label="Projects">
+            {projects?.map((p) => {
+              const active = activeProjectId === p.id;
+              return (
+                <Link key={p.id} className={`projectItem ${active ? 'active' : ''}`} to={`/project/${encodeURIComponent(p.id)}`}>
+                  <div className="projectItemTitle">{p.title}</div>
+                  <div className="projectItemMeta">
+                    <span className="mono">{p.id}</span>
+                    <span className="dot">•</span>
+                    <span>{p.figures.length} figure{p.figures.length === 1 ? '' : 's'}</span>
+                  </div>
+                </Link>
+              );
+            })}
+            {projectsError ? <div className="sidebarError">{projectsError}</div> : null}
+            {!projects && !projectsError ? <div className="sidebarHint">Loading…</div> : null}
+          </nav>
+        </div>
+
+        {activeProject ? (
+          <div className="sidebarSection">
+            <div className="sidebarSectionTitle">Figures</div>
+            <input
+              className="search"
+              placeholder={`Search in ${activeProject.title}…`}
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+            />
+            <nav className="figureList" aria-label="Figures">
+              {filteredFigures.map((f) => {
+                const active = activeId === f.id;
+                return (
+                  <Link
+                    key={f.id}
+                    className={`figureItem ${active ? 'active' : ''}`}
+                    to={`/project/${encodeURIComponent(activeProject.id)}/figure/${encodeURIComponent(f.id)}`}
+                  >
+                    <div className="figureItemTitle">{f.title}</div>
+                    <div className="figureItemMeta">
+                      <span className="mono">{f.id}</span>
+                      <span className="dot">•</span>
+                      <span>
+                        {f.variants.length} variant{f.variants.length === 1 ? '' : 's'}
+                      </span>
+                    </div>
+                  </Link>
+                );
+              })}
+            </nav>
+          </div>
+        ) : null}
+      </aside>
+
+      <main className="main">
+        <Routes>
+          <Route path="/" element={<ProjectsHome />} />
+          <Route path="/project/:projectId" element={<ProjectHome />} />
+          <Route path="/project/:projectId/figure/:figureId/:variantId?" element={<FigureView />} />
+          <Route
+            path="*"
+            element={
+              <div className="empty">
+                <div className="emptyTitle">Not found</div>
+                <div className="emptyBody">
+                  Go back to <Link to="/">home</Link>.
+                </div>
+              </div>
+            }
+          />
+        </Routes>
+      </main>
+    </div>
+  );
+}

package/templates/blank/src/studio/StudioRoot.tsx

@@ -0,0 +1,14 @@
+import { HashRouter, Route, Routes } from 'react-router-dom';
+import { RenderView } from './routes/RenderView';
+import { StudioApp } from './StudioApp';
+
+export function StudioRoot() {
+  return (
+    <HashRouter>
+      <Routes>
+        <Route path="/render/:projectId/:figureId/:variantId?" element={<RenderView />} />
+        <Route path="/*" element={<StudioApp />} />
+      </Routes>
+    </HashRouter>
+  );
+}

package/templates/blank/src/studio/base64url.ts

@@ -0,0 +1,8 @@
+export function base64UrlDecodeToString(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  const binary = atob(padded);
+  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+

package/templates/blank/src/studio/figureLoader.ts

@@ -0,0 +1,30 @@
+import type { ComponentType } from 'react';
+
+type FigureModule = { default: ComponentType<any> };
+
+const modules = import.meta.glob<FigureModule>('../../projects/*/figures/*.tsx');
+
+const byProject: Record<string, Record<string, () => Promise<FigureModule>>> = {};
+for (const [modulePath, loader] of Object.entries(modules)) {
+  const match = modulePath.match(/projects\/([^/]+)\/figures\/([^/]+)\.tsx$/);
+  if (!match) continue;
+  const projectId = match[1]!;
+  const moduleKey = match[2]!;
+  byProject[projectId] = byProject[projectId] ?? {};
+  byProject[projectId]![moduleKey] = loader;
+}
+
+export function availableFigureModuleKeys(projectId: string): string[] {
+  return Object.keys(byProject[projectId] ?? {}).sort();
+}
+
+export async function loadFigureComponent(projectId: string, moduleKey: string): Promise<ComponentType<any>> {
+  const loader = byProject[projectId]?.[moduleKey];
+  if (!loader) {
+    throw new Error(
+      `Unknown moduleKey "${moduleKey}" for project "${projectId}". Available: ${availableFigureModuleKeys(projectId).join(', ')}`
+    );
+  }
+  const mod = await loader();
+  return mod.default;
+}

package/templates/blank/src/studio/projectLoader.ts

@@ -0,0 +1,40 @@
+import type { ProjectDefinition } from '../core/manifest';
+
+type ProjectModule = { default: ProjectDefinition };
+
+const modules = import.meta.glob<ProjectModule>('../../projects/*/project.ts');
+
+const byId: Record<string, () => Promise<ProjectModule>> = Object.fromEntries(
+  Object.entries(modules)
+    .map(([modulePath, loader]) => {
+      const match = modulePath.match(/projects\/([^/]+)\/project\.ts$/);
+      if (!match) return null;
+      return [match[1]!, loader] as const;
+    })
+    .filter((x): x is readonly [string, () => Promise<ProjectModule>] => Boolean(x))
+);
+
+const cache = new Map<string, Promise<ProjectDefinition>>();
+
+export function availableProjectIds(): string[] {
+  return Object.keys(byId).sort();
+}
+
+export async function loadProject(projectId: string): Promise<ProjectDefinition> {
+  const loader = byId[projectId];
+  if (!loader) throw new Error(`Unknown projectId "${projectId}". Available: ${availableProjectIds().join(', ')}`);
+
+  const cached = cache.get(projectId);
+  if (cached) return cached;
+
+  const promise = loader().then((m) => m.default);
+  cache.set(projectId, promise);
+  return promise;
+}
+
+export async function loadAllProjects(): Promise<ProjectDefinition[]> {
+  const ids = availableProjectIds();
+  const projects = await Promise.all(ids.map((id) => loadProject(id)));
+  return projects.slice().sort((a, b) => a.title.localeCompare(b.title));
+}
+

package/templates/blank/src/studio/propsApi.ts

@@ -0,0 +1,26 @@
+import { emptyPropsFile, validatePropsFileV1, type PropsFileV1 } from '../core/manifest';
+
+function propsUrl(projectId: string): string {
+  const u = new URL('/__imagine/props', window.location.origin);
+  u.searchParams.set('projectId', projectId);
+  return u.toString();
+}
+
+export async function fetchPropsFile(projectId: string): Promise<PropsFileV1> {
+  const res = await fetch(propsUrl(projectId), { method: 'GET' });
+  if (!res.ok) throw new Error(`GET props failed: ${res.status} ${res.statusText}`);
+  const json = await res.json();
+  return validatePropsFileV1(json);
+}
+
+export async function savePropsFile(projectId: string, file: PropsFileV1): Promise<void> {
+  const res = await fetch(propsUrl(projectId), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(file)
+  });
+  if (!res.ok) throw new Error(`POST props failed: ${res.status} ${res.statusText}`);
+}
+
+export { emptyPropsFile };
+