@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/display-profile.js

@@ -0,0 +1,338 @@
+// ---------------------------------------------------------------------------
+// DisplayProfile — declarative description of a display's capabilities.
+//
+// Lives in the project config (cuttlefish.config.ts) or in built-in framework
+// profiles. Describes everything the transpiler needs to know about the
+// display hardware: dimensions, color depth, rotation, pins, touch.
+//
+// Adding a new display = adding a profile. No framework code changes.
+export function normalizeDisplayRotation(rotation) {
+    const r = ((rotation ?? 0) % 4 + 4) % 4;
+    return r;
+}
+/** Return the screen-space dimensions after the display rotation is applied. */
+export function effectiveDisplaySize(display) {
+    if (display.nativeWidth === undefined || display.nativeHeight === undefined) {
+        return { width: display.width, height: display.height };
+    }
+    const rotation = normalizeDisplayRotation(display.rotation);
+    return rotation === 1 || rotation === 3
+        ? { width: display.nativeHeight, height: display.nativeWidth }
+        : { width: display.nativeWidth, height: display.nativeHeight };
+}
+/** Touch libraries treated as resistive (noisy, low-sample-rate) panels. */
+const RESISTIVE_TOUCH_LIBS = new Set([
+    "XPT2046_Touchscreen",
+    "Adafruit_TouchScreen",
+]);
+/** Default RGB565 scroll viewport canvas budget (~88 KB, ESP32-class SRAM). */
+export const DEFAULT_SCROLL_CANVAS_BUDGET_BYTES = 88000;
+/** PSRAM scroll canvas budget (~2 MB). ESP32-S3 with OPI/QSPI PSRAM exposes
+ *  ~8 MB external RAM; a full-width scroll viewport canvas (e.g. 460×266×2 ≈
+ *  239 KB) is trivial there, so the transpile-time scroll-canvas-memory
+ *  diagnostic should use a PSRAM-appropriate budget rather than the no-PSRAM
+ *  SRAM default — otherwise every PSRAM target emits stale "exceeds budget"
+ *  warnings for canvases the runtime allocates without issue. */
+export const PSRAM_SCROLL_CANVAS_BUDGET_BYTES = 2_000_000;
+/** Detect PSRAM from an Arduino FQBN buildTarget (e.g. "esp32:esp32:esp32s3:PSRAM=opi").
+ *  Returns true for any PSRAM=<value> option whose value indicates PSRAM is
+ *  enabled (opi, io, qspi, enabled, true). Returns false when absent or set
+ *  to a disabled-looking value (disabled, false, none). */
+export function buildTargetHasPsram(buildTarget) {
+    if (!buildTarget)
+        return false;
+    const opts = buildTarget.split(":");
+    for (const opt of opts) {
+        const eq = opt.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = opt.slice(0, eq).trim().toLowerCase();
+        const val = opt.slice(eq + 1).trim().toLowerCase();
+        if (key !== "psram")
+            continue;
+        // Any explicit PSRAM option except an explicit disabled value means PSRAM.
+        return !["disabled", "false", "none", "no", "0"].includes(val);
+    }
+    return false;
+}
+/**
+ * Resolve scroll config from a display profile. Declared overrides win;
+ * otherwise derive the input tier from the touch library (resistive chips →
+ * "resistive", any other touch → "capacitive", no touch → "none") and assume a
+ * full render tier (ESP32-class SRAM can fit a viewport canvas).
+ */
+export function resolveScrollConfig(display, ctx) {
+    const s = display.scroll ?? {};
+    const lib = display.touch && typeof display.touch === "object"
+        ? display.touch.library
+        : undefined;
+    const derivedInput = lib && RESISTIVE_TOUCH_LIBS.has(lib)
+        ? "resistive"
+        : display.touch
+            ? "capacitive"
+            : "none";
+    // PSRAM-aware canvas budget: an explicit override always wins; otherwise use
+    // the PSRAM budget when the build target opts into PSRAM (so the scroll-canvas-
+    // memory diagnostic doesn't emit stale warnings for canvases the runtime
+    // allocates in external RAM without issue), else the no-PSRAM SRAM default.
+    const psramBudget = buildTargetHasPsram(ctx?.buildTarget);
+    const budgetDefault = psramBudget
+        ? PSRAM_SCROLL_CANVAS_BUDGET_BYTES
+        : DEFAULT_SCROLL_CANVAS_BUDGET_BYTES;
+    return {
+        inputTier: s.inputTier ?? derivedInput,
+        renderTier: s.renderTier ?? "full",
+        dragScale: s.dragScale ?? 1,
+        maxOverscroll: s.maxOverscroll ?? 40,
+        stiffness: s.stiffness ?? 0.5,
+        edgeSnapPx: s.edgeSnapPx ?? 12,
+        inputSmoothing: s.inputSmoothing ?? 0.3,
+        overrideProbes: s.overrideProbes ?? true,
+        debug: s.debug ?? false,
+        scrollCanvasBudgetBytes: s.scrollCanvasBudgetBytes ?? budgetDefault,
+    };
+}
+export function resolveDisplayProfile(config, registry) {
+    let base;
+    if (config.profile) {
+        const found = registry.get(config.profile);
+        if (!found) {
+            throw new Error(`Unknown display profile "${config.profile}". Available: ${[...registry.keys()].join(", ") || "(none)"}`);
+        }
+        base = { ...found };
+    }
+    else {
+        base = {
+            driver: config.driver ?? "ili9341",
+            width: config.width ?? 320,
+            height: config.height ?? 240,
+            nativeWidth: config.nativeWidth,
+            nativeHeight: config.nativeHeight,
+            // The SDL adapter renders to a 32-bit desktop framebuffer and is
+            // RGB888-only (uint32_t throughout). The generic default is rgb565
+            // (byte-identical to bare TFT hardware), but a desktop window has no
+            // 565 surface — default SDL to rgb888 so UI_COLOR_T matches the adapter
+            // and colors reach the window at full 24-bit precision.
+            colorFormat: config.colorFormat ?? (config.driver === "sdl" ? "rgb888" : "rgb565"),
+            rotation: config.rotation ?? 1,
+            backlight: config.backlight,
+            spiFrequency: config.spiFrequency,
+            spiPins: config.spiPins,
+            colorOrder: config.colorOrder,
+            invertDisplay: config.invertDisplay,
+            touch: config.touch === false ? undefined : config.touch,
+            displayClass: config.displayClass,
+            capabilities: config.capabilities,
+        };
+    }
+    if (config.width !== undefined)
+        base.width = config.width;
+    if (config.height !== undefined)
+        base.height = config.height;
+    if (config.nativeWidth !== undefined)
+        base.nativeWidth = config.nativeWidth;
+    if (config.nativeHeight !== undefined)
+        base.nativeHeight = config.nativeHeight;
+    if (config.colorFormat !== undefined)
+        base.colorFormat = config.colorFormat;
+    if (config.displayClass !== undefined)
+        base.displayClass = config.displayClass;
+    if (config.capabilities !== undefined)
+        base.capabilities = config.capabilities;
+    if (config.rotation !== undefined)
+        base.rotation = config.rotation;
+    if (config.backlight !== undefined)
+        base.backlight = config.backlight;
+    if (config.spiFrequency !== undefined)
+        base.spiFrequency = config.spiFrequency;
+    if (config.spiPins !== undefined)
+        base.spiPins = config.spiPins;
+    if (config.colorOrder !== undefined)
+        base.colorOrder = config.colorOrder;
+    if (config.invertDisplay !== undefined)
+        base.invertDisplay = config.invertDisplay;
+    if (config.touch === false)
+        base.touch = undefined;
+    else if (config.touch !== undefined)
+        base.touch = config.touch;
+    if (config.antialias !== undefined)
+        base.antialias = config.antialias;
+    if (config.fullscreen !== undefined)
+        base.fullscreen = config.fullscreen;
+    if (config.title !== undefined)
+        base.title = config.title;
+    if (config.icon !== undefined)
+        base.icon = config.icon;
+    // Carry scroll config through resolution so it reaches getDisplayProfile().
+    if (config.scroll !== undefined)
+        base.scroll = config.scroll;
+    return {
+        profile: base,
+        cs: config.cs ?? 5,
+        dc: config.dc ?? 21,
+        rst: config.rst ?? 22,
+        bus: config.bus ?? "SPI",
+        address: config.address ?? 0x3C,
+        reset: config.reset ?? -1,
+    };
+}
+/** Generate C++ code for a built-in touch library adapter. */
+export function generateTouchAdapter(touch) {
+    const cs = touch.cs ?? 0;
+    const irq = touch.irq;
+    if (touch.library === "XPT2046_Touchscreen") {
+        return {
+            includes: ["#include <XPT2046_Touchscreen.h>"],
+            declaration: `XPT2046_Touchscreen __tc_touch(${cs}${irq ? `, ${irq}` : ""});`,
+            functions: [
+                `static inline void touch_init() { __tc_touch.begin(); }`,
+                `static inline bool touch_isTouched() { return __tc_touch.touched(); }`,
+                `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+                `  TS_Point __tp = __tc_touch.getPoint();`,
+                `  if (x) *x = (int16_t)__tp.x;`,
+                `  if (y) *y = (int16_t)__tp.y;`,
+                `  if (z) *z = (int16_t)__tp.z;`,
+                `}`,
+            ].join("\n"),
+        };
+    }
+    if (touch.library === "Adafruit_TouchScreen" && touch.analogPins) {
+        const a = touch.analogPins;
+        return {
+            includes: ["#include <TouchScreen.h>"],
+            declaration: `TouchScreen __tc_touch = TouchScreen(${a.xp}, ${a.yp}, ${a.xm}, ${a.ym}, ${a.rx});`,
+            functions: [
+                `static inline void touch_init() {}`,
+                `static inline bool touch_isTouched() { return __tc_touch.isTouching(); }`,
+                `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+                `  TS_Point __tp = __tc_touch.getPoint();`,
+                `  if (x) *x = (int16_t)__tp.x;`,
+                `  if (y) *y = (int16_t)__tp.y;`,
+                `  if (z) *z = (int16_t)__tp.z;`,
+                `}`,
+            ].join("\n"),
+        };
+    }
+    if (touch.library === "Adafruit_STMPE610") {
+        return {
+            includes: ["#include <Adafruit_STMPE610.h>"],
+            declaration: `Adafruit_STMPE610 __tc_touch(${cs});`,
+            functions: [
+                `static inline void touch_init() { __tc_touch.begin(); }`,
+                `static inline bool touch_isTouched() { return __tc_touch.touched() && !__tc_touch.bufferEmpty(); }`,
+                `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+                `  TS_Point __tp = __tc_touch.getPoint();`,
+                `  if (x) *x = (int16_t)__tp.x;`,
+                `  if (y) *y = (int16_t)__tp.y;`,
+                `  if (z) *z = (int16_t)__tp.z;`,
+                `}`,
+            ].join("\n"),
+        };
+    }
+    if (touch.library === "FT6336U") {
+        const addr = touch.i2cAddress ?? 0x38;
+        // I2C addresses are conventional in hex in Arduino code.
+        const addrHex = "0x" + addr.toString(16).toUpperCase();
+        const i2cFrequency = touch.i2cFrequency ?? 400000;
+        const reset = touch.resetPin;
+        const resetLines = reset
+            ? [
+                `  pinMode(${reset}, OUTPUT);`,
+                `  digitalWrite(${reset}, LOW);`,
+                `  delay(10);`,
+                `  digitalWrite(${reset}, HIGH);`,
+                `  delay(500);`,
+            ].join("\n")
+            : ``;
+        return {
+            includes: ["#include <Wire.h>", "#include <RAK14014_FT6336U.h>"],
+            declaration: [
+                `FT6336U __tc_touch(${addrHex});`,
+                `static int16_t __tc_touch_cached_x = 0;`,
+                `static int16_t __tc_touch_cached_y = 0;`,
+                `static int16_t __tc_touch_cached_z = 0;`,
+                `static uint8_t __tc_touch_cached_valid = 0;`,
+            ].join("\n"),
+            functions: [
+                `static inline uint8_t __tc_ft6336u_read_block(uint8_t reg, uint8_t* buf, uint8_t len) {`,
+                `  Wire.beginTransmission(${addrHex});`,
+                `  Wire.write(reg);`,
+                `  if (Wire.endTransmission(false) != 0) return 0;`,
+                `  uint8_t got = Wire.requestFrom((uint8_t)${addrHex}, len);`,
+                `  if (got < len) return 0;`,
+                `  for (uint8_t i = 0; i < len; i++) {`,
+                `    if (!Wire.available()) return 0;`,
+                `    buf[i] = Wire.read();`,
+                `  }`,
+                `  return 1;`,
+                `}`,
+                `static inline void touch_init() {`,
+                resetLines,
+                `  __tc_touch.begin(Wire, ${addrHex});`,
+                `  Wire.setClock(${i2cFrequency});`,
+                `}`,
+                `static inline bool touch_isTouched() {`,
+                `  uint8_t buf[5] = {0, 0, 0, 0, 0};`,
+                `  __tc_touch_cached_valid = 0;`,
+                `  __tc_touch_cached_z = 0;`,
+                `  if (!__tc_ft6336u_read_block(0x02, buf, 5)) return false;`,
+                `  uint8_t count = buf[0] & 0x0F;`,
+                `  if (count == 0) return false;`,
+                `  __tc_touch_cached_x = (int16_t)(((uint16_t)(buf[1] & 0x0F) << 8) | buf[2]);`,
+                `  __tc_touch_cached_y = (int16_t)(((uint16_t)(buf[3] & 0x0F) << 8) | buf[4]);`,
+                `  __tc_touch_cached_z = 255;`,
+                `  __tc_touch_cached_valid = 1;`,
+                `  return true;`,
+                `}`,
+                `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+                `  if (!__tc_touch_cached_valid) {`,
+                `    (void)touch_isTouched();`,
+                `  }`,
+                `  if (x) *x = __tc_touch_cached_x;`,
+                `  if (y) *y = __tc_touch_cached_y;`,
+                `  if (z) *z = __tc_touch_cached_z;`,
+                `  __tc_touch_cached_valid = 0;`,
+                `}`,
+            ].join("\n"),
+        };
+    }
+    if (touch.library === "sdl") {
+        return {
+            includes: ["#include <SDL2/SDL.h>"],
+            declaration: `// SDL touch: no controller object — the event-driven mouse state`,
+            // __sdl_mouse_* is declared in the SDL display adapter (sdl.ts) and written
+            // by the host event loop from SDL_MOUSEBUTTONDOWN/MOTION/BUTTONUP. Reading
+            // it here (instead of polling SDL_GetMouseState each frame) makes input
+            // event-driven, removes a per-frame SDL query, and lets the same state feed
+            // hit-testing in the wheel handler. Forward-declared here in case the touch
+            // adapter is ever emitted without the display adapter (defensive).
+            functions: [
+                `extern uint8_t __sdl_mouse_down;`,
+                `extern int16_t __sdl_mouse_x;`,
+                `extern int16_t __sdl_mouse_y;`,
+                `static inline void touch_init() {}`,
+                `static inline bool touch_isTouched() {`,
+                `  return __sdl_mouse_down != 0;`,
+                `}`,
+                // Scale window/logical mouse coords to framebuffer coords. In a normal
+                // window the two are the same size (1:1), but in fullscreen (or any
+                // HiDPI case where the window is larger than the fixed framebuffer) the
+                // raw coords cover the whole window (e.g. 0..1920) while the framebuffer
+                // is w_×h_ (e.g. 320×240). Without scaling, clicks past the framebuffer
+                // size clamp to the corner. SDL_RenderCopy stretches the texture to fill
+                // the renderer, so the inverse scale maps window→framebuffer.
+                `static inline void touch_readRaw(int16_t* x, int16_t* y, int16_t* z) {`,
+                `  int __ww = 0, __wh = 0; SDL_GetWindowSize(__tc_display.win, &__ww, &__wh);`,
+                `  if (__ww <= 0) __ww = display_width();`,
+                `  if (__wh <= 0) __wh = display_height();`,
+                `  if (x) *x = (int16_t)((int32_t)__sdl_mouse_x * display_width() / __ww);`,
+                `  if (y) *y = (int16_t)((int32_t)__sdl_mouse_y * display_height() / __wh);`,
+                `  if (z) *z = 200;   // constant > default minPressure (10)`,
+                `}`,
+            ].join("\n"),
+        };
+    }
+    throw new Error(`Unknown touch library "${touch.library}". ` +
+        `Use { adapter: './path' } for custom touch adapters, or one of: ` +
+        `XPT2046_Touchscreen, Adafruit_TouchScreen, Adafruit_STMPE610, FT6336U, sdl.`);
+}

package/dist/api/shared/graphics-strategy.d.ts

@@ -0,0 +1,29 @@
+import type { DisplayHALOp } from "./display-op-ir.js";
+export interface GraphicsCapacity {
+    /** Max nodes the retained tree may hold on this target. */
+    maxNodes: number;
+    /** Max ui.bind() entries. */
+    maxBindings: number;
+    /** Max simultaneously-armed transitions. */
+    maxActiveTransitions: number;
+    /** Where the static node table lives. */
+    nodeStorage: "progmem" | "flash";
+}
+export interface PlatformGraphicsStrategy {
+    /** Resolve a display HAL op to target-specific C++. Return undefined to fall back. */
+    resolveDisplayOp(op: DisplayHALOp): {
+        code?: string;
+        expression?: string;
+    } | undefined;
+    /** Display driver ids this framework provides (e.g. new Set(["ili9341"])). */
+    supportedDisplayDrivers(): ReadonlySet<string>;
+    /** Target color format — drives transpile-time color resolution.
+     *  Phase 1: 565/mono active. Phase 2+ will widen the plumbing (ColorFormat
+     *  aliases in model.ts/ui-lowering.ts, resolveColor signature) to admit
+     *  rgb666/rgb888/palette, at which point resolveColor888 is the resolution
+     *  entry point. Widening only the return type now would break assignment to
+     *  the "rgb565" | "mono" field types downstream. */
+    colorFormat(): "rgb565" | "rgb666" | "rgb888" | "mono";
+    /** Per-target capacity caps (node/binding/transition limits, storage). */
+    graphicsCapacity(): GraphicsCapacity;
+}

package/dist/api/shared/graphics-strategy.js

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// PlatformGraphicsStrategy — per-target graphics capacity and driver resolution
+//
+// Frameworks implement this sub-interface to (a) declare which display drivers
+// they support (used by ui.mount() for fail-fast validation), (b) declare the
+// target's color format (drives transpile-time color resolution), and (c)
+// translate display HAL ops to driver-specific C++.
+//
+// Mirrors the existing resolveHALOperation() seam.
+// ---------------------------------------------------------------------------
+export {};