@typecad/cuttlefish 0.1.0-alpha.1

package/dist/api/shared/display-adapters/st7796.js

@@ -0,0 +1,132 @@
+// ---------------------------------------------------------------------------
+// ST7796S display adapter — targets the Adafruit_ST7735_and_ST7789_Library
+// fork that exposes the Adafruit_ST7796S class (320×480 SPI TFT).
+//
+// Color mode: RGB565 only. The Adafruit_ST7796S init sequence hardcodes
+// ST77XX_COLMOD = 0x55 (16-bit/pixel). RGB666/18-bit would require patching
+// the library's init array (0x55 → 0x66) AND overriding Adafruit_SPITFT's
+// 565-native writePixels — out of scope for v1. Requesting rgb666 throws.
+//
+// Init API: Adafruit_ST7796S requires init(w,h,rowOff,colOff,colorOrder) to
+// send the panel init sequence. begin(freq) alone would skip it (blank panel).
+// SPI frequency handling: init() runs the panel command sequence and initializes
+// Adafruit_SPITFT. If the profile requests a frequency, update the transaction
+// settings with setSPISpeed() after init; do not call initSPI() a second time.
+// ---------------------------------------------------------------------------
+export const st7796Adapter = (display) => {
+    const cs = display._mountCs;
+    const dc = display._mountDc;
+    const rst = display._mountRst;
+    const rotation = display.rotation ?? 1;
+    const spiFreq = display.spiFrequency;
+    const invertDisplay = display.invertDisplay;
+    const colorOrder = display.colorOrder === "bgr" ? "ST7796S_BGR" : "ST7796S_RGB";
+    if (display.colorFormat === "rgb666" || display.colorFormat === "rgb888") {
+        throw new Error(`RGB666/RGB888 is not supported by the Adafruit_ST7796S library: ` +
+            `its init sequence hardcodes COLMOD=0x55 (RGB565). Use colorFormat: "rgb565". ` +
+            `True 18-bit support requires patching the library init array and overriding ` +
+            `Adafruit_SPITFT's 565-native writePixels — tracked as a follow-up.`);
+    }
+    const includes = [
+        "#define CuttlefishDisplayTarget Adafruit_GFX",
+        "#define CuttlefishCanvas16 GFXcanvas16",
+        "#include <Adafruit_GFX.h>",
+        "#include <Adafruit_ST7796S.h>",
+    ].join("\n");
+    const inversionLines = invertDisplay === undefined
+        ? []
+        : [
+            `  __tc_display.startWrite();`,
+            `  __tc_display.writeCommand(${invertDisplay ? "ST77XX_INVON" : "ST77XX_INVOFF"});`,
+            `  __tc_display.endWrite();`,
+        ];
+    return {
+        includes,
+        declaration: `Adafruit_ST7796S __tc_display = Adafruit_ST7796S(${cs}, ${dc}, ${rst});`,
+        functions: [
+            `// --- Display adapter: ST7796S (RGB565) ---`,
+            `static inline void display_init() {`,
+            `  __tc_display.init(320, 480, 0, 0, ${colorOrder});`,
+            spiFreq ? `  __tc_display.setSPISpeed(${spiFreq});` : ``,
+            ...inversionLines,
+            `  __tc_display.setRotation(${rotation});`,
+            `  __tc_display.fillScreen(0x0000);`,
+            `}`,
+            ``,
+            `static inline void display_fillScreen(UI_COLOR_T color) { __tc_display.fillScreen((uint16_t)color); }`,
+            `static inline CuttlefishDisplayTarget* display_defaultTarget() { return &__tc_display; }`,
+            `static inline int16_t display_width() { return __tc_display.width(); }`,
+            `static inline int16_t display_height() { return __tc_display.height(); }`,
+            ``,
+            `static inline void display_startWrite() { __tc_display.startWrite(); }`,
+            `static inline void display_endWrite() { __tc_display.endWrite(); }`,
+            `static inline void display_setAddrWindow(int16_t x, int16_t y, int16_t w, int16_t h) {`,
+            `  __tc_display.setAddrWindow(x, y, w, h);`,
+            `}`,
+            `static inline void display_writePixels(uint16_t* pixels, uint32_t count) {`,
+            `  __tc_display.writePixels(pixels, count);`,
+            `}`,
+            ``,
+            `static inline CuttlefishCanvas16* display_createCanvas(int16_t w, int16_t h) {`,
+            `  return new GFXcanvas16(w, h);`,
+            `}`,
+            `static inline CuttlefishCanvas16* display_createCanvasPsram(int16_t w, int16_t h) {`,
+            `#if defined(ESP32) && defined(BOARD_HAS_PSRAM)`,
+            `  return new (ps_malloc(sizeof(GFXcanvas16))) GFXcanvas16(w, h);`,
+            `#else`,
+            `  (void)w; (void)h;`,
+            `  return nullptr;`,
+            `#endif`,
+            `}`,
+            `static inline void display_deleteCanvas(CuttlefishCanvas16* canvas) { delete canvas; }`,
+            `static inline int16_t display_canvasWidth(CuttlefishCanvas16* canvas) { return canvas->width(); }`,
+            `static inline int16_t display_canvasHeight(CuttlefishCanvas16* canvas) { return canvas->height(); }`,
+            `static inline uint16_t* display_canvasBuffer(CuttlefishCanvas16* canvas) { return canvas->getBuffer(); }`,
+            `static inline uint16_t display_canvasGetPixel(CuttlefishCanvas16* canvas, int16_t x, int16_t y) { return canvas->getPixel(x, y); }`,
+            `static inline void display_canvasFillScreen(CuttlefishCanvas16* canvas, UI_COLOR_T color) { canvas->fillScreen((uint16_t)color); }`,
+            `static inline void display_canvasFillRect(CuttlefishCanvas16* canvas, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  canvas->fillRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            ``,
+            `static inline void display_targetDrawPixel(CuttlefishDisplayTarget* target, int16_t x, int16_t y, UI_COLOR_T color) { target->drawPixel(x, y, (uint16_t)color); }`,
+            `static inline int16_t display_targetWidth(CuttlefishDisplayTarget* target) { return target->width(); }`,
+            `static inline int16_t display_targetHeight(CuttlefishDisplayTarget* target) { return target->height(); }`,
+            `static inline void display_targetDrawRGBBitmap(CuttlefishDisplayTarget* target, int16_t x, int16_t y, const uint16_t* bitmap, int16_t w, int16_t h) {`,
+            `  target->drawRGBBitmap(x, y, bitmap, w, h);`,
+            `}`,
+            `static inline void display_targetFillRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  target->fillRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawFastHLine(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, UI_COLOR_T color) {`,
+            `  target->drawFastHLine(x, y, w, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawFastVLine(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t h, UI_COLOR_T color) {`,
+            `  target->drawFastVLine(x, y, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetFillRoundRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {`,
+            `  target->fillRoundRect(x, y, w, h, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, UI_COLOR_T color) {`,
+            `  target->drawRect(x, y, w, h, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawRoundRect(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t w, int16_t h, int16_t r, UI_COLOR_T color) {`,
+            `  target->drawRoundRect(x, y, w, h, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawLine(CuttlefishDisplayTarget* target, int16_t x0, int16_t y0, int16_t x1, int16_t y1, UI_COLOR_T color) {`,
+            `  target->drawLine(x0, y0, x1, y1, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetFillCircle(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {`,
+            `  target->fillCircle(x, y, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetDrawCircle(CuttlefishDisplayTarget* target, int16_t x, int16_t y, int16_t r, UI_COLOR_T color) {`,
+            `  target->drawCircle(x, y, r, (uint16_t)color);`,
+            `}`,
+            `static inline void display_targetSetCursor(CuttlefishDisplayTarget* target, int16_t x, int16_t y) { target->setCursor(x, y); }`,
+            `static inline void display_targetSetTextColor(CuttlefishDisplayTarget* target, UI_COLOR_T fg) { target->setTextColor((uint16_t)fg); }`,
+            `static inline void display_targetSetTextColorBg(CuttlefishDisplayTarget* target, UI_COLOR_T fg, UI_COLOR_T bg) { target->setTextColor((uint16_t)fg, (uint16_t)bg); }`,
+            `static inline void display_targetSetTextSize(CuttlefishDisplayTarget* target, uint8_t size) { target->setTextSize(size); }`,
+            `static inline void display_targetSetTextWrap(CuttlefishDisplayTarget* target, bool wrap) { target->setTextWrap(wrap); }`,
+            `static inline void display_targetPrint(CuttlefishDisplayTarget* target, const char* text) { target->print(text); }`,
+        ].join("\n"),
+    };
+};

package/dist/api/shared/display-capabilities.d.ts

@@ -0,0 +1,45 @@
+/** Native pixel format the panel stores / the shim quantizes to at push. */
+export type NativeFormat = "rgb888" | "rgb666" | "rgb565" | "mono" | "palette";
+/** How the panel accepts refreshed pixels. */
+export type RefreshModel = "immediate" | "deferred-partial" | "deferred-full";
+/** Scope of partial-refresh support (e-ink panels vary). */
+export type PartialRefreshScope = "none" | "mono-only" | "full";
+/** Feature flags the shim can honor. False ⇒ the core snaps/disables. */
+export interface DisplayFeatureFlags {
+    antialias: boolean;
+    gradients: boolean;
+    opacityBlend: boolean;
+    smoothScroll: boolean;
+    animation: boolean;
+}
+export interface DisplayCapabilities {
+    nativeFormat: NativeFormat;
+    /** For palette displays (e-ink multi-color): the ink set as CSS strings. */
+    palette?: string[];
+    refreshModel: RefreshModel;
+    partialRefresh: PartialRefreshScope;
+    /** Latency (ms) of a full refresh; used by the refresh scheduler (Phase 4). */
+    fullRefreshMs?: number;
+    /** Max sustained partial refreshes/sec. */
+    maxPartialFps?: number;
+    /** Shim requires a backing store (e-ink, any dithered target). */
+    requiresBackingStore: boolean;
+    features: DisplayFeatureFlags;
+}
+/** The capabilities a fast RGB565 TFT has today — the Phase 2 default so
+ *  output stays byte-identical with pre-descriptor behavior. */
+export declare function defaultTftCapabilities(): DisplayCapabilities;
+/** A minimal profile shape deriveCapabilities reads. Keeps it decoupled from
+ *  the full DisplayProfile (which references this module). */
+interface ProfileLike {
+    width: number;
+    height: number;
+    colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono";
+    displayClass?: "tft" | "eink" | "oled";
+    capabilities?: DisplayCapabilities;
+}
+/** Derive capabilities from a profile. Explicit `capabilities` on the profile
+ *  win; otherwise derive from `displayClass` + `colorFormat`. A bare TFT profile
+ *  (no displayClass) defaults to defaultTftCapabilities() — byte-identical. */
+export declare function deriveCapabilities(profile: ProfileLike): DisplayCapabilities;
+export {};

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

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// DisplayCapabilities — declarative description of a display's rendering
+// capabilities. The single source of truth that @media evaluation, feature-flag
+// consultation, and (in later phases) the display shim all read.
+//
+// Phase 2 introduces the type + derivation. Default = today's TFT behavior, so
+// output is byte-identical. Phase 3+ consumes it for shim routing.
+// ---------------------------------------------------------------------------
+/** The capabilities a fast RGB565 TFT has today — the Phase 2 default so
+ *  output stays byte-identical with pre-descriptor behavior. */
+export function defaultTftCapabilities() {
+    return {
+        nativeFormat: "rgb565",
+        refreshModel: "immediate",
+        partialRefresh: "full",
+        requiresBackingStore: false,
+        features: {
+            antialias: true,
+            gradients: true,
+            opacityBlend: true,
+            smoothScroll: true,
+            animation: true,
+        },
+    };
+}
+/** Derive capabilities from a profile. Explicit `capabilities` on the profile
+ *  win; otherwise derive from `displayClass` + `colorFormat`. A bare TFT profile
+ *  (no displayClass) defaults to defaultTftCapabilities() — byte-identical. */
+export function deriveCapabilities(profile) {
+    if (profile.capabilities)
+        return profile.capabilities;
+    if (profile.displayClass === "eink" || profile.displayClass === "oled") {
+        return {
+            nativeFormat: profile.colorFormat === "mono" ? "mono" : "palette",
+            refreshModel: "deferred-partial",
+            partialRefresh: profile.colorFormat === "mono" ? "mono-only" : "none",
+            requiresBackingStore: true,
+            features: {
+                antialias: false,
+                gradients: false,
+                opacityBlend: false,
+                smoothScroll: false,
+                animation: false,
+            },
+        };
+    }
+    const base = defaultTftCapabilities();
+    // rgb888 TFT (e.g. the SDL native target) carries true 888 to the surface;
+    // all other TFT color formats are 565 by default (byte-identical history).
+    if (profile.colorFormat === "rgb888") {
+        base.nativeFormat = "rgb888";
+    }
+    return base;
+}

package/dist/api/shared/display-op-ir.d.ts

@@ -0,0 +1,62 @@
+export interface DisplayInitOp {
+    operation: "display.init";
+    /** Bus identifier, e.g. "SPI" or "Wire" */
+    bus: string;
+    /** Chip-select pin number */
+    cs: number;
+    /** Data/Command pin number */
+    dc: number;
+    /** Reset pin number */
+    rst: number;
+    /** Panel width in pixels */
+    width: number;
+    /** Panel height in pixels */
+    height: number;
+    /** Driver id, e.g. "ili9341" — must be in supportedDisplayDrivers() */
+    driver: string;
+    /** Optional SPI clock frequency in Hz for SPI-backed displays. */
+    spiFrequency?: number;
+    /** I2C address (hex) for I2C-backed displays like SSD1309. */
+    address?: number;
+    /** Reset pin for I2C displays (separate from SPI rst). */
+    reset?: number;
+}
+export interface DisplayFillRectOp {
+    operation: "display.fill_rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Pre-resolved color value (rgb565 uint16 on color targets, 0/1 on mono) */
+    color: number;
+}
+export interface DisplayDrawTextOp {
+    operation: "display.draw_text";
+    x: number;
+    y: number;
+    text: string;
+    /** Font id, e.g. "8x16" — resolved by the driver to a font table */
+    fontId: string;
+    /** Pre-resolved color value */
+    color: number;
+}
+export interface DisplayDrawRectOp {
+    operation: "display.draw_rect";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: number;
+}
+export interface DisplayFlushOp {
+    operation: "display.flush";
+    /** Dirty rectangles to push to the panel this frame */
+    rects: Array<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+}
+export type DisplayHALOp = DisplayInitOp | DisplayFillRectOp | DisplayDrawTextOp | DisplayDrawRectOp | DisplayFlushOp;
+export declare const DISPLAY_OPERATION_KINDS: readonly ["display.init", "display.fill_rect", "display.draw_text", "display.draw_rect", "display.flush"];

package/dist/api/shared/display-op-ir.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// Display HAL Operations — semantic graphics draw calls
+//
+// Each DisplayHALOp node represents a single display operation. Framework
+// strategies (PlatformGraphicsStrategy.resolveDisplayOp) translate these into
+// driver-specific C++ (ILI9341 SPI commands, SSD1306 I2C bitpacks, native
+// terminal cells). Colors are pre-resolved at transpile time to the target's
+// color format, so no runtime color conversion occurs.
+// ---------------------------------------------------------------------------
+// Runtime registry of every display operation discriminator. Lets tests verify
+// union membership at runtime (type-only `import type` assertions are erased
+// and pass vacuously). Keep in sync with DisplayHALOp above.
+export const DISPLAY_OPERATION_KINDS = [
+    "display.init",
+    "display.fill_rect",
+    "display.draw_text",
+    "display.draw_rect",
+    "display.flush",
+];

package/dist/api/shared/display-profile.d.ts

@@ -0,0 +1,265 @@
+import type { DisplayCapabilities } from "./display-capabilities.js";
+export type TouchLibrary = "XPT2046_Touchscreen" | "Adafruit_TouchScreen" | "Adafruit_STMPE610" | "FT6336U" | "sdl";
+export interface TouchProfile {
+    /**
+     * Either a built-in library name OR a path to a custom TypeScript adapter
+     * file (relative to the project root). The adapter must export:
+     *   - isTouched(): boolean
+     *   - read(): { x: number, y: number, z: number }
+     *
+     * Built-in: { library: 'XPT2046_Touchscreen', cs: 14, irq: 2 }
+     * Custom:   { adapter: './my-touch-adapter' }
+     */
+    library?: TouchLibrary;
+    adapter?: string;
+    /** CS pin for SPI touch controllers (separate from display CS). */
+    cs?: number;
+    /** IRQ pin (optional). */
+    irq?: number;
+    /** Resistive 4-wire analog pins (Adafruit_TouchScreen only). */
+    analogPins?: {
+        xp: number;
+        yp: number;
+        xm: number;
+        ym: number;
+        rx: number;
+    };
+    /** Software SPI pins (optional). */
+    swSpiPins?: {
+        mosi: number;
+        miso: number;
+        sck: number;
+    };
+    /** I2C address for I2C touch controllers (FT6336U default 0x38). */
+    i2cAddress?: number;
+    /** I2C bus speed in Hz for I2C touch controllers. */
+    i2cFrequency?: number;
+    /** Reset pin for touch controllers requiring a hardware-reset sequence
+     *  before begin() (FT6336U on boards with a reset GPIO tied to the chip). */
+    resetPin?: number;
+    /** Raw ADC calibration — maps touch controller raw values to display pixels. */
+    calibration: {
+        xMin: number;
+        xMax: number;
+        yMin: number;
+        yMax: number;
+    };
+    /** Minimum pressure/z to register a touch (default 10). */
+    minPressure?: number;
+}
+export interface DisplayProfile {
+    driver: string;
+    /** Visible screen-space dimensions used by UI layout and preview. */
+    width: number;
+    height: number;
+    /** Native panel dimensions before rotation, when they differ from layout size. */
+    nativeWidth?: number;
+    nativeHeight?: number;
+    colorFormat: "rgb565" | "rgb666" | "rgb888" | "mono";
+    /** Display class: "tft" (default) for fast-refresh panels, "eink" for
+     *  bistable/slow-refresh panels. Drives capability derivation + @media. */
+    displayClass?: "tft" | "eink" | "oled";
+    /** Explicit capabilities override. If absent, capabilities are derived from
+     *  displayClass + colorFormat. Phase 2 default (bare TFT) = today's behavior. */
+    capabilities?: DisplayCapabilities;
+    rotation: number;
+    backlight?: number;
+    spiFrequency?: number;
+    spiPins?: {
+        mosi: number;
+        sck: number;
+        miso: number;
+    };
+    /** Pixel color channel order expected by the panel module. Default: rgb. */
+    colorOrder?: "rgb" | "bgr";
+    /** Optional explicit display inversion override. Some controller libraries
+     *  use panel-specific defaults that do not match every module. */
+    invertDisplay?: boolean;
+    touch?: TouchProfile;
+    /** Enable antialiased rendering for circles, lines, rounded corners, and text
+     *  unless a node opts out with font-smoothing:none.
+     *  Renders AA work to offscreen GFXcanvas16 buffers, blends edges, then draws. */
+    antialias?: boolean;
+    /** SDL desktop target only: render the window borderless at the current
+     *  desktop resolution, scaling the fixed framebuffer to fill the monitor.
+     *  true (or "desktop") = `SDL_WINDOW_FULLSCREEN_DESKTOP`. Ignored by hardware
+     *  targets. Default: off (a normal titled window at width × height). */
+    fullscreen?: boolean | "desktop";
+    /** SDL desktop target only: the OS window title. Default "cuttlefish".
+     *  Overridable at runtime via ui.window.setTitle(). Ignored by hardware. */
+    title?: string;
+    /** SDL desktop target only: window/taskbar icon image file path (BMP via
+     *  core SDL2; .png/.ico require SDL_image). Ignored by hardware. */
+    icon?: string;
+    /** Scroll engine capability + physics tunables. Defaults are derived from the
+     *  declared touch hardware when omitted (see resolveScrollConfig). */
+    scroll?: ScrollConfig;
+}
+/** Extended profile with mount wiring (cs/dc/rst/address/reset from ui.mount).
+ *  Lives here (not in the store) so api/shared has zero upward dependencies
+ *  on ui/. The store populates it; display-adapter.ts types against it. */
+export interface ResolvedDisplay extends DisplayProfile {
+    _mountCs: number;
+    _mountDc: number;
+    _mountRst: number;
+    _mountBus: string;
+    _mountAddress: number;
+    _mountReset: number;
+    /** Arduino FQBN (e.g. "esp32:esp32:esp32s3:PSRAM=opi"), used to derive PSRAM
+     *  availability for the scroll-canvas-memory budget. Optional. */
+    _buildTarget?: string;
+}
+export interface DisplayConfig {
+    profile?: string;
+    driver?: string;
+    /** Visible screen-space dimensions used by UI layout and preview. */
+    width?: number;
+    height?: number;
+    /** Native panel dimensions before rotation, when they differ from layout size. */
+    nativeWidth?: number;
+    nativeHeight?: number;
+    colorFormat?: "rgb565" | "rgb888" | "mono";
+    displayClass?: "tft" | "eink" | "oled";
+    capabilities?: DisplayCapabilities;
+    rotation?: number;
+    backlight?: number;
+    spiFrequency?: number;
+    spiPins?: {
+        mosi: number;
+        sck: number;
+        miso: number;
+    };
+    /** Pixel color channel order expected by the panel module. Default: rgb. */
+    colorOrder?: "rgb" | "bgr";
+    /** Optional explicit display inversion override. */
+    invertDisplay?: boolean;
+    touch?: TouchProfile | false;
+    cs?: number;
+    dc?: number;
+    rst?: number;
+    bus?: string;
+    /** I2C address (hex, e.g. 0x3C). Used by I2C display drivers like SSD1309. */
+    address?: number;
+    /** Reset pin for I2C displays (separate from SPI `rst`). */
+    reset?: number;
+    antialias?: boolean;
+    /** SDL desktop target only: render the window borderless at the current
+     *  desktop resolution, scaling the fixed framebuffer to fill the monitor.
+     *  Ignored by hardware targets. Default: off. */
+    fullscreen?: boolean | "desktop";
+    /** SDL desktop target only: the OS window title. Default "cuttlefish". */
+    title?: string;
+    /** SDL desktop target only: window/taskbar icon image file path (BMP). */
+    icon?: string;
+    /** Override the CSS theme file. Relative paths resolve from the .ui.html
+     *  directory; absolute paths are used as-is. Default: sibling .ui.css. */
+    themeCss?: string;
+    /** Activate a class-scoped theme for CSS variables (e.g. "dark"). When set,
+     *  var() substitution prefers variables defined under `.dark { ... }` over
+     *  :root. One theme per build (transpile-time selection). */
+    themeClass?: string;
+    /** Scroll engine capability + physics tunables. Defaults are derived from the
+     *  declared touch hardware when omitted (see resolveScrollConfig). */
+    scroll?: ScrollConfig;
+}
+export interface DisplaySize {
+    width: number;
+    height: number;
+}
+export declare function normalizeDisplayRotation(rotation?: number): 0 | 1 | 2 | 3;
+/** Return the screen-space dimensions after the display rotation is applied. */
+export declare function effectiveDisplaySize(display: {
+    width: number;
+    height: number;
+    nativeWidth?: number;
+    nativeHeight?: number;
+    rotation?: number;
+}): DisplaySize;
+/** Input-quality axis: how raw touch becomes a smoothed scroll delta. */
+export type ScrollInputTier = "capacitive" | "resistive" | "none";
+/** Frame/refresh-budget axis: whether per-frame canvas repaint (incl. the
+ *  rubber-band animation) is affordable. Constrained tiers get a cheaper path. */
+export type ScrollRenderTier = "full" | "constrained";
+/** Author-facing scroll config (all optional; defaults derived from hardware). */
+export interface ScrollConfig {
+    inputTier?: ScrollInputTier;
+    renderTier?: ScrollRenderTier;
+    /** Multiplier applied to drag deltas before scroll physics. Default 1.0. */
+    dragScale?: number;
+    /** Ceiling on rubber-band excursion past a boundary, in px. Default 40. */
+    maxOverscroll?: number;
+    /** Rubber-band resistance curve (higher = stiffer, less stretch). Default 0.5. */
+    stiffness?: number;
+    /** Radius within which release snaps to a boundary for free, in px. Default 12. */
+    edgeSnapPx?: number;
+    /** Low-pass coefficient for the resistive input filter (0 = passthrough).
+     *  Capacitive/preview always passthrough regardless. Default 0.3. */
+    inputSmoothing?: number;
+    /** default true: trust the declared tiers (deterministic). When false, runtime
+     *  probes may refine the input smoothing level from observed sample quality. */
+    overrideProbes?: boolean;
+    /** Emit per-frame scroll/canvas telemetry over Serial (UI_SCROLL_DEBUG). Off by
+     *  default — enable temporarily to diagnose scroll/canvas draw skips on-device. */
+    debug?: boolean;
+    /** Max RGB565 scroll viewport canvas size (w×h×2 bytes) assumed to fit in heap
+     *  for Mode B smooth scrolling on the target. Default ~88 KB (ESP32 no PSRAM). */
+    scrollCanvasBudgetBytes?: number;
+}
+/** Fully-resolved scroll config — every field populated, ready for emit. */
+export interface ResolvedScrollConfig {
+    inputTier: ScrollInputTier;
+    renderTier: ScrollRenderTier;
+    dragScale: number;
+    maxOverscroll: number;
+    stiffness: number;
+    edgeSnapPx: number;
+    inputSmoothing: number;
+    overrideProbes: boolean;
+    debug: boolean;
+    scrollCanvasBudgetBytes: number;
+}
+/** Default RGB565 scroll viewport canvas budget (~88 KB, ESP32-class SRAM). */
+export declare 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 declare const PSRAM_SCROLL_CANVAS_BUDGET_BYTES = 2000000;
+/** 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 declare function buildTargetHasPsram(buildTarget: string | undefined): boolean;
+/**
+ * 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 declare function resolveScrollConfig(display: {
+    touch?: TouchProfile | false;
+    scroll?: ScrollConfig;
+}, ctx?: {
+    buildTarget?: string;
+}): ResolvedScrollConfig;
+export declare function resolveDisplayProfile(config: DisplayConfig, registry: Map<string, DisplayProfile>): {
+    profile: DisplayProfile;
+    cs: number;
+    dc: number;
+    rst: number;
+    bus: string;
+    address: number;
+    reset: number;
+};
+export interface TouchAdapterCodegen {
+    /** C++ #include lines for the touch library. */
+    includes: string[];
+    /** C++ declaration(s) for the touch object (file scope). */
+    declaration: string;
+    /** C++ static inline shim functions: touch_init, touch_isTouched, touch_readRaw. */
+    functions: string;
+}
+/** Generate C++ code for a built-in touch library adapter. */
+export declare function generateTouchAdapter(touch: TouchProfile): TouchAdapterCodegen;