@typecad/cuttlefish 1.0.0-alpha.7 → 1.0.0-alpha.8

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

@@ -25,43 +25,13 @@ 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) {
+export function resolveScrollConfig(display) {
     const s = display.scroll ?? {};
     const lib = display.touch && typeof display.touch === "object"
         ? display.touch.library
@@ -71,15 +41,6 @@ export function resolveScrollConfig(display, ctx) {
         : display.touch
             ? "capacitive"
             : "none";
-    // PSRAM-aware canvas budget: an explicit override always wins; otherwise use
-    // the PSRAM budget when the target opts into PSRAM — either via an explicit
-    // frameworkData.psram flag (IDF path) or an Arduino FQBN PSRAM= option — so
-    // the scroll-canvas-memory diagnostic doesn't emit stale warnings for canvases
-    // the runtime allocates in external RAM without issue. Else the SRAM default.
-    const psramBudget = ctx?.psram === true || 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",
@@ -90,7 +51,6 @@ export function resolveScrollConfig(display, ctx) {
         inputSmoothing: s.inputSmoothing ?? 0.3,
         overrideProbes: s.overrideProbes ?? true,
         debug: s.debug ?? false,
-        scrollCanvasBudgetBytes: s.scrollCanvasBudgetBytes ?? budgetDefault,
     };
 }
 export function resolveDisplayProfile(config, registry) {
@@ -152,6 +112,8 @@ export function resolveDisplayProfile(config, registry) {
         base.colorOrder = config.colorOrder;
     if (config.invertDisplay !== undefined)
         base.invertDisplay = config.invertDisplay;
+    if (config.scanlineSync !== undefined)
+        base.scanlineSync = config.scanlineSync;
     if (config.touch === false)
         base.touch = undefined;
     else if (config.touch !== undefined)
@@ -179,13 +141,18 @@ export function resolveDisplayProfile(config, registry) {
 }
 /** Generate C++ code for a built-in touch library adapter.
  *
- *  Strategy-owned touch adapters (ESP32 native) take precedence: when the
- *  strategy's `providesTouchAdapter()` returns true and `resolveTouchAdapter`
- *  returns non-null, that codegen wins. Otherwise falls through to the
- *  built-in library switch below (the Arduino path, unchanged).
+ *  Strategy-owned touch adapters take precedence: when the strategy's
+ *  `providesTouchAdapter()` returns true and `resolveTouchAdapter` returns
+ *  non-null, that codegen wins. The Arduino-ecosystem libraries
+ *  (XPT2046_Touchscreen, Adafruit_TouchScreen, Adafruit_STMPE610, FT6336U)
+ *  are strategy-owned — they live in @typecad/framework-arduino
+ *  (src/displays/touch-adapters-codegen.ts) and ArduinoStrategy dispatches to
+ *  them. Cuttlefish keeps only the framework-agnostic `sdl` path here.
  *
- *  Passing `undefined` for the strategy (or a strategy that doesn't provide
- *  touch adapters) keeps the historical behavior — the Arduino library switch.
+ *  Passing `undefined` for the strategy (or a strategy whose
+ *  resolveTouchAdapter returns undefined for the given library) falls through
+ *  to the `sdl` branch below; any other library without a strategy-provided
+ *  adapter throws.
  */
 export function generateTouchAdapter(touch, strategy) {
     if (strategy?.providesTouchAdapter?.() && strategy.resolveTouchAdapter) {
@@ -193,124 +160,6 @@ export function generateTouchAdapter(touch, strategy) {
         if (code)
             return code;
     }
-    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>"],
@@ -340,14 +189,17 @@ export function generateTouchAdapter(touch, strategy) {
                 `  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 (x) *x = static_cast<int16_t>(static_cast<int32_t>(__sdl_mouse_x) * display_width() / __ww);`,
+                `  if (y) *y = static_cast<int16_t>(static_cast<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.`);
+    throw new Error(`No touch adapter for library "${touch.library}". ` +
+        `The built-in Arduino touch libraries (XPT2046_Touchscreen, Adafruit_TouchScreen, ` +
+        `Adafruit_STMPE610, FT6336U) are provided by @typecad/framework-arduino — pass the ` +
+        `ArduinoStrategy (or another framework strategy that provides touch adapters) so its ` +
+        `resolveTouchAdapter can dispatch to them. Otherwise use the framework-agnostic ` +
+        `"sdl" library, or { adapter: './path' } for a custom touch adapter.`);
 }

package/dist/api/shared/framework-manifest-registry.d.ts

@@ -1,5 +1,5 @@
 import type { FrameworkManifest } from './framework-manifest.js';
-export declare const KNOWN_FRAMEWORK_PACKAGES: readonly ["@typecad/framework-arduino", "@typecad/framework-avr", "@typecad/framework-esp32"];
+export declare const KNOWN_FRAMEWORK_PACKAGES: readonly ["@typecad/framework-arduino", "@typecad/framework-zephyr"];
 export type KnownFrameworkPackage = typeof KNOWN_FRAMEWORK_PACKAGES[number];
 /**
  * Loads a framework's manifest via its `./framework.manifest` subpath export.

package/dist/api/shared/framework-manifest-registry.js

@@ -1,15 +1,17 @@
 // ---------------------------------------------------------------------------
 // Framework manifest discovery
 //
-// KNOWN_FRAMEWORK_PACKAGES is the authoritative list of framework packages.
-// Add a new framework here when it ships. loadFrameworkManifest uses the
-// "./framework.manifest" subpath export each framework declares in its
-// package.json.
+// KNOWN_FRAMEWORK_PACKAGES is the authoritative list of framework packages
+// that ship a framework.manifest (i.e. participate in the manifest validation
+// system). It names real packages by their npm scope+name so the manifest
+// validator and coverage tooling can iterate them — it is not framework-
+// specific knowledge. Add a new framework here when it ships a manifest.
+// loadFrameworkManifest uses the "./framework.manifest" subpath export each
+// framework declares in its package.json.
 // ---------------------------------------------------------------------------
 export const KNOWN_FRAMEWORK_PACKAGES = [
     '@typecad/framework-arduino',
-    '@typecad/framework-avr',
-    '@typecad/framework-esp32',
+    '@typecad/framework-zephyr',
 ];
 /**
  * Loads a framework's manifest via its `./framework.manifest` subpath export.

package/dist/api/shared/framework-manifest.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-declare const HAL_CATEGORIES: readonly ["gpio", "pwm", "adc", "dac", "interrupts", "tone", "timing", "power", "i2c", "spi", "uart", "pulse", "shift", "board", "wdt", "wifi", "http", "display"];
+declare const HAL_CATEGORIES: readonly ["gpio", "pwm", "adc", "dac", "interrupts", "tone", "timing", "power", "i2c", "spi", "uart", "pulse", "shift", "board", "wdt", "wifi", "http", "mqtt", "display"];
 export type HalCategory = typeof HAL_CATEGORIES[number];
 export declare const FrameworkManifestSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
@@ -74,23 +74,102 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         }, {
             supported: boolean;
         }>>;
+    }, "strip", z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        [x: string]: {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, z.objectOutputType<{
+        [x: string]: z.ZodObject<{
+            supported: z.ZodBoolean;
+            unsupportedReason: z.ZodOptional<z.ZodString>;
+            ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+            partialCoverage: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
             supported: boolean;
             ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             partialCoverage: boolean;
             unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
+        }, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        }>;
+    } & {
+        raw: z.ZodDefault<z.ZodObject<{
+            supported: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+        }, {
+            supported: boolean;
+        }>>;
+    }, z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
     }, {
-        [x: string]: {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, "strip">, z.objectInputType<{
+        [x: string]: z.ZodObject<{
+            supported: z.ZodBoolean;
+            unsupportedReason: z.ZodOptional<z.ZodString>;
+            ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+            partialCoverage: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        }, {
             supported: boolean;
             ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
             unsupportedReason?: string | undefined;
             partialCoverage?: boolean | undefined;
-        };
-        raw?: unknown;
-    }>;
+        }>;
+    } & {
+        raw: z.ZodDefault<z.ZodObject<{
+            supported: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            supported: boolean;
+        }, {
+            supported: boolean;
+        }>>;
+    }, z.ZodObject<{
+        supported: z.ZodBoolean;
+        unsupportedReason: z.ZodOptional<z.ZodString>;
+        ops: z.ZodRecord<z.ZodString, z.ZodEnum<["supported", "stub", "unsupported", "probe-inconclusive", "polyfill"]>>;
+        partialCoverage: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        partialCoverage: boolean;
+        unsupportedReason?: string | undefined;
+    }, {
+        supported: boolean;
+        ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+        unsupportedReason?: string | undefined;
+        partialCoverage?: boolean | undefined;
+    }>, "strip">>;
     polyfills: z.ZodObject<{
         emitted: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -269,10 +348,40 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     }>;
+    doctor: z.ZodOptional<z.ZodObject<{
+        available: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        available: boolean;
+    }, {
+        available: boolean;
+    }>>;
+    licenses: z.ZodOptional<z.ZodObject<{
+        available: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        available: boolean;
+    }, {
+        available: boolean;
+    }>>;
 }, "strip", z.ZodTypeAny, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            partialCoverage: boolean;
+            unsupportedReason?: string | undefined;
+        };
+    };
+    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
-    packageName: string;
     canonical: boolean;
     displayName: string;
     description: string;
@@ -291,15 +400,6 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         symbolAliases: Record<string, string>;
         targets: string[];
     };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
-            partialCoverage: boolean;
-            unsupportedReason?: string | undefined;
-        };
-        raw?: unknown;
-    };
     polyfills: {
         emitted: {
             id: string;
@@ -343,6 +443,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;
     libraryResolution?: {
@@ -353,9 +459,25 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         reexportedFrom?: string | undefined;
     } | undefined;
 }, {
+    hal: {
+        [x: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+        raw?: unknown;
+    } & {
+        [k: string]: {
+            supported: boolean;
+            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
+            unsupportedReason?: string | undefined;
+            partialCoverage?: boolean | undefined;
+        };
+    };
+    packageName: string;
     schemaVersion: 1;
     frameworkId: string;
-    packageName: string;
     displayName: string;
     description: string;
     implementationMode: "from-scratch" | "extends-canonical" | "extends-other";
@@ -373,15 +495,6 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         symbolAliases: Record<string, string>;
         targets: string[];
     };
-    hal: {
-        [x: string]: {
-            supported: boolean;
-            ops: Record<string, "stub" | "polyfill" | "supported" | "unsupported" | "probe-inconclusive">;
-            unsupportedReason?: string | undefined;
-            partialCoverage?: boolean | undefined;
-        };
-        raw?: unknown;
-    };
     polyfills: {
         emitted: {
             id: string;
@@ -425,6 +538,12 @@ export declare const FrameworkManifestSchema: z.ZodObject<{
         hardwareTestGroups: string[];
         halResolutionTests: string[];
     };
+    doctor?: {
+        available: boolean;
+    } | undefined;
+    licenses?: {
+        available: boolean;
+    } | undefined;
     canonical?: boolean | undefined;
     basedOn?: string | undefined;
     inheritsStrategyId?: string | undefined;

package/dist/api/shared/framework-manifest.js

@@ -11,10 +11,21 @@
 // cross-checks each claim against the loaded strategy/toolchain.
 // ---------------------------------------------------------------------------
 import { z } from 'zod';
+// Core HAL categories that EVERY framework MUST declare coverage for (the
+// universal embedded surface: digital/analog I/O, comms buses, timing, power,
+// watchdog). These keys are required in every manifest's `hal` block.
+//
+// Extended categories — `rmt`, `ble`, `preferences`, `random`, `fs`, `mqtt`,
+// `mdns`, `ota`, etc. — are OPTIONAL: a framework declares them only if it
+// lowers them. The HalCoverageSchema below uses `.catchall()` so declared
+// extended categories survive zod parsing (they used to be silently stripped,
+// which made esp32's ble/rmt/preferences manifest blocks dead data) and get
+// validated by the manifest validator like any core category. A framework that
+// does not lower an extended category simply omits it.
 const HAL_CATEGORIES = [
     'gpio', 'pwm', 'adc', 'dac', 'interrupts', 'tone', 'timing', 'power',
     'i2c', 'spi', 'uart', 'pulse', 'shift', 'board', 'wdt', 'wifi', 'http',
-    'display',
+    'mqtt', 'display',
 ];
 const OpStatus = z.enum(['supported', 'stub', 'unsupported', 'probe-inconclusive', 'polyfill']);
 const HalCategorySchema = z.object({
@@ -32,7 +43,15 @@ const HalCoverageSchema = z.object(Object.fromEntries(HAL_CATEGORIES.map((c) =>
     c === 'display' ? DisplayCategorySchema : HalCategorySchema,
 ]))).extend({
     raw: z.object({ supported: z.boolean() }).default({ supported: true }),
-});
+    // catchall: extended categories (rmt, ble, preferences, random, fs, mqtt,
+    // mdns, ota, ...) declared by a framework that lowers them. Without this,
+    // zod's default object parsing silently strips unknown keys, so a manifest's
+    // `ble:` / `rmt:` / `preferences:` / `random:` blocks never reached the
+    // validator or consumers. The catchall validates them with the same shape as
+    // core categories (HalCategorySchema) and preserves them on the parsed
+    // object. Frameworks that don't lower an extended category simply omit it.
+    // `raw` is excluded — it is the escape hatch, not a HAL category.
+}).catchall(HalCategorySchema);
 const EntrypointSchema = z.object({
     entrypointFunctionName: z.string(),
     requiresLoopFunction: z.boolean(),
@@ -75,6 +94,15 @@ const LibraryResolutionSchema = z.object({
     tryGenerateLibDecl: z.boolean(),
     reexportedFrom: z.string().optional(),
 });
+/**
+ * Capability block for an optional subcommand the framework may own (e.g.
+ * `cuttlefish doctor`, `cuttlefish licenses`). The manifest only declares
+ * availability; the framework's runtime `doctor` / `licenses` exports provide
+ * the implementation, and cuttlefish dispatches to them when present.
+ */
+const SubcommandCapabilitySchema = z.object({
+    available: z.boolean(),
+});
 const StdLibSupportSchema = z.object({
     hasVector: z.boolean(),
     hasString: z.boolean(),
@@ -116,6 +144,11 @@ export const FrameworkManifestSchema = z.object({
     typeEmission: TypeEmissionSchema,
     ambientTypes: z.array(z.string()),
     conformance: ConformanceSchema,
+    // Optional subcommand capabilities owned by the framework. When declared
+    // `{ available: true }`, the framework exports matching `doctor` / `licenses`
+    // functions that cuttlefish dispatches the corresponding CLI subcommands to.
+    doctor: SubcommandCapabilitySchema.optional(),
+    licenses: SubcommandCapabilitySchema.optional(),
 });
 /**
  * Authoritative map of HAL op kinds that are lowered via the polyfill system

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

@@ -1,5 +1,5 @@
 import type { DisplayHALOp } from "./display-op-ir.js";
-import type { ResolvedDisplay, TouchProfile, TouchAdapterCodegen } from "./display-profile.js";
+import type { DisplayProfile, ResolvedDisplay, TouchProfile, TouchAdapterCodegen } from "./display-profile.js";
 import type { DisplayAdapterCode } from "./display-adapter.js";
 export interface GraphicsCapacity {
     /** Max nodes the retained tree may hold on this target. */
@@ -18,14 +18,15 @@ export interface PlatformGraphicsStrategy {
         expression?: string;
     } | undefined;
     /**
-     * True if this strategy emits its own display adapters (AVR, ESP32). When
-     * false or undefined, generateDisplayAdapter() falls back to the built-in
-     * Adafruit registry — the Arduino path, unchanged.
+     * True if this strategy emits its own display adapters (e.g. framework-arduino
+     * owns the Adafruit_GFX drivers, framework-native owns SDL). When false or
+     * undefined, generateDisplayAdapter() falls back to cuttlefish's generic
+     * built-in adapter registry.
      */
     providesDisplayAdapter?(): boolean;
     /**
-     * Returns the adapter code for one display, or undefined to defer to the
-     * built-in Adafruit registry. Only called when providesDisplayAdapter()
+     * Returns the adapter code for one display, or undefined to defer to cuttlefish's
+     * built-in adapter registry. Only called when providesDisplayAdapter()
      * returns true.
      */
     resolveDisplayAdapter?(display: ResolvedDisplay): DisplayAdapterCode | undefined;
@@ -43,6 +44,14 @@ export interface PlatformGraphicsStrategy {
      * surface a clear compile-time error instead of emitting incompatible code.
      */
     resolveTouchAdapter?(touch: TouchProfile): TouchAdapterCodegen | undefined;
+    /**
+     * Optional hook returning this framework's named display-profile registry
+     * (profile name → DisplayProfile). When present, transpile.ts consults it to
+     * resolve `display.profile` config values instead of dynamically importing a
+     * framework module — so profile names resolve correctly per-framework.
+     * Returns undefined to fall back to the legacy dynamic-import path.
+     */
+    getProfileRegistry?(): Map<string, DisplayProfile>;
     /** Display driver ids this framework provides (e.g. new Set(["ili9341"])). */
     supportedDisplayDrivers(): ReadonlySet<string>;
     /** Target color format — drives transpile-time color resolution.