@typecad/cuttlefish 0.1.0-alpha.1

package/dist/preview/client.js

@@ -0,0 +1,137 @@
+// PreviewUIRuntime is loaded dynamically (see the import in the snapshot
+// handler). Typed as any to avoid a static dependency on @typecad/ui.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let runtime;
+let imageData;
+let pendingPointerMove;
+let pendingPointerFrame = 0;
+function byId(id) {
+    const el = document.getElementById(id);
+    if (!el)
+        throw new Error(`Missing preview element #${id}`);
+    return el;
+}
+function renderDiagnostics(snapshot, extra = []) {
+    const diagnostics = byId("diagnostics");
+    const messages = [
+        ...snapshot.diagnostics.map((d) => `${d.severity}: ${d.message}`),
+        ...extra,
+    ];
+    diagnostics.replaceChildren(...messages.map((message) => {
+        const div = document.createElement("div");
+        div.textContent = message;
+        return div;
+    }));
+}
+function canvasPoint(canvas, event, width, height) {
+    const rect = canvas.getBoundingClientRect();
+    return {
+        x: Math.floor(((event.clientX - rect.left) / rect.width) * width),
+        y: Math.floor(((event.clientY - rect.top) / rect.height) * height),
+    };
+}
+function renderPinControls(controls) {
+    const panel = byId("pins");
+    panel.replaceChildren();
+    if (controls.length === 0) {
+        const empty = document.createElement("div");
+        empty.className = "empty";
+        empty.textContent = "No GPIO controls";
+        panel.append(empty);
+        return;
+    }
+    for (const control of controls) {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.textContent = control.label;
+        button.addEventListener("click", () => runtime?.triggerPin(control));
+        panel.append(button);
+    }
+}
+function flushPointerMove() {
+    pendingPointerFrame = 0;
+    if (!runtime || !pendingPointerMove)
+        return;
+    const point = pendingPointerMove;
+    pendingPointerMove = undefined;
+    runtime.pointerMove(point.x, point.y);
+}
+async function loadSnapshot() {
+    const res = await fetch("/snapshot.json", { cache: "no-store" });
+    if (!res.ok)
+        throw new Error(await res.text());
+    return await res.json();
+}
+async function start() {
+    const snapshot = await loadSnapshot();
+    runtime?.stop();
+    runtime = undefined;
+    const canvas = byId("display");
+    canvas.width = snapshot.program.width;
+    canvas.height = snapshot.program.height;
+    imageData = new ImageData(snapshot.program.width, snapshot.program.height);
+    const ctx = canvas.getContext("2d");
+    if (!ctx)
+        throw new Error("2D canvas context unavailable");
+    ctx.imageSmoothingEnabled = false;
+    // Set the canvas CSS aspect-ratio to match the display (e.g. 128:64 for
+    // OLED, 320:240 for TFT) so the browser scales it proportionally.
+    document.documentElement.style.setProperty("--display-aspect", `${snapshot.program.width} / ${snapshot.program.height}`);
+    const status = byId("status");
+    status.textContent = `${snapshot.profileName ?? snapshot.program.display?.driver ?? "display"} ${snapshot.program.width}x${snapshot.program.height} ${snapshot.program.colorFormat}`;
+    const extraDiagnostics = [];
+    // Routed through a variable (not a string literal) so tsc types this as
+    // `any` and never resolves @typecad/ui's declaration files — see the
+    // comment in ui/ui-bridge.ts for why a literal specifier here causes
+    // TS5055 on rebuilds where dist/ already exists.
+    const hostRuntimePath = "@typecad/ui/preview/host-ui-runtime";
+    const { PreviewUIRuntime } = await import(hostRuntimePath);
+    runtime = new PreviewUIRuntime(snapshot, {
+        onFrame: (rgba) => {
+            if (!imageData)
+                return;
+            imageData.data.set(rgba);
+            ctx.putImageData(imageData, 0, 0);
+        },
+        onDiagnostics: (message) => {
+            extraDiagnostics.push(message);
+            renderDiagnostics(snapshot, extraDiagnostics);
+        },
+    });
+    canvas.onpointerdown = (event) => {
+        if (!runtime)
+            return;
+        canvas.setPointerCapture(event.pointerId);
+        const p = canvasPoint(canvas, event, snapshot.program.width, snapshot.program.height);
+        runtime.pointerDown(p.x, p.y);
+    };
+    canvas.onpointermove = (event) => {
+        if (!runtime)
+            return;
+        pendingPointerMove = canvasPoint(canvas, event, snapshot.program.width, snapshot.program.height);
+        if (!pendingPointerFrame)
+            pendingPointerFrame = requestAnimationFrame(flushPointerMove);
+    };
+    const pointerUp = () => {
+        if (pendingPointerFrame) {
+            cancelAnimationFrame(pendingPointerFrame);
+            flushPointerMove();
+        }
+        runtime?.pointerUp();
+    };
+    canvas.onpointerup = pointerUp;
+    canvas.onpointercancel = pointerUp;
+    renderPinControls(snapshot.pinControls);
+    renderDiagnostics(snapshot);
+    runtime.start();
+}
+void start().catch((error) => {
+    byId("diagnostics").textContent = error instanceof Error ? error.message : String(error);
+});
+const events = new EventSource("/events");
+events.addEventListener("reload", () => {
+    void start().catch((error) => {
+        byId("diagnostics").textContent = error instanceof Error ? error.message : String(error);
+    });
+});
+export {};

package/dist/preview/server.d.ts

@@ -0,0 +1,5 @@
+export interface PreviewServerOptions {
+    configPath?: string;
+    port?: number;
+}
+export declare function runPreviewServer(options?: PreviewServerOptions): Promise<void>;

package/dist/preview/server.js

@@ -0,0 +1,199 @@
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import chalk from "chalk";
+import { findConfigFile, parseConfigFile } from "../config-loader.js";
+import { requireUIHook } from "../ui-hook.js";
+const HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Cuttlefish Preview</title>
+  <style>
+    :root { color-scheme: dark; font-family: ui-sans-serif, system-ui, sans-serif; background: #111315; color: #e8ecef; }
+    body { margin: 0; height: 100vh; overflow: hidden; display: grid; grid-template-columns: minmax(360px, 1fr) 280px; }
+    main { display: grid; place-items: center; padding: 24px; background: #191d20; }
+    canvas { image-rendering: pixelated; width: min(92vw, 960px); max-height: calc(100vh - 48px); aspect-ratio: var(--display-aspect, 4 / 3); background: #000; box-shadow: 0 12px 36px rgba(0,0,0,.35); }
+    aside { border-left: 1px solid #2d3338; padding: 18px; display: flex; flex-direction: column; gap: 18px; min-height: 0; }
+    aside > section:first-child, aside > section:nth-child(2) { flex-shrink: 0; }  /* Display + GPIO stay visible */
+    aside > section:last-child { min-height: 0; display: flex; flex-direction: column; }
+    #diagnostics { overflow-y: auto; min-height: 0; }
+    h1 { font-size: 15px; margin: 0 0 8px; font-weight: 650; }
+    #status, #diagnostics, .empty { color: #aab3ba; font-size: 12px; line-height: 1.4; }
+    #pins { display: grid; gap: 8px; }
+    button { appearance: none; border: 1px solid #44505a; background: #252b30; color: #f3f6f8; border-radius: 6px; padding: 9px 10px; text-align: left; font: inherit; cursor: pointer; }
+    button:hover { background: #303841; }
+    @media (max-width: 760px) {
+      body { height: auto; min-height: 100vh; overflow: auto; grid-template-rows: auto 1fr; grid-template-columns: 1fr; }
+      aside { border-left: 0; border-top: 1px solid #2d3338; }
+      canvas { width: min(94vw, 640px); }
+    }
+  </style>
+</head>
+<body>
+  <main><canvas id="display" width="320" height="240"></canvas></main>
+  <aside>
+    <section>
+      <h1>Display</h1>
+      <div id="status"></div>
+    </section>
+    <section>
+      <h1>GPIO</h1>
+      <div id="pins"></div>
+    </section>
+    <section>
+      <h1>Diagnostics</h1>
+      <div id="diagnostics"></div>
+    </section>
+  </aside>
+  <script type="module" src="/__cuttlefish/preview/client.js"></script>
+</body>
+</html>`;
+function contentType(filePath) {
+    if (filePath.endsWith(".js"))
+        return "text/javascript; charset=utf-8";
+    if (filePath.endsWith(".json"))
+        return "application/json; charset=utf-8";
+    if (filePath.endsWith(".map"))
+        return "application/json; charset=utf-8";
+    return "text/plain; charset=utf-8";
+}
+function writeText(res, status, text, type = "text/plain; charset=utf-8") {
+    res.writeHead(status, { "content-type": type });
+    res.end(text);
+}
+function resolveConfigPath(configPath) {
+    if (configPath) {
+        const abs = path.resolve(process.cwd(), configPath);
+        if (!fs.existsSync(abs))
+            throw new Error(`Config file not found: ${abs}`);
+        return abs;
+    }
+    const found = findConfigFile(process.cwd());
+    if (!found)
+        throw new Error("No cuttlefish.config.ts found for preview.");
+    return found;
+}
+function watchPreviewFiles(projectRoot, configPath, notify) {
+    const watchers = [];
+    let timer;
+    const debounced = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(notify, 80);
+    };
+    const addWatch = (target, recursive = false) => {
+        if (!fs.existsSync(target))
+            return;
+        try {
+            watchers.push(fs.watch(target, { recursive }, (_event, filename) => {
+                const name = String(filename ?? "");
+                if (!name || /\.(ts|css|html)$/.test(name) || name === path.basename(configPath))
+                    debounced();
+            }));
+        }
+        catch {
+            if (recursive)
+                addWatch(target, false);
+        }
+    };
+    addWatch(path.join(projectRoot, "src"), true);
+    addWatch(configPath);
+    return watchers;
+}
+async function listen(server, preferredPort) {
+    for (let port = preferredPort; port < preferredPort + 20; port++) {
+        const result = await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                server.off("listening", onListening);
+                if (error.code === "EADDRINUSE")
+                    resolve("busy");
+                else
+                    reject(error);
+            };
+            const onListening = () => {
+                server.off("error", onError);
+                resolve("ok");
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen(port, "127.0.0.1");
+        });
+        if (result === "ok")
+            return port;
+    }
+    throw new Error(`No available preview port found starting at ${preferredPort}.`);
+}
+export async function runPreviewServer(options = {}) {
+    const configPath = resolveConfigPath(options.configPath);
+    const config = parseConfigFile(configPath);
+    if (!config)
+        throw new Error(`Could not parse ${configPath}`);
+    const projectRoot = path.dirname(configPath);
+    requireUIHook().generateProjectUITypeDeclarations(projectRoot);
+    const distRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const clients = new Set();
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        try {
+            if (url.pathname === "/") {
+                writeText(res, 200, HTML, "text/html; charset=utf-8");
+                return;
+            }
+            if (url.pathname === "/snapshot.json") {
+                requireUIHook().generateProjectUITypeDeclarations(projectRoot);
+                // Routed through a variable (not a string literal) so tsc types this
+                // as `any` and never resolves @typecad/ui's declaration files — see
+                // the comment in ui/ui-bridge.ts for why a literal specifier here
+                // causes TS5055 on rebuilds where dist/ already exists.
+                const buildProgramPath = "@typecad/ui/preview/build-program";
+                const { buildPreviewSnapshot } = await import(buildProgramPath);
+                const snapshot = await buildPreviewSnapshot({ config, projectRoot });
+                writeText(res, 200, JSON.stringify(snapshot), "application/json; charset=utf-8");
+                return;
+            }
+            if (url.pathname === "/events") {
+                res.writeHead(200, {
+                    "content-type": "text/event-stream",
+                    "cache-control": "no-cache",
+                    "connection": "keep-alive",
+                });
+                res.write("\n");
+                clients.add(res);
+                req.on("close", () => clients.delete(res));
+                return;
+            }
+            if (url.pathname.startsWith("/__cuttlefish/")) {
+                const rel = decodeURIComponent(url.pathname.slice("/__cuttlefish/".length));
+                const filePath = path.resolve(distRoot, rel);
+                if (!filePath.startsWith(distRoot) || !fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+                    writeText(res, 404, "Not found");
+                    return;
+                }
+                res.writeHead(200, { "content-type": contentType(filePath) });
+                fs.createReadStream(filePath).pipe(res);
+                return;
+            }
+            writeText(res, 404, "Not found");
+        }
+        catch (error) {
+            writeText(res, 500, error instanceof Error ? error.message : String(error));
+        }
+    });
+    const notify = () => {
+        for (const client of clients) {
+            client.write("event: reload\n");
+            client.write(`data: ${Date.now()}\n\n`);
+        }
+    };
+    const watchers = watchPreviewFiles(projectRoot, configPath, notify);
+    server.on("close", () => watchers.forEach((watcher) => watcher.close()));
+    const port = await listen(server, options.port ?? 5174);
+    console.log(chalk.cyan("Cuttlefish preview") + chalk.gray(` ${path.relative(process.cwd(), configPath)}`));
+    console.log(`  http://127.0.0.1:${port}/`);
+    await new Promise((resolve) => {
+        server.on("close", resolve);
+    });
+}

package/dist/profiler/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Performance profiler for transpilation.
+ *
+ * @example
+ * ```typescript
+ * import { initProfiler, formatConsoleReport } from './profiler.js';
+ *
+ * const profiler = initProfiler({ enabled: true });
+ * profiler.startSession();
+ *
+ * // Time synchronous operations
+ * profiler.timeSync('phase:name', () => {
+ *   // do work
+ * });
+ *
+ * // Time async operations
+ * await profiler.timeAsync('phase:async', async () => {
+ *   // do async work
+ * });
+ *
+ * // Generate report
+ * const session = profiler.endSession();
+ * const report = profiler.generateReport(session);
+ * console.log(formatConsoleReport(report));
+ * ```
+ */
+export { Profiler, getProfiler, initProfiler } from "./profiler.js";
+export { TimingEntry, MemorySnapshot, PhaseStatistics, ProfilerSession, ProfilerOptions, ProfilerReport, DEFAULT_PROFILER_OPTIONS, } from "./types.js";

package/dist/profiler/index.js

@@ -0,0 +1,28 @@
+/**
+ * Performance profiler for transpilation.
+ *
+ * @example
+ * ```typescript
+ * import { initProfiler, formatConsoleReport } from './profiler.js';
+ *
+ * const profiler = initProfiler({ enabled: true });
+ * profiler.startSession();
+ *
+ * // Time synchronous operations
+ * profiler.timeSync('phase:name', () => {
+ *   // do work
+ * });
+ *
+ * // Time async operations
+ * await profiler.timeAsync('phase:async', async () => {
+ *   // do async work
+ * });
+ *
+ * // Generate report
+ * const session = profiler.endSession();
+ * const report = profiler.generateReport(session);
+ * console.log(formatConsoleReport(report));
+ * ```
+ */
+export { Profiler, getProfiler, initProfiler } from "./profiler.js";
+export { DEFAULT_PROFILER_OPTIONS, } from "./types.js";

package/dist/profiler/profiler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Performance profiler for the transpilation pipeline.
+ *
+ * Usage:
+ *   const profiler = initProfiler({ enabled: true });
+ *   profiler.startSession();
+ *   profiler.timeSync('phase:name', () => { ... });
+ *   await profiler.timeAsync('phase:async', async () => { ... });
+ *   const report = profiler.endSession();
+ */
+import { ProfilerOptions, ProfilerSession, ProfilerReport } from "./types.js";
+export declare class Profiler {
+    private enabled;
+    private trackMemory;
+    private threshold;
+    private timings;
+    private activeTimers;
+    private memorySnapshots;
+    private sessionStart;
+    private parentStack;
+    private timerCounter;
+    constructor(options?: Partial<ProfilerOptions>);
+    /**
+     * Check if profiling is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Start a timing measurement
+     */
+    startTimer(name: string, metadata?: Record<string, unknown>): void;
+    /**
+     * End a timing measurement
+     */
+    endTimer(name: string): number;
+    /**
+     * Time a synchronous function
+     */
+    timeSync<T>(name: string, fn: () => T, metadata?: Record<string, unknown>): T;
+    /**
+     * Time an asynchronous function
+     */
+    timeAsync<T>(name: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+    /**
+     * Capture a memory snapshot
+     */
+    captureMemorySnapshot(name: string): void;
+    /**
+     * Start a profiling session
+     */
+    startSession(): void;
+    /**
+     * End a profiling session and return the session data
+     */
+    endSession(): ProfilerSession;
+    /**
+     * Compute aggregated statistics by phase
+     */
+    private computePhaseStatistics;
+    /**
+     * Extract the base phase name from a timer name
+     */
+    private extractBasePhase;
+    /**
+     * Generate a profiler report from a session
+     */
+    generateReport(session: ProfilerSession): ProfilerReport;
+    /**
+     * Identify phases that are bottlenecks (>10% of total time)
+     */
+    private identifyBottlenecks;
+    /**
+     * Generate optimization recommendations based on profiling data
+     */
+    private generateRecommendations;
+    /**
+     * Generate a human-readable summary
+     */
+    private generateSummary;
+    /**
+     * Get all timing durations as a flat record (for diagnostics integration).
+     */
+    getTimings(): Record<string, number>;
+    /**
+     * Clear all profiling data
+     */
+    clear(): void;
+}
+/**
+ * Get the global profiler instance (creates one if not exists)
+ */
+export declare function getProfiler(): Profiler;
+/**
+ * Initialize the global profiler with options
+ */
+export declare function initProfiler(options?: Partial<ProfilerOptions>): Profiler;