@typecad/cuttlefish 0.1.0-alpha.1

package/dist/ir/transformers/callback-context-registry.d.ts

@@ -0,0 +1,20 @@
+export type CallbackContextId = "setInterval" | "ui-event-callback" | "ui-draw-canvas";
+export interface CallbackContextCapabilities {
+    id: CallbackContextId;
+    /** Human label used in diagnostic messages, e.g. "UI event callback". */
+    label: string;
+    /** Statement-level control-flow constructs this context lowers. */
+    statements: readonly string[];
+    /** Expression-level / side-effecting forms this context recognizes. */
+    expressions: readonly string[];
+    /** Actionable next step when a statement/expression isn't supported here. */
+    escapeHatch: string;
+}
+export declare const CALLBACK_CONTEXTS: Readonly<Record<CallbackContextId, CallbackContextCapabilities>>;
+/** Human-readable name for a context, used in diagnostic messages. */
+export declare function callbackContextLabel(id: CallbackContextId): string;
+/** Render a context's declared capabilities into the hint text shown
+ *  alongside a "statement not lowerable here" diagnostic, so the message
+ *  always matches what lowerCallbackStatements for that context actually
+ *  implements. */
+export declare function unsupportedStatementHint(id: CallbackContextId): string;

package/dist/ir/transformers/callback-context-registry.js

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// Declarative capability registry for UI callback contexts.
+//
+// UI callback bodies (setInterval, ui.bind/onClick/onToggle/watchPin,
+// ui.drawCanvas) each lower through lowerCallbackStatements →
+// lowerStatementList (the same pipeline setInterval uses). This registry is
+// the single declarative source of truth for diagnostics: each context lists
+// what it lowers, and unsupportedStatementHint() renders that list into the
+// hint text shown next to fatal "ui-callback-unsupported-statement"
+// diagnostics.
+// ---------------------------------------------------------------------------
+export const CALLBACK_CONTEXTS = {
+    setInterval: {
+        id: "setInterval",
+        label: "setInterval callback",
+        statements: ["const/let", "if/else", "for", "while", "do/while", "break/continue", "nested blocks"],
+        expressions: ["the full statement-to-IR expression pipeline — the same one top-level code uses"],
+        escapeHatch: "setInterval callbacks already route through the main statement-to-IR pipeline, so a failure here reflects a general transpiler limitation rather than a callback-context restriction",
+    },
+    "ui-event-callback": {
+        id: "ui-event-callback",
+        label: "UI event callback",
+        statements: ["const/let", "if/else", "for", "while", "do/while", "break/continue"],
+        expressions: [
+            "signal.set(value)",
+            "signal() reads",
+            "console.* calls",
+            "any other expression via the standard expression pipeline (arithmetic, comparisons, ternaries, color literals, ...)",
+        ],
+        escapeHatch: "move the logic to setInterval or a plain function",
+    },
+    "ui-draw-canvas": {
+        id: "ui-draw-canvas",
+        label: "ui.drawCanvas callback",
+        statements: ["const/let", "if/else", "for", "while", "do/while", "break/continue"],
+        expressions: [
+            "ctx.*() draw calls (drawPixel, fillRect, rect, fillRoundRect, roundRect, line, hline, vline, fillCircle, circle, rgbBitmap, text, fillScreen)",
+        ],
+        escapeHatch: "move non-drawing side effects (calls not on ctx, e.g. signal writes or console output) to setInterval",
+    },
+};
+/** Human-readable name for a context, used in diagnostic messages. */
+export function callbackContextLabel(id) {
+    return CALLBACK_CONTEXTS[id].label;
+}
+/** Render a context's declared capabilities into the hint text shown
+ *  alongside a "statement not lowerable here" diagnostic, so the message
+ *  always matches what lowerCallbackStatements for that context actually
+ *  implements. */
+export function unsupportedStatementHint(id) {
+    const ctx = CALLBACK_CONTEXTS[id];
+    return (`${ctx.label}s support ${ctx.statements.join(", ")} for control flow, ` +
+        `plus ${ctx.expressions.join("; ")}. If you hit this, the statement kind used ` +
+        `isn't lowerable here — ${ctx.escapeHatch}.`);
+}

package/dist/ir/transformers/canvas-lowering.d.ts

@@ -0,0 +1,42 @@
+import ts from "typescript";
+import { Diagnostic, type SourceSpan } from "../../types.js";
+import type { StatementIR } from "../../api/shared/ir-core.js";
+/** One user draw callback: the node it targets + IR body (preferred) or
+ *  lowered C++ body string (fallback / tests). */
+export interface DrawCanvasSpec {
+    nodeIndex: number;
+    fnName: string;
+    /** @deprecated Prefer bodyStatements; kept for compact-string fallbacks. */
+    callbackBody: string;
+    /** Statement IR produced by lowerCallbackStatements (main pipeline). */
+    bodyStatements?: StatementIR[];
+    /** Source span of the original (ctx) => {...} callback, when known. */
+    sourceSpan?: SourceSpan;
+}
+export declare function resetCanvasBindings(): void;
+export declare function canvasBindings(): DrawCanvasSpec[];
+export declare function recordCanvasBinding(spec: DrawCanvasSpec): void;
+export declare function getCanvasBindingsCount(): number;
+/**
+ * If `call` is a `<ctxName>.method(args)` call we recognize, return the lowered
+ * C++ statement(s) (each terminated with `;`). Otherwise return null (and push
+ * a diagnostic if it IS a ctx call with an unknown method).
+ */
+export declare function rewriteCanvasCall(call: ts.CallExpression, ctxName: string, diagnostics: Diagnostic[], sourceText?: string): string | null;
+/**
+ * Lower an entire ui.drawCanvas callback body through the main statement-to-IR
+ * pipeline (ambient canvas ctx rewrites ctx.* during lowering). Returns a
+ * compact-rendered C++ string for unit tests / callers that still want text.
+ */
+export declare function lowerCanvasBody(cbArg: ts.ArrowFunction | ts.FunctionExpression, sourceText: string, diagnostics: Diagnostic[], fileName?: string): string;
+/** Emit the canvas binding table + callback functions.
+ *
+ * When `emitStatements` is provided, bodyStatements are rendered through it
+ * (StatementRenderer path). Otherwise falls back to compact string paste of
+ * callbackBody (tests / no-emitter contexts). */
+export declare function emitCanvasBindings(specs: DrawCanvasSpec[], emitLine?: (line: string, span?: SourceSpan) => void, emitStatements?: (statements: StatementIR[], indent: string, span?: SourceSpan) => void): string;
+/**
+ * Resolve a `ui.drawCanvas(node, (ctx) => {...})` call.
+ * Records a DrawCanvasSpec with bodyStatements from the main IR pipeline.
+ */
+export declare function resolveDrawCanvasCall(call: ts.CallExpression, fileName: string, sourceText: string, diagnostics: Diagnostic[]): StatementIR | null;

package/dist/ir/transformers/canvas-lowering.js

@@ -0,0 +1,249 @@
+// ---------------------------------------------------------------------------
+// Canvas callback lowering: rewrite `ctx.method(args)` calls inside a
+// ui.drawCanvas(node, (ctx) => {...}) body into ui_display_* shim calls.
+//
+// `ctx` is a compile-time fiction — at runtime the callback draws into the
+// node's offscreen CuttlefishCanvas16 set as the active __ui_gfx target, so the
+// lowered body uses the SAME ui_display_* wrappers every other draw path uses.
+// Colors resolve to RGB565 via the existing resolver; ctx.width/ctx.height map
+// to __ui_canvas_w / __ui_canvas_h locals set by the emitted wrapper.
+//
+// Block-body callbacks lower through lowerCallbackStatements (main
+// statement-to-IR pipeline, same as setInterval / onClick), with an ambient
+// canvas ctx so callToStatement / expressionToIR rewrite ctx.* forms. The
+// resulting StatementIR[] is stored on DrawCanvasSpec and rendered at emit.
+// ---------------------------------------------------------------------------
+import ts from "typescript";
+import { expressionToIR } from "../expression-to-ir.js";
+import { renderExprAsText } from "../render-expr.js";
+import { requireUIHook } from "../../ui-hook.js";
+import { getDisplayProfile } from "../../stores/display-profile-store.js";
+import { resolveColorIR, lowerCallbackStatements, renderStatementsCompact, } from "./ui-callback-lowering.js";
+import { makeSourceSpan } from "../ast-node-utils.js";
+import { resolveNodeIndex, resolveUIModuleImport, pushUnknownElementDiagnostic } from "./ui-call-resolver.js";
+const _canvasBindings = [];
+export function resetCanvasBindings() {
+    _canvasBindings.length = 0;
+}
+export function canvasBindings() {
+    return _canvasBindings;
+}
+export function recordCanvasBinding(spec) {
+    _canvasBindings.push(spec);
+}
+export function getCanvasBindingsCount() {
+    return _canvasBindings.length;
+}
+/** True if `text` is a quoted CSS color string. */
+function isColorLiteral(text) {
+    const t = text.trim();
+    return /^["'](#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})|[a-z]+|rgba?\([^)]*\))["']$/i.test(t);
+}
+/** Lower a CSS color string to the target's internal color literal, or null if not a color. */
+function tryColor(text) {
+    if (!isColorLiteral(text))
+        return null;
+    const color = text.trim().replace(/^["']|["']$/g, "");
+    try {
+        return requireUIHook().resolveColorInternal(color, getDisplayProfile().colorFormat);
+    }
+    catch {
+        return null;
+    }
+}
+/** Substitute ctx.width/ctx.height references (bare or embedded in a
+ *  compound expression, e.g. `ctx.height - 4`) with the wrapper's locals. */
+function substituteCanvasDims(raw, ctxName) {
+    return raw
+        .replace(new RegExp(`\\b${ctxName}\\.width\\b`, "g"), "__ui_canvas_w")
+        .replace(new RegExp(`\\b${ctxName}\\.height\\b`, "g"), "__ui_canvas_h");
+}
+/** Lower one argument expression to its C++ text. Color strings → rgb565 hex. */
+function lowerArg(arg, ctxName, sourceText, diagnostics) {
+    if (ts.isPropertyAccessExpression(arg) &&
+        ts.isIdentifier(arg.expression) &&
+        arg.expression.text === ctxName &&
+        (arg.name.text === "width" || arg.name.text === "height")) {
+        return arg.name.text === "width" ? "__ui_canvas_w" : "__ui_canvas_h";
+    }
+    let raw = renderExprAsText(expressionToIR(arg, sourceText, diagnostics));
+    raw = substituteCanvasDims(raw, ctxName);
+    const color = tryColor(raw);
+    if (color !== null)
+        raw = `0x${color.toString(16)}`;
+    return raw;
+}
+/** Lower an argument known (by its position) to be a color. Resolves color
+ *  string literals at the IR level (via resolveColorIR) BEFORE rendering, so
+ *  ternaries like `temp() > 25 ? '#a33' : '#33a'` resolve both branches. */
+function lowerColorArg(arg, ctxName, sourceText, diagnostics) {
+    const ir = resolveColorIR(expressionToIR(arg, sourceText, diagnostics));
+    return substituteCanvasDims(renderExprAsText(ir), ctxName);
+}
+/** ctx method name → shim callee. */
+const CANVAS_METHODS = {
+    drawPixel: "ui_display_draw_pixel",
+    fillRect: "ui_display_fill_rect",
+    rect: "ui_display_draw_rect",
+    fillRoundRect: "ui_display_fill_round_rect",
+    roundRect: "ui_display_draw_round_rect",
+    line: "ui_display_draw_line",
+    hline: "ui_display_draw_fast_hline",
+    vline: "ui_display_draw_fast_vline",
+    fillCircle: "ui_display_fill_circle",
+    circle: "ui_display_draw_circle",
+    rgbBitmap: "ui_display_draw_rgb_bitmap",
+};
+/** Argument index (0-based) of the color parameter for each ctx method. */
+const COLOR_ARG_INDEX = {
+    drawPixel: 2,
+    fillRect: 4,
+    rect: 4,
+    fillRoundRect: 5,
+    roundRect: 5,
+    line: 4,
+    hline: 3,
+    vline: 3,
+    fillCircle: 3,
+    circle: 3,
+};
+/**
+ * If `call` is a `<ctxName>.method(args)` call we recognize, return the lowered
+ * C++ statement(s) (each terminated with `;`). Otherwise return null (and push
+ * a diagnostic if it IS a ctx call with an unknown method).
+ */
+export function rewriteCanvasCall(call, ctxName, diagnostics, sourceText = "") {
+    if (!ts.isPropertyAccessExpression(call.expression) ||
+        !ts.isIdentifier(call.expression.expression) ||
+        call.expression.expression.text !== ctxName) {
+        return null;
+    }
+    const method = call.expression.name.text;
+    const args = call.arguments;
+    if (method === "text") {
+        if (args.length < 3) {
+            diagnostics.push({
+                severity: "error", code: "ui-canvas-method",
+                message: `ctx.text() requires at least 3 arguments (x, y, text); got ${args.length}.`,
+                source: sourceText.slice(Math.max(0, call.getStart() - 20), call.getEnd()).trim(),
+            });
+            return null;
+        }
+        const x = lowerArg(args[0], ctxName, sourceText, diagnostics);
+        const y = lowerArg(args[1], ctxName, sourceText, diagnostics);
+        const str = renderExprAsText(expressionToIR(args[2], sourceText, diagnostics));
+        const colorText = args.length >= 4 ? lowerColorArg(args[3], ctxName, sourceText, diagnostics) : "0xffff";
+        return `ui_display_set_cursor(${x}, ${y}); ui_display_set_text_color_solid(${colorText}); ui_display_print(${str});`;
+    }
+    if (method === "fillScreen") {
+        if (args.length < 1) {
+            diagnostics.push({
+                severity: "error", code: "ui-canvas-method",
+                message: `ctx.fillScreen() requires a color argument.`,
+                source: sourceText.slice(Math.max(0, call.getStart() - 20), call.getEnd()).trim(),
+            });
+            return null;
+        }
+        const colorText = lowerColorArg(args[0], ctxName, sourceText, diagnostics);
+        return `ui_display_fill_rect(0, 0, __ui_canvas_w, __ui_canvas_h, ${colorText});`;
+    }
+    const shim = CANVAS_METHODS[method];
+    if (!shim) {
+        diagnostics.push({
+            severity: "error", code: "ui-canvas-method",
+            message: `Unknown canvas method ctx.${method}() — supported: drawPixel, fillRect, rect, fillRoundRect, roundRect, line, hline, vline, fillCircle, circle, rgbBitmap, text, fillScreen`,
+            source: sourceText.slice(Math.max(0, call.getStart() - 20), call.getEnd()).trim(),
+        });
+        return null;
+    }
+    const colorIdx = COLOR_ARG_INDEX[method];
+    const loweredArgs = args
+        .map((a, i) => (i === colorIdx ? lowerColorArg(a, ctxName, sourceText, diagnostics) : lowerArg(a, ctxName, sourceText, diagnostics)))
+        .join(", ");
+    return `${shim}(${loweredArgs});`;
+}
+/**
+ * Lower an entire ui.drawCanvas callback body through the main statement-to-IR
+ * pipeline (ambient canvas ctx rewrites ctx.* during lowering). Returns a
+ * compact-rendered C++ string for unit tests / callers that still want text.
+ */
+export function lowerCanvasBody(cbArg, sourceText, diagnostics, fileName = "canvas.ts") {
+    const statements = lowerCallbackStatements(cbArg, fileName, sourceText, diagnostics, "ui-draw-canvas");
+    return renderStatementsCompact(statements);
+}
+/** Emit the canvas binding table + callback functions.
+ *
+ * When `emitStatements` is provided, bodyStatements are rendered through it
+ * (StatementRenderer path). Otherwise falls back to compact string paste of
+ * callbackBody (tests / no-emitter contexts). */
+export function emitCanvasBindings(specs, emitLine, emitStatements) {
+    const lines = [];
+    const push = (line, span) => {
+        lines.push(line);
+        emitLine?.(line, span);
+    };
+    if (specs.length === 0) {
+        push(`UICanvasBinding __ui_canvas_bindings[] = {};`);
+        push(`const uint16_t __ui_canvas_binding_count = 0;`);
+        return lines.join("\n");
+    }
+    for (const spec of specs) {
+        push(`void ${spec.fnName}(CuttlefishCanvas16* __c) {`, spec.sourceSpan);
+        push(`  int16_t __ui_canvas_w = __c ? display_canvasWidth(__c) : __ui_canvas_fallback_w;`);
+        push(`  int16_t __ui_canvas_h = __c ? display_canvasHeight(__c) : __ui_canvas_fallback_h;`);
+        if (spec.bodyStatements && emitStatements) {
+            emitStatements(spec.bodyStatements, "  ", spec.sourceSpan);
+        }
+        else if (spec.bodyStatements) {
+            push(`  ${renderStatementsCompact(spec.bodyStatements)}`, spec.sourceSpan);
+        }
+        else {
+            push(`  ${spec.callbackBody || ""}`, spec.sourceSpan);
+        }
+        push(`}`);
+    }
+    push(`UICanvasBinding __ui_canvas_bindings[] = {`);
+    for (const spec of specs) {
+        push(`  { .node=${spec.nodeIndex}, .fn=${spec.fnName} },`);
+    }
+    push(`};`);
+    push(`const uint16_t __ui_canvas_binding_count = ${specs.length};`);
+    return lines.join("\n");
+}
+/**
+ * Resolve a `ui.drawCanvas(node, (ctx) => {...})` call.
+ * Records a DrawCanvasSpec with bodyStatements from the main IR pipeline.
+ */
+export function resolveDrawCanvasCall(call, fileName, sourceText, diagnostics) {
+    const nodeArg = call.arguments[0];
+    const cbArg = call.arguments[1];
+    if (!nodeArg || !ts.isPropertyAccessExpression(nodeArg) || !ts.isIdentifier(nodeArg.expression))
+        return null;
+    if (!cbArg || !(ts.isArrowFunction(cbArg) || ts.isFunctionExpression(cbArg)))
+        return null;
+    const treeName = nodeArg.expression.text;
+    const id = nodeArg.name.text;
+    const htmlPath = resolveUIModuleImport(treeName);
+    if (!htmlPath)
+        return null;
+    const nodeIndex = resolveNodeIndex(htmlPath, id);
+    if (nodeIndex < 0) {
+        pushUnknownElementDiagnostic(diagnostics, "ui.drawCanvas", id, treeName);
+        return null;
+    }
+    const bodyStatements = lowerCallbackStatements(cbArg, fileName, sourceText, diagnostics, "ui-draw-canvas");
+    const fnName = `__ui_canvas_draw_${getCanvasBindingsCount()}`;
+    recordCanvasBinding({
+        nodeIndex,
+        fnName,
+        // Legacy compact string for tests / emitCanvasBindings without emitStatements.
+        callbackBody: renderStatementsCompact(bodyStatements),
+        bodyStatements,
+        sourceSpan: makeSourceSpan(cbArg, fileName, sourceText),
+    });
+    return {
+        kind: "block",
+        sourceSpan: makeSourceSpan(call, fileName, sourceText),
+        body: [],
+    };
+}

package/dist/ir/transformers/control-flow.d.ts

@@ -0,0 +1,8 @@
+import ts from "typescript";
+import { Diagnostic } from "../../types.js";
+import { StatementIR } from "../../api/index.js";
+import { CppTypeHint } from "../type-resolution.js";
+import { PointerTracker } from "../build-ir-state.js";
+export declare function forInitializerToIR(declarationList: ts.VariableDeclarationList, fileName: string, sourceText: string, diagnostics: Diagnostic[], functionReturnTypes: Map<string, CppTypeHint>, localVariableTypes: Map<string, CppTypeHint>): StatementIR | undefined;
+export declare function incrementorToIR(expr: ts.Expression, sourceText: string, diagnostics: Diagnostic[], localVariableTypes: Map<string, CppTypeHint>): StatementIR | undefined;
+export declare function lowerControlFlowStatement(statement: ts.Statement, fileName: string, sourceText: string, diagnostics: Diagnostic[], functionReturnTypes: Map<string, CppTypeHint>, localVariableTypes: Map<string, CppTypeHint>, functionNameForDiagnostics: string, typeAliases?: Map<string, ts.TypeNode>, pointerVars?: PointerTracker): StatementIR[] | null;