create-imagine 0.1.0

package/templates/blank/src/studio/routes/FigureView.tsx

@@ -0,0 +1,365 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Link, useNavigate, useParams } from 'react-router-dom';
+import { inferControlsFromProps } from '../../core/controls';
+import type { FigureControl, FigureVariant, ProjectDefinition } from '../../core/manifest';
+import { resolveSize } from '../../framework/sizing';
+import { loadFigureComponent } from '../figureLoader';
+import { loadProject } from '../projectLoader';
+import { useProjectProps } from '../useProjectProps';
+
+type ZoomMode = { kind: 'fit' } | { kind: 'percent'; value: number };
+
+function useElementSize(ref: React.RefObject<HTMLElement>) {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const ro = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      setSize({ width: entry.contentRect.width, height: entry.contentRect.height });
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [ref]);
+
+  return size;
+}
+
+function coerceZoomValue(value: number) {
+  if (!Number.isFinite(value)) return 100;
+  return Math.max(5, Math.min(800, Math.round(value)));
+}
+
+export function FigureView() {
+  const navigate = useNavigate();
+  const params = useParams();
+  const projectId = params.projectId ?? '';
+  const figureId = params.figureId ?? '';
+  const variantId = params.variantId;
+  const [FigureComponent, setFigureComponent] = useState<React.ComponentType<any> | null>(null);
+  const [zoom, setZoom] = useState<ZoomMode>({ kind: 'fit' });
+  const [checker, setChecker] = useState(false);
+  const [project, setProject] = useState<ProjectDefinition | null>(null);
+  const [projectError, setProjectError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!projectId) return;
+    setProject(null);
+    setProjectError(null);
+    loadProject(projectId).then(setProject, (err) => setProjectError(String(err?.message ?? err)));
+  }, [projectId]);
+
+  const fig = project?.figures.find((f) => f.id === figureId);
+  const variant: FigureVariant | undefined = useMemo(() => {
+    if (!fig) return undefined;
+    if (variantId) return fig.variants.find((v) => v.id === variantId) ?? fig.variants[0];
+    return fig.variants[0];
+  }, [fig, variantId]);
+
+  const propsState = useProjectProps(projectId);
+
+  useEffect(() => {
+    if (!fig) return;
+    setFigureComponent(null);
+    loadFigureComponent(projectId, fig.moduleKey).then((Component) => setFigureComponent(() => Component), (err) => {
+      // eslint-disable-next-line no-console
+      console.error(err);
+      setFigureComponent(() => () => (
+        <div className="empty">
+          <div className="emptyTitle">Failed to load figure module</div>
+          <div className="emptyBody mono">{String(err?.message ?? err)}</div>
+        </div>
+      ));
+    });
+  }, [projectId, fig?.moduleKey]);
+
+  const surfaceRef = useRef<HTMLDivElement | null>(null);
+  const surfaceSize = useElementSize(surfaceRef);
+
+  const size = useMemo(() => {
+    if (!fig || !variant) return { width: 100, height: 100, source: { unit: 'px' as const, width: 100, height: 100 } };
+    return resolveSize(variant.size ?? fig.size);
+  }, [fig, variant]);
+
+  const scale = useMemo(() => {
+    if (zoom.kind === 'percent') return zoom.value / 100;
+    const pad = 24;
+    const w = Math.max(1, surfaceSize.width - pad * 2);
+    const h = Math.max(1, surfaceSize.height - pad * 2);
+    return Math.max(0.05, Math.min(8, Math.min(w / size.width, h / size.height)));
+  }, [zoom, surfaceSize.width, surfaceSize.height, size.width, size.height]);
+
+  if (projectError) {
+    return (
+      <div className="page">
+        <div className="empty">
+          <div className="emptyTitle">Failed to load project</div>
+          <div className="emptyBody mono">{projectError}</div>
+        </div>
+      </div>
+    );
+  }
+
+  if (!fig || !variant) {
+    return (
+      <div className="page">
+        <div className="empty">
+          <div className="emptyTitle">Figure not found</div>
+          <div className="emptyBody">
+            Go back to <Link to={`/project/${encodeURIComponent(projectId)}`}>project</Link>.
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  const controls: FigureControl[] = (() => {
+    const explicit = [...(fig.controls ?? []), ...(variant.controls ?? [])];
+    if (explicit.length) return explicit;
+    return inferControlsFromProps(variant.props ?? {});
+  })();
+
+  // const size = ... (already defined above)
+  const background = variant.background ?? 'white';
+  const variantOverrides = propsState.getVariantOverrides(fig.id, variant.id);
+  const effectiveVariantProps = { ...(variant.props ?? {}), ...variantOverrides };
+
+  const props = {
+    width: size.width,
+    height: size.height,
+    background,
+    ...(effectiveVariantProps as any)
+  };
+
+  const mmText = size.mm && size.dpi ? `${size.mm.width}×${size.mm.height} mm @ ${size.dpi}dpi` : null;
+
+  return (
+    <div className="page figurePage">
+      <div className="pageHeader figureHeader">
+        <div className="figureHeaderLeft">
+          <div className="pageTitle">{fig.title}</div>
+          <div className="pageSubtitle">
+            <span className="mono">{fig.id}</span> • {size.width}×{size.height} px{mmText ? ` • ${mmText}` : ''}
+          </div>
+        </div>
+        <div className="figureHeaderRight">
+          <label className="label">
+            Variant
+            <select
+              className="select"
+              value={variant.id}
+              onChange={(e) =>
+                navigate(
+                  `/project/${encodeURIComponent(projectId)}/figure/${encodeURIComponent(fig.id)}/${encodeURIComponent(
+                    e.target.value
+                  )}`
+                )
+              }
+            >
+              {fig.variants.map((v) => (
+                <option key={v.id} value={v.id}>
+                  {v.title ? `${v.title} (${v.id})` : v.id}
+                </option>
+              ))}
+            </select>
+          </label>
+
+          <div className="toolbarGroup">
+            <button className="btn btnSmall" onClick={() => setZoom({ kind: 'fit' })}>
+              Fit
+            </button>
+            <button className="btn btnSmall" onClick={() => setZoom({ kind: 'percent', value: 100 })}>
+              100%
+            </button>
+            <button className="btn btnSmall" onClick={() => setZoom({ kind: 'percent', value: 200 })}>
+              200%
+            </button>
+          </div>
+
+          <label className="label">
+            Zoom
+            <input
+              className="input"
+              type="number"
+              min={5}
+              max={800}
+              step={5}
+              value={zoom.kind === 'percent' ? zoom.value : Math.round(scale * 100)}
+              onChange={(e) => setZoom({ kind: 'percent', value: coerceZoomValue(Number(e.target.value)) })}
+            />
+          </label>
+
+          <label className="checkbox">
+            <input type="checkbox" checked={checker} onChange={(e) => setChecker(e.target.checked)} /> Checkerboard
+          </label>
+
+          <Link
+            className="btn btnSmall"
+            to={`/render/${encodeURIComponent(projectId)}/${encodeURIComponent(fig.id)}/${encodeURIComponent(variant.id)}`}
+            target="_blank"
+          >
+            Render route
+          </Link>
+        </div>
+      </div>
+
+      <div className="figureBody">
+        <div className={`previewSurface ${checker ? 'checker' : ''}`} ref={surfaceRef}>
+          <div className="previewScale" style={{ transform: `scale(${scale})` }}>
+            <div id="figure-root" style={{ width: size.width, height: size.height }}>
+              {FigureComponent ? <FigureComponent {...props} /> : <div className="loading">Loading…</div>}
+            </div>
+          </div>
+        </div>
+
+        <aside className="controlsPanel" aria-label="Controls">
+          <div className="controlsHeader">
+            <div className="controlsTitle">Controls</div>
+            <div className="controlsActions">
+              <button
+                className="btn btnSmall"
+                onClick={() => propsState.resetVariantOverrides(fig.id, variant.id)}
+                title="Clear saved overrides for this variant"
+              >
+                Reset
+              </button>
+              <button
+                className="btn btnSmall"
+                onClick={async () => {
+                  const json = JSON.stringify(variantOverrides, null, 2);
+                  try {
+                    await navigator.clipboard.writeText(json);
+                  } catch {
+                    window.prompt('Copy overrides JSON:', json);
+                  }
+                }}
+                title="Copy overrides JSON"
+              >
+                Copy JSON
+              </button>
+            </div>
+          </div>
+
+          <div className="controlsStatus">
+            {propsState.readOnly ? (
+              <span className="statusMuted" title={propsState.loadError ?? undefined}>
+                Saving disabled
+              </span>
+            ) : propsState.saveStatus === 'saving' ? (
+              <span className="statusMuted">Saving…</span>
+            ) : propsState.saveStatus === 'saved' ? (
+              <span className="statusOk">Saved</span>
+            ) : propsState.saveStatus === 'error' ? (
+              <span className="statusErr">Save failed</span>
+            ) : (
+              <span className="statusMuted">Edits auto-save</span>
+            )}
+            {propsState.saveError ? <div className="statusErr mono">{propsState.saveError}</div> : null}
+          </div>
+
+          {controls.length ? (
+            <div className="controlsGrid">
+              {controls.map((c, idx) => {
+                const key = c.key;
+                const label = c.label ?? key;
+                const currentValue = (effectiveVariantProps as any)[key];
+
+                if (c.kind === 'text') {
+                  const value = typeof currentValue === 'string' ? currentValue : currentValue == null ? '' : String(currentValue);
+                  return (
+                    <label key={`${key}:${idx}`} className="control">
+                      <div className="controlLabel">{label}</div>
+                      {c.multiline ? (
+                        <textarea
+                          className="textarea"
+                          rows={5}
+                          placeholder={c.placeholder}
+                          value={value}
+                          onChange={(e) => propsState.setVariantOverride(fig.id, variant.id, key, e.target.value)}
+                        />
+                      ) : (
+                        <input
+                          className="input"
+                          type="text"
+                          placeholder={c.placeholder}
+                          value={value}
+                          onChange={(e) => propsState.setVariantOverride(fig.id, variant.id, key, e.target.value)}
+                        />
+                      )}
+                    </label>
+                  );
+                }
+
+                if (c.kind === 'number') {
+                  const value = typeof currentValue === 'number' && Number.isFinite(currentValue) ? String(currentValue) : '';
+                  return (
+                    <label key={`${key}:${idx}`} className="control">
+                      <div className="controlLabel">{label}</div>
+                      <input
+                        className="input"
+                        type="number"
+                        min={c.min}
+                        max={c.max}
+                        step={c.step}
+                        value={value}
+                        onChange={(e) => {
+                          const s = e.target.value;
+                          if (!s) propsState.setVariantOverride(fig.id, variant.id, key, undefined);
+                          else {
+                            const n = Number(s);
+                            propsState.setVariantOverride(fig.id, variant.id, key, Number.isFinite(n) ? n : undefined);
+                          }
+                        }}
+                      />
+                    </label>
+                  );
+                }
+
+                if (c.kind === 'boolean') {
+                  const checked = Boolean(currentValue);
+                  return (
+                    <label key={`${key}:${idx}`} className="control controlCheckbox">
+                      <input
+                        type="checkbox"
+                        checked={checked}
+                        onChange={(e) => propsState.setVariantOverride(fig.id, variant.id, key, e.target.checked)}
+                      />
+                      <div className="controlLabel">{label}</div>
+                    </label>
+                  );
+                }
+
+                if (c.kind === 'select') {
+                  const value = typeof currentValue === 'string' ? currentValue : currentValue == null ? '' : String(currentValue);
+                  return (
+                    <label key={`${key}:${idx}`} className="control">
+                      <div className="controlLabel">{label}</div>
+                      <select
+                        className="select"
+                        value={value}
+                        onChange={(e) => propsState.setVariantOverride(fig.id, variant.id, key, e.target.value)}
+                      >
+                        {c.options.map((opt) => (
+                          <option key={opt.value} value={opt.value}>
+                            {opt.label}
+                          </option>
+                        ))}
+                      </select>
+                    </label>
+                  );
+                }
+
+                return null;
+              })}
+            </div>
+          ) : (
+            <div className="controlsEmpty">No editable props found.</div>
+          )}
+        </aside>
+      </div>
+    </div>
+  );
+}

package/templates/blank/src/studio/routes/ProjectHome.tsx

@@ -0,0 +1,107 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Link, useParams } from 'react-router-dom';
+import type { ProjectDefinition } from '../../core/manifest';
+import { resolveSize } from '../../framework/sizing';
+import { loadProject } from '../projectLoader';
+
+export function ProjectHome() {
+  const params = useParams();
+  const projectId = params.projectId ?? '';
+  const [project, setProject] = useState<ProjectDefinition | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!projectId) return;
+    setProject(null);
+    setError(null);
+    loadProject(projectId).then(setProject, (err) => setError(String(err?.message ?? err)));
+  }, [projectId]);
+
+  const examples = project?.examples ?? [];
+
+  const figures = useMemo(() => project?.figures ?? [], [project]);
+
+  if (error) {
+    return (
+      <div className="page">
+        <div className="empty">
+          <div className="emptyTitle">Failed to load project</div>
+          <div className="emptyBody mono">{error}</div>
+        </div>
+      </div>
+    );
+  }
+
+  if (!project) {
+    return (
+      <div className="page">
+        <div className="loading">Loading…</div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="page">
+      <div className="pageHeader">
+        <div>
+          <div className="pageTitle">{project.title}</div>
+          <div className="pageSubtitle">
+            <span className="mono">{project.id}</span>
+            {project.description ? ` • ${project.description}` : ''}
+          </div>
+        </div>
+      </div>
+
+      {examples.length ? (
+        <div className="section">
+          <div className="sectionTitle">Gallery</div>
+          <div className="galleryGrid">
+            {examples.map((ex) => (
+              <Link
+                key={`${ex.figureId}/${ex.variantId}`}
+                className="galleryItem"
+                to={`/project/${encodeURIComponent(project.id)}/figure/${encodeURIComponent(ex.figureId)}/${encodeURIComponent(
+                  ex.variantId
+                )}`}
+              >
+                <img className="galleryImg" src={ex.src} alt={ex.caption ?? `${ex.figureId}/${ex.variantId}`} loading="lazy" />
+                <div className="galleryCaption">{ex.caption ?? `${ex.figureId}/${ex.variantId}`}</div>
+              </Link>
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      <div className="section">
+        <div className="sectionTitle">Figures</div>
+        <div className="cardGrid">
+          {figures.map((f) => {
+            const r = resolveSize(f.size);
+            const mmText = r.mm && r.dpi ? ` (${r.mm.width}×${r.mm.height} mm @ ${r.dpi}dpi)` : '';
+            return (
+              <Link
+                key={f.id}
+                to={`/project/${encodeURIComponent(project.id)}/figure/${encodeURIComponent(f.id)}`}
+                className="card"
+              >
+                <div className="cardTitle">{f.title}</div>
+                <div className="cardBody">
+                  <div className="cardMeta">
+                    <span className="mono">{f.id}</span>
+                  </div>
+                  <div className="cardMeta">
+                    {r.width}×{r.height} px{mmText}
+                  </div>
+                  <div className="cardMeta">
+                    {f.variants.length} variant{f.variants.length === 1 ? '' : 's'}
+                  </div>
+                </div>
+              </Link>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
+

package/templates/blank/src/studio/routes/ProjectsHome.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useState } from 'react';
+import { Link } from 'react-router-dom';
+import type { ProjectDefinition } from '../../core/manifest';
+import { loadAllProjects } from '../projectLoader';
+
+export function ProjectsHome() {
+  const [projects, setProjects] = useState<ProjectDefinition[] | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadAllProjects().then(setProjects, (err) => setError(String(err?.message ?? err)));
+  }, []);
+
+  return (
+    <div className="page">
+      <div className="pageHeader">
+        <div>
+          <div className="pageTitle">Projects</div>
+          <div className="pageSubtitle">
+            Create a folder in <span className="mono">{'projects/<id>'}</span> to add a new project (restart dev server).
+          </div>
+        </div>
+      </div>
+
+      {error ? (
+        <div className="empty">
+          <div className="emptyTitle">Failed to load projects</div>
+          <div className="emptyBody mono">{error}</div>
+        </div>
+      ) : null}
+
+      <div className="cardGrid">
+        {(projects ?? []).map((p) => (
+          <Link key={p.id} to={`/project/${encodeURIComponent(p.id)}`} className="card projectCard">
+            <div className="cardTitle">{p.title}</div>
+            <div className="cardBody">
+              <div className="cardMeta">
+                <span className="mono">{p.id}</span>
+                <span className="dot">•</span>
+                <span>{p.figures.length} figures</span>
+              </div>
+              {p.description ? <div className="cardMeta">{p.description}</div> : null}
+              {p.examples?.length ? (
+                <div className="thumbRow" aria-label="Example previews">
+                  {p.examples.slice(0, 3).map((ex) => (
+                    <img
+                      key={`${ex.figureId}/${ex.variantId}`}
+                      className="thumb"
+                      src={ex.src}
+                      alt={ex.caption ?? `${ex.figureId}/${ex.variantId}`}
+                      loading="lazy"
+                    />
+                  ))}
+                </div>
+              ) : null}
+            </div>
+          </Link>
+        ))}
+        {!projects && !error ? <div className="loading">Loading…</div> : null}
+      </div>
+    </div>
+  );
+}

package/templates/blank/src/studio/routes/RenderView.tsx

@@ -0,0 +1,123 @@
+import { useEffect, useMemo, useState } from 'react';
+import { useLocation, useParams } from 'react-router-dom';
+import type { FigureVariant, ProjectDefinition } from '../../core/manifest';
+import { resolveSize } from '../../framework/sizing';
+import { loadFigureComponent } from '../figureLoader';
+import { waitForMathTasks } from '../../framework/math/mathjax';
+import { loadProject } from '../projectLoader';
+import { base64UrlDecodeToString } from '../base64url';
+
+declare global {
+  interface Window {
+    __IMAGINE_READY__?: boolean;
+  }
+}
+
+function setPageBackground(bg: 'white' | 'transparent') {
+  const val = bg === 'transparent' ? 'transparent' : '#ffffff';
+  document.documentElement.style.background = val;
+  document.body.style.background = val;
+}
+
+async function waitForPendingMathDom(maxMs: number) {
+  const start = Date.now();
+  while (Date.now() - start < maxMs) {
+    const pending = document.querySelector('[data-imagine-math="pending"]');
+    if (!pending) return;
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+export function RenderView() {
+  const location = useLocation();
+  const params = useParams();
+  const projectId = params.projectId ?? '';
+  const figureId = params.figureId ?? '';
+  const variantId = params.variantId;
+  const [FigureComponent, setFigureComponent] = useState<React.ComponentType<any> | null>(null);
+  const [project, setProject] = useState<ProjectDefinition | null>(null);
+
+  const propsOverride = useMemo(() => {
+    const encoded = new URLSearchParams(location.search).get('props');
+    if (!encoded) return null;
+    try {
+      const decoded = base64UrlDecodeToString(encoded);
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+      return parsed as Record<string, unknown>;
+    } catch {
+      return null;
+    }
+  }, [location.search]);
+
+  useEffect(() => {
+    if (!projectId) return;
+    setProject(null);
+    loadProject(projectId).then(setProject, (err) => {
+      // eslint-disable-next-line no-console
+      console.error(err);
+      setProject(() => null);
+      window.__IMAGINE_READY__ = true;
+    });
+  }, [projectId]);
+
+  const fig = project?.figures.find((f) => f.id === figureId);
+  const variant: FigureVariant | undefined = useMemo(() => {
+    if (!fig) return undefined;
+    if (variantId) return fig.variants.find((v) => v.id === variantId) ?? fig.variants[0];
+    return fig.variants[0];
+  }, [fig, variantId]);
+
+  useEffect(() => {
+    window.__IMAGINE_READY__ = false;
+    if (!fig) return;
+    setFigureComponent(null);
+    loadFigureComponent(projectId, fig.moduleKey).then((Component) => setFigureComponent(() => Component), (err) => {
+      // eslint-disable-next-line no-console
+      console.error(err);
+      setFigureComponent(() => () => null);
+    });
+  }, [projectId, fig?.moduleKey]);
+
+  useEffect(() => {
+    if (!fig || !variant || !FigureComponent) return;
+    (async () => {
+      window.__IMAGINE_READY__ = false;
+      document.body.style.margin = '0';
+      const bg = (variant?.background ?? 'white') as 'white' | 'transparent';
+      setPageBackground(bg);
+
+      await (document as any).fonts?.ready?.catch(() => undefined);
+
+      // Let figure effects run at least once, then wait for math (if any).
+      await new Promise((r) => setTimeout(r, 0));
+      await Promise.race([waitForMathTasks(), new Promise((r) => setTimeout(r, 30_000))]);
+      await waitForPendingMathDom(30_000);
+
+      await new Promise(requestAnimationFrame);
+      window.__IMAGINE_READY__ = true;
+    })().catch((err) => {
+      // eslint-disable-next-line no-console
+      console.error(err);
+      window.__IMAGINE_READY__ = true;
+    });
+  }, [fig?.id, variant?.id, variant?.background, FigureComponent, location.search]);
+
+  if (!fig || !variant) return null;
+
+  const size = resolveSize(variant.size ?? fig.size);
+  const background = variant.background ?? 'white';
+  const mergedProps = { ...(variant.props ?? {}), ...(propsOverride ?? {}) };
+  const props = {
+    width: size.width,
+    height: size.height,
+    background,
+    ...(mergedProps as any)
+  };
+
+  return (
+    <div id="figure-root" style={{ width: size.width, height: size.height, overflow: 'hidden' }}>
+      {FigureComponent ? <FigureComponent {...props} /> : null}
+    </div>
+  );
+}