@1agh/maude 0.16.0 → 0.17.1

package/plugins/design/dev-server/exporters/html.ts

@@ -0,0 +1,103 @@
+// Phase 6.5 T5 — HTML adapter (standalone bundler).
+//
+// Renders the target through Playwright, emits a self-contained `index.html`
+// with all stylesheets inlined (fonts + remote images still referenced by
+// origin — full asset inlining is a follow-up). Output is always a ZIP per
+// plan T5 ("Always zipped (multi-file)"), even for a single artboard,
+// because the consuming workflow typically wants one bundle per export.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import JSZip from 'jszip';
+
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  canvasShellUrl,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+const HTML_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_html-playwright.mjs');
+
+async function captureHtml(
+  target: Extract<Target, { kind: 'element' }>,
+  ctx: ExportContext,
+  outDir: string,
+  timeoutSec: number
+): Promise<string[]> {
+  const args = [
+    HTML_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, target.file),
+    '--selector',
+    target.cssPath,
+    '--timeout',
+    String(timeoutSec),
+  ];
+  if (target.multi) {
+    args.push('--multi', '1', '--out-dir', outDir);
+  } else {
+    args.push('--widen-to-artboard', '1', '--out', path.join(outDir, `${target.canvasSlug}.html`));
+  }
+  const proc = Bun.spawn(['node', ...args], {
+    cwd: path.dirname(HTML_PLAYWRIGHT),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`_html-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('html adapter requires element targets (got file-tree)');
+  }
+  const timeoutSec = (options.timeoutSec as number | undefined) ?? 8;
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-html-'));
+  try {
+    const written: string[] = [];
+    for (const t of elementTargets) {
+      const paths = await captureHtml(t, ctx, tmp, timeoutSec);
+      written.push(...paths);
+    }
+    if (!written.length) {
+      return { filename: 'export.zip', contentType: 'application/zip', body: new Uint8Array(0) };
+    }
+    const zip = new JSZip();
+    for (const p of written) {
+      zip.file(path.basename(p), new Uint8Array(readFileSync(p)));
+    }
+    const zipBytes = await zip.generateAsync({ type: 'uint8array', compression: 'DEFLATE' });
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    return {
+      filename: `${baseSlug}.html.zip`,
+      contentType: 'application/zip',
+      body: zipBytes,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/plugins/design/dev-server/exporters/index.ts

@@ -0,0 +1,135 @@
+// Phase 6.5 T1 — adapter registry + dispatch.
+//
+// Each format adapter exports a single `run(targets, options, ctx) → Result`
+// function. This module owns the (format → adapter) lookup and the shared
+// `Result` envelope. Stub adapters live in `./{png,pdf,svg,html,pptx,canva,zip}.ts`
+// and currently return zero-byte payloads with valid MIME types — T2…T7
+// replace them with real renderers.
+
+import path from 'node:path';
+
+import * as canva from './canva.ts';
+import * as html from './html.ts';
+import * as pdf from './pdf.ts';
+import * as png from './png.ts';
+import * as pptx from './pptx.ts';
+import { type ResolveScopeArgs, type Scope, type Target, resolveScope } from './scope.ts';
+import * as svg from './svg.ts';
+import * as zip from './zip.ts';
+
+export type Format = 'png' | 'pdf' | 'svg' | 'html' | 'pptx' | 'canva' | 'zip';
+
+export const FORMATS: readonly Format[] = ['png', 'pdf', 'svg', 'html', 'pptx', 'canva', 'zip'];
+
+/** Options bag forwarded to the adapter. Format-specific keys are validated by each adapter. */
+export type ExportOptions = Record<string, unknown>;
+
+export interface ExportContext {
+  /** Absolute design root (e.g. /abs/.design). */
+  designRoot: string;
+  /** Absolute repo root. */
+  repoRoot: string;
+  /** Dev-server origin including port (`http://localhost:NNNN`) — adapters that render via Playwright resolve canvas URLs against this. */
+  serverOrigin: string;
+  /**
+   * designRoot-relative path to the tokens CSS file (e.g. `system/colors_and_type.css`).
+   * Threaded into the `?tokens=` query param on the canvas-shell URL so the
+   * standalone shell actually loads the project's design tokens — without it
+   * `var(--bg-0)` resolves to nothing and renders blank.
+   */
+  tokensCssRel?: string;
+  /** designRoot-relative path to a shared components CSS file (optional). */
+  componentsCssRel?: string;
+}
+
+export interface ExportResult {
+  /** Final filename (no path). E.g. `mockup.pdf` or `mockup.zip`. */
+  filename: string;
+  /** MIME type for the Content-Disposition / Content-Type header. */
+  contentType: string;
+  /** Payload bytes. T1 stubs return zero-byte placeholders. */
+  body: Uint8Array;
+}
+
+export interface Adapter {
+  run(targets: Target[], options: ExportOptions, ctx: ExportContext): Promise<ExportResult>;
+}
+
+const REGISTRY: Record<Format, Adapter> = {
+  png,
+  pdf,
+  svg,
+  html,
+  pptx,
+  canva,
+  zip,
+};
+
+export function getAdapter(format: Format): Adapter | null {
+  return REGISTRY[format] ?? null;
+}
+
+export function isFormat(s: unknown): s is Format {
+  return typeof s === 'string' && (FORMATS as readonly string[]).includes(s);
+}
+
+export function isScope(s: unknown): s is Scope {
+  return s === 'selection' || s === 'artboard' || s === 'canvas-as-separate' || s === 'project-raw';
+}
+
+/**
+ * One-shot dispatch — resolve scope, look up adapter, run it. The HTTP layer
+ * is a thin shell over this so CLI/slash can call the same path without
+ * re-implementing the orchestration.
+ */
+export async function runExport(args: {
+  format: Format;
+  scope: Scope;
+  options: ExportOptions;
+  resolve: Omit<ResolveScopeArgs, 'scope'>;
+  ctx: ExportContext;
+}): Promise<ExportResult> {
+  const targets = await resolveScope({ ...args.resolve, scope: args.scope });
+  const adapter = getAdapter(args.format);
+  if (!adapter) {
+    throw new Error(`unknown format: ${args.format}`);
+  }
+  return adapter.run(targets, args.options, args.ctx);
+}
+
+export { resolveScope };
+export type { Scope, Target };
+
+/**
+ * Build the `_canvas-shell.html?canvas=…&tokens=…&components=…` URL the
+ * playwright shims navigate to. Three normalisations the shell expects:
+ *
+ *   1. `canvas=` is a **designRoot-relative** path (`ui/Foo.tsx`), NOT a
+ *      repo-relative one (`.design/ui/Foo.tsx`). Without the strip the shell
+ *      builds `/.design/.design/ui/Foo.tsx` and 404s.
+ *   2. `tokens=` is the designRoot-relative path to the project's tokens CSS.
+ *      The shell only loads `<link id="canvas-tokens">` when this is set —
+ *      missing it means every `var(--bg-0)` etc. resolves to undefined and
+ *      the rendered DOM looks blank in screenshots.
+ *   3. `components=` (optional) — designRoot-relative path to a shared
+ *      components CSS file. Same shell behaviour as tokens.
+ *
+ * `_active.json.active` leaks the prefixed form straight through; this helper
+ * is the single normalization point. `ctx.tokensCssRel` is supplied by the
+ * HTTP handler from `cfg.tokensCssRel`.
+ */
+export function canvasShellUrl(ctx: ExportContext, file: string): string {
+  const designRel = path.basename(ctx.designRoot);
+  const stripPrefix = `${designRel}/`;
+  const rel = file.startsWith(stripPrefix) ? file.slice(stripPrefix.length) : file;
+  const params = new URLSearchParams();
+  params.set('canvas', rel);
+  if (ctx.tokensCssRel) params.set('tokens', ctx.tokensCssRel);
+  if (ctx.componentsCssRel) params.set('components', ctx.componentsCssRel);
+  // Suppress dev-server overlays (tool palette, mini-map, halos, pins, snap
+  // guides, annotation chrome) so the export captures only the artboard
+  // content. The shell's tiny <style id="canvas-hide-chrome"> rule flips
+  // active when this is set.
+  params.set('hide-chrome', '1');
+  return `${ctx.serverOrigin}/_canvas-shell.html?${params.toString()}`;
+}

package/plugins/design/dev-server/exporters/pdf.ts

@@ -0,0 +1,109 @@
+// Phase 6.5 T3 — PDF adapter (Playwright page.pdf, vector-faithful).
+//
+// Uses Chromium's print-to-PDF pipeline so the output is a TRUE vector PDF —
+// selectable text, web fonts embedded, SVG primitives kept as paths. The old
+// pdf-lib-over-PNG approach (which the user correctly complained was raster)
+// is gone; this adapter is now ~50 lines because Chromium does the work.
+//
+// Multi-target rendering: one PDF per target via the playwright shim, then
+// pdf-lib concatenates pages into a single document.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { PDFDocument } from 'pdf-lib';
+
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  canvasShellUrl,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+const PDF_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_pdf-playwright.mjs');
+
+async function capturePdf(
+  target: Extract<Target, { kind: 'element' }>,
+  ctx: ExportContext,
+  outDir: string,
+  timeoutSec: number
+): Promise<string[]> {
+  const args = [
+    PDF_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, target.file),
+    '--selector',
+    target.cssPath,
+    '--timeout',
+    String(timeoutSec),
+  ];
+  if (target.multi) args.push('--multi', '1', '--out-dir', outDir);
+  else args.push('--out', path.join(outDir, `${target.canvasSlug}.pdf`));
+
+  const proc = Bun.spawn(['node', ...args], {
+    cwd: path.dirname(PDF_PLAYWRIGHT),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`_pdf-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('pdf adapter requires element targets (got file-tree)');
+  }
+  const timeoutSec = (options.timeoutSec as number | undefined) ?? 12;
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-pdf-'));
+  try {
+    const written: string[] = [];
+    for (const t of elementTargets) {
+      const paths = await capturePdf(t, ctx, tmp, timeoutSec);
+      written.push(...paths);
+    }
+    if (!written.length) {
+      return { filename: 'export.pdf', contentType: 'application/pdf', body: new Uint8Array(0) };
+    }
+    if (written.length === 1) {
+      const bytes = new Uint8Array(readFileSync(written[0]));
+      const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+      return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+    }
+    // Multi-target → concatenate via pdf-lib `copyPages`. The vector
+    // primitives produced by Chromium copy through losslessly — we never
+    // re-render or rasterize.
+    const out = await PDFDocument.create();
+    for (const p of written) {
+      const src = await PDFDocument.load(new Uint8Array(readFileSync(p)));
+      const pages = await out.copyPages(src, src.getPageIndices());
+      for (const page of pages) out.addPage(page);
+    }
+    const bytes = await out.save();
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    return { filename: `${baseSlug}.pdf`, contentType: 'application/pdf', body: bytes };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}

package/plugins/design/dev-server/exporters/png.ts

@@ -0,0 +1,136 @@
+// Phase 6.5 T2 — PNG adapter (playwright-native).
+//
+// Drives `bin/_png-playwright.mjs` — Chromium-via-Playwright with explicit
+// viewport sizing per target. The previous `screenshot.sh` path used
+// agent-browser which applied its own viewport defaults and produced clipped
+// captures of the world-plane background instead of the artboard. With our
+// own shim we control the viewport, scroll the artboard to (0,0), then
+// `page.screenshot({ clip })`.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import JSZip from 'jszip';
+
+import {
+  type ExportContext,
+  type ExportOptions,
+  type ExportResult,
+  canvasShellUrl,
+} from './index.ts';
+import type { Target } from './scope.ts';
+
+const PNG_PLAYWRIGHT = path.join(import.meta.dir, '..', 'bin', '_png-playwright.mjs');
+
+interface CaptureOptions {
+  scale?: 1 | 2 | 3;
+  timeoutSec?: number;
+}
+
+async function captureElement(
+  target: Extract<Target, { kind: 'element' }>,
+  ctx: ExportContext,
+  outDir: string,
+  options: CaptureOptions
+): Promise<string[]> {
+  const args = [
+    PNG_PLAYWRIGHT,
+    '--url',
+    canvasShellUrl(ctx, target.file),
+    '--selector',
+    target.cssPath,
+    '--scale',
+    String(options.scale ?? 1),
+    '--timeout',
+    String(options.timeoutSec ?? 12),
+  ];
+  if (target.multi) {
+    args.push('--multi', '1', '--out-dir', outDir);
+  } else {
+    args.push('--widen-to-artboard', '1', '--out', path.join(outDir, `${target.canvasSlug}.png`));
+  }
+  const proc = Bun.spawn(['node', ...args], {
+    cwd: path.dirname(PNG_PLAYWRIGHT),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`_png-playwright exited ${code}: ${stderr.trim() || stdout.trim()}`);
+  }
+  return stdout
+    .split('\n')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function readBytes(paths: string[]): Array<{ name: string; bytes: Uint8Array }> {
+  return paths.map((p) => ({
+    name: path.basename(p),
+    bytes: new Uint8Array(readFileSync(p)),
+  }));
+}
+
+async function bundleZip(entries: Array<{ name: string; bytes: Uint8Array }>): Promise<Uint8Array> {
+  const zip = new JSZip();
+  for (const e of entries) {
+    zip.file(e.name, e.bytes);
+  }
+  return zip.generateAsync({ type: 'uint8array', compression: 'DEFLATE' });
+}
+
+export async function run(
+  targets: Target[],
+  options: ExportOptions,
+  ctx: ExportContext
+): Promise<ExportResult> {
+  if (!targets.length) {
+    return { filename: 'export.png', contentType: 'image/png', body: new Uint8Array(0) };
+  }
+  const elementTargets = targets.filter(
+    (t): t is Extract<Target, { kind: 'element' }> => t.kind === 'element'
+  );
+  if (!elementTargets.length) {
+    throw new Error('png adapter requires element targets (got file-tree)');
+  }
+
+  const tmp = mkdtempSync(path.join(tmpdir(), 'maude-png-'));
+  const captureOpts: CaptureOptions = {
+    scale: (options.scale as 1 | 2 | 3 | undefined) ?? 1,
+    timeoutSec: (options.timeoutSec as number | undefined) ?? 8,
+  };
+
+  try {
+    const written: string[] = [];
+    for (const t of elementTargets) {
+      const paths = await captureElement(t, ctx, tmp, captureOpts);
+      written.push(...paths);
+    }
+    const entries = readBytes(written);
+
+    if (entries.length === 0) {
+      return { filename: 'export.png', contentType: 'image/png', body: new Uint8Array(0) };
+    }
+    if (entries.length === 1) {
+      return {
+        filename: entries[0].name,
+        contentType: 'image/png',
+        body: entries[0].bytes,
+      };
+    }
+    const zipBytes = await bundleZip(entries);
+    const baseSlug = elementTargets[0]?.canvasSlug ?? 'export';
+    return {
+      filename: `${baseSlug}.zip`,
+      contentType: 'application/zip',
+      body: zipBytes,
+    };
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}