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

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

@@ -15,4 +15,132 @@
 // the MCU package's pin mapping. The `pin` field provides backward
 // compatibility as a legacy framework pin number.
 // ---------------------------------------------------------------------------
-export {};
+/**
+ * Runtime registry of every HAL operation discriminator, parallel to
+ * {@link DISPLAY_OPERATION_KINDS}. Lets tests and the manifest validator
+ * enumerate HAL op kinds without parsing types (which are erased at runtime).
+ * Keep in sync with {@link HALOpIR} above.
+ *
+ * Note: `display.*` ops are NOT listed here — they live in
+ * {@link DISPLAY_OPERATION_KINDS} in `display-op-ir.ts`. The manifest
+ * validator imports both and unions them when probing display ops.
+ */
+export const HAL_OPERATION_KINDS = [
+    // GPIO
+    'gpio.write', 'gpio.read', 'gpio.toggle', 'gpio.set_mode',
+    // PWM
+    'pwm.write', 'pwm.get_frequency', 'pwm.get_resolution',
+    // RMT
+    'rmt.tx_init', 'rmt.tx_write_bytes', 'rmt.tx_write_symbols',
+    'rmt.tx_wait_done', 'rmt.tx_deinit',
+    'rmt.rx_init', 'rmt.rx_on_received', 'rmt.rx_start',
+    'rmt.rx_stop', 'rmt.rx_read', 'rmt.rx_deinit',
+    // ADC
+    'adc.read', 'adc.get_resolution', 'adc.set_reference',
+    'adc.get_reference', 'adc.read_voltage',
+    // DAC
+    'dac.write',
+    // Interrupts
+    'interrupt.attach', 'interrupt.detach',
+    // Tone
+    'tone.play', 'tone.stop',
+    // Timing
+    'timing.delay', 'timing.delay_microseconds', 'timing.millis',
+    'timing.micros', 'timing.free_heap', 'timing.set_interval',
+    'timing.set_timeout', 'timing.clear_interval', 'timing.clear_timeout',
+    // Power
+    'power.deep_sleep', 'power.light_sleep', 'power.set_cpu_frequency', 'power.deep_sleep_pin',
+    // I2C
+    'i2c.begin', 'i2c.end', 'i2c.set_clock', 'i2c.begin_transmission',
+    'i2c.write', 'i2c.write_bytes', 'i2c.write_buffer', 'i2c.read_buffer',
+    'i2c.end_transmission', 'i2c.request_from', 'i2c.available', 'i2c.read',
+    'i2c.recover',
+    // SPI
+    'spi.begin', 'spi.end', 'spi.transfer', 'spi.begin_transaction',
+    'spi.end_transaction', 'spi.set_mode', 'spi.set_bit_order',
+    'spi.cs_low', 'spi.cs_high', 'spi.read_buffer',
+    // UART
+    'uart.begin', 'uart.end', 'uart.print', 'uart.println', 'uart.printf',
+    'uart.write', 'uart.read', 'uart.peek', 'uart.available', 'uart.flush',
+    // Pulse
+    'pulse.in', 'pulse.in_long',
+    // Shift
+    'shift.out', 'shift.in',
+    // Board
+    'board.resolve',
+    // Watchdog timer
+    'wdt.enable', 'wdt.reset', 'wdt.disable',
+    // Snprintf
+    'snprintf.emit',
+    // WiFi
+    'wifi.connect', 'wifi.connect_start', 'wifi.disconnect', 'wifi.status',
+    'wifi.is_connected', 'wifi.local_ip', 'wifi.rssi', 'wifi.mac',
+    'wifi.set_hostname', 'wifi.set_static_ip', 'wifi.set_auto_reconnect',
+    'wifi.set_power_save', 'wifi.set_tx_power', 'wifi.on_event',
+    'wifi.ap_start', 'wifi.ap_stop', 'wifi.ap_client_count', 'wifi.ap_ip',
+    'wifi.ap_set_channel', 'wifi.ap_set_hidden', 'wifi.ap_set_max_clients',
+    'wifi.scan', 'wifi.scan_start', 'wifi.scan_done', 'wifi.scan_count',
+    'wifi.scan_ssid', 'wifi.scan_rssi', 'wifi.scan_encryption',
+    'wifi.scan_channel', 'wifi.save_credentials', 'wifi.connect_saved',
+    'wifi.clear_credentials', 'wifi.wait_connected', 'wifi.wait_disconnected',
+    // HTTP
+    'http.begin', 'http.reset', 'http.set_header', 'http.set_timeout',
+    'http.set_max_body', 'http.set_body', 'http.set_insecure',
+    'http.set_ca_cert', 'http.send', 'http.send_start', 'http.done',
+    'http.status', 'http.ok', 'http.body', 'http.content_length',
+    'http.response_header',
+    // Worker offload (generalized request-in / poll-out over a worker pool)
+    'worker.submit', 'worker.done',
+    // BLE (NimBLE GATT peripheral)
+    'ble.server_begin', 'ble.advertise_start', 'ble.advertise_stop',
+    'ble.add_service', 'ble.add_char',
+    'ble.on_read', 'ble.on_write', 'ble.on_connect', 'ble.on_disconnect', 'ble.notify',
+    'ble.is_connected', 'ble.client_count', 'ble.set_name',
+    'ble.until_connected', 'ble.until_connected_start',
+    'ble.set_tx_power', 'ble.status',
+    // Preferences (NVS)
+    'preferences.begin', 'preferences.end', 'preferences.clear', 'preferences.remove',
+    'preferences.put_int', 'preferences.get_int',
+    'preferences.put_uint', 'preferences.get_uint',
+    'preferences.put_bool', 'preferences.get_bool',
+    'preferences.put_float', 'preferences.get_float',
+    'preferences.put_string', 'preferences.get_string',
+    // Random
+    'random.int', 'random.range', 'random.seed',
+    // FS (filesystem)
+    'fs.begin', 'fs.read_text', 'fs.write_text', 'fs.exists', 'fs.remove',
+    // mDNS
+    'mdns.start', 'mdns.set_hostname', 'mdns.add_service', 'mdns.announce', 'mdns.stop',
+    // MQTT
+    'mqtt.connect', 'mqtt.on_message', 'mqtt.subscribe', 'mqtt.publish', 'mqtt.connected', 'mqtt.disconnect',
+    // OTA
+    'ota.from_url', 'ota.begin', 'ota.write', 'ota.apply',
+    // Temperature
+    'temp.read',
+    // Hardware timer
+    'hwtimer.set_frequency', 'hwtimer.on_overflow', 'hwtimer.start', 'hwtimer.stop',
+    // Capacitive touch pins
+    'capacitive.read',
+    // I2S / digital audio (unimplemented — declared unsupported by all frameworks)
+    'i2s.init', 'i2s.write', 'i2s.read',
+    // TWAI / CAN (unimplemented)
+    'twai.init', 'twai.send', 'twai.receive',
+    // USB OTG / USB-Serial-JTAG (unimplemented)
+    'usb.init', 'usb.write', 'usb.read',
+    // Ethernet MAC (unimplemented)
+    'eth.init', 'eth.start', 'eth.is_linked',
+    // ESPNOW (unimplemented)
+    'espnow.init', 'espnow.add_peer', 'espnow.send', 'espnow.on_receive',
+    // Hardware crypto (unimplemented)
+    'crypto.aes_encrypt', 'crypto.sha256', 'crypto.hmac',
+    // Pulse counter (unimplemented)
+    'pcnt.init', 'pcnt.count', 'pcnt.clear',
+    // Motor control PWM (unimplemented)
+    'mcpwm.init', 'mcpwm.set_duty', 'mcpwm.start',
+    // Raw passthrough
+    'raw',
+];
+// Compile-time exhaustiveness check: every HAL_OPERATION_KINDS entry must
+// be a valid HALOpIR["operation"]. If you add an op to the const but not the
+// union (or vice versa), this assignment fails to type-check.
+const _halOpKindsExhaustive = [...HAL_OPERATION_KINDS];

package/dist/api/shared/index.d.ts

@@ -1,13 +1,18 @@
 export type { Diagnostic, PlatformContext, SourceSpan, TargetProfile } from './types.js';
+export type { GeneratedSourceMap, SourceMapEntry } from '../../types.js';
 export type { CppTypeIR, CppTypeKind, CppPrimitiveName, CppFormatKind, } from './cpp-type-ir.js';
 export { parseCppType, renderCppType, splitTemplateArgs, isPointer, isReference, isContainer, isVector, isMap, isSet, isTuple, isVariant, isStdFunction, isStaticArray, isCArray, isStringLike, isPrimitive, bareType, elementOf, formatKindOf, CppTypeIR as cppTypeIRBuilder, parsedIsPointer, parsedIsStringLike, parsedIsPrimitive, parsedIsContainer, parsedIsVector, parsedIsMap, parsedIsSet, parsedIsTuple, parsedIsVariant, parsedIsStaticArray, parsedIsStdString, parsedElementOf, parsedElementString, parsedBareString, parsedBareType, collectNamedTypes, parsedCollectNamedTypes, needsCStrForStringLike, parsedIsPlainStructType, } from './cpp-type-ir.js';
 export type { ExpressionIR, StatementIR, ProgramIR, ImportIR, ReExportIR, CallExpressionIR, SuperCallIR, VariableDeclarationIR, AssignmentIR, UpdateIR, ReturnIR, WhileIR, IfIR, ForIR, ForOfIR, ForInIR, BreakIR, ContinueIR, DoWhileIR, SwitchIR, CaseIR, TryIR, ThrowIR, LabeledIR, BlockIR, HALOpStatementIR, FunctionIR, StructDefIR, EnumIR, ClassFieldIR, ClassConstructorIR, ClassMethodIR, ClassGetterIR, ClassSetterIR, ClassIR, InterfaceIR, TypeAliasIR, NamespaceIR, PeripheralUsageIR, RegisterBitFieldIR, RegisterClassIR, ParameterIR, CppType, } from './ir.js';
 export type { HALOpIR, HALOperationKind, } from './hal-op-ir.js';
+export { HAL_OPERATION_KINDS } from './hal-op-ir.js';
 export type { DisplayInitOp, DisplayFillRectOp, DisplayDrawTextOp, DisplayDrawRectOp, DisplayFlushOp, DisplayHALOp, } from './display-op-ir.js';
 export { DISPLAY_OPERATION_KINDS } from './display-op-ir.js';
 export type { PlatformGraphicsStrategy, GraphicsCapacity } from './graphics-strategy.js';
-export type { DisplayProfile, DisplayConfig, DisplaySize, TouchProfile, TouchLibrary, ResolvedDisplay } from './display-profile.js';
-export { effectiveDisplaySize, normalizeDisplayRotation, resolveDisplayProfile, resolveScrollConfig, DEFAULT_SCROLL_CANVAS_BUDGET_BYTES } from './display-profile.js';
+export type { DisplayProfile, DisplayConfig, DisplaySize, TouchProfile, TouchLibrary, TouchAdapterCodegen, ResolvedDisplay } from './display-profile.js';
+export { effectiveDisplaySize, normalizeDisplayRotation, resolveDisplayProfile, resolveScrollConfig } from './display-profile.js';
+export { GLCDFONT_BYTES, renderGlcdfontArray } from './glcdfont.js';
+export type { DisplayAdapterCode, DisplayAdapterGenerator } from './display-adapter.js';
+export { resolveNativeDisplayOp } from './native-display-op-resolver.js';
 export type { DisplayCapabilities, DisplayFeatureFlags, NativeFormat, RefreshModel, PartialRefreshScope, } from './display-capabilities.js';
 export { defaultTftCapabilities, deriveCapabilities } from './display-capabilities.js';
 export type { BoardConstants } from './board-resolver.js';
@@ -21,6 +26,19 @@ export { POLYFILL_HELPER_MAP, filterPolyfillHelpers } from './polyfill-helper-re
 export { STRING_METHODS, STRING_METHOD_NAMES, applyStringMethodRewrites } from './string-method-registry.js';
 export type { StringMethodSpec, StringMethodArgForm } from './string-method-registry.js';
 export { isStringEnum } from './ir-declarations.js';
+export { mapProgramStatements } from '../../ir/utils/map-statements.js';
+export { programUsesSafety } from '../../emit/emitters/setup.js';
 export type { AsyncRuntimeConfig } from './async-types.js';
 export { generatePromiseRuntime } from './promise-runtime.js';
 export { generateStaticAsyncRuntime } from './async-runtime-static.js';
+export { generateCoopScheduler, buildCoopSchedInjection } from './coop-scheduler.js';
+export type { CoopWorkUnit, CoopSchedOptions } from './coop-scheduler.js';
+export { generateWorkerRuntime, lowerWorkerOp } from './worker-runtime.js';
+export type { WorkerRuntimeOptions, WorkerBacking } from './worker-runtime.js';
+export { buildWorkerRuntimePolyfill } from './worker-runtime-polyfill.js';
+export { FrameworkManifestSchema, defineFrameworkManifest, HAL_CATEGORIES, POLYFILL_BACKED_OPS, } from './framework-manifest.js';
+export type { FrameworkManifest, HalCategory, } from './framework-manifest.js';
+export { KNOWN_FRAMEWORK_PACKAGES, loadFrameworkManifest, } from './framework-manifest-registry.js';
+export type { KnownFrameworkPackage } from './framework-manifest-registry.js';
+export { validateFrameworkManifest } from './validate-framework-manifest.js';
+export type { ManifestValidationContext, ManifestValidationResult, ManifestValidationError, ManifestValidationWarning, } from './validate-framework-manifest.js';

package/dist/api/shared/index.js

@@ -4,8 +4,16 @@
 // Re-exports all shared types for use by CLI and framework packages.
 // ---------------------------------------------------------------------------
 export { parseCppType, renderCppType, splitTemplateArgs, isPointer, isReference, isContainer, isVector, isMap, isSet, isTuple, isVariant, isStdFunction, isStaticArray, isCArray, isStringLike, isPrimitive, bareType, elementOf, formatKindOf, CppTypeIR as cppTypeIRBuilder, parsedIsPointer, parsedIsStringLike, parsedIsPrimitive, parsedIsContainer, parsedIsVector, parsedIsMap, parsedIsSet, parsedIsTuple, parsedIsVariant, parsedIsStaticArray, parsedIsStdString, parsedElementOf, parsedElementString, parsedBareString, parsedBareType, collectNamedTypes, parsedCollectNamedTypes, needsCStrForStringLike, parsedIsPlainStructType, } from './cpp-type-ir.js';
+export { HAL_OPERATION_KINDS } from './hal-op-ir.js';
 export { DISPLAY_OPERATION_KINDS } from './display-op-ir.js';
-export { effectiveDisplaySize, normalizeDisplayRotation, resolveDisplayProfile, resolveScrollConfig, DEFAULT_SCROLL_CANVAS_BUDGET_BYTES } from './display-profile.js';
+export { effectiveDisplaySize, normalizeDisplayRotation, resolveDisplayProfile, resolveScrollConfig } from './display-profile.js';
+// Shared 5x7 glcdfont table (Adafruit public-domain source). Consumed by
+// the SDL preview adapter and the native CuttlefishGFX runtime-header slice.
+export { GLCDFONT_BYTES, renderGlcdfontArray } from './glcdfont.js';
+// Native display-op resolver — lowers display.* HAL ops into calls against
+// the adapter surface (display_init / display_targetFillRect / etc.). Used
+// by NativeAVRStrategy and Esp32Strategy's resolveDisplayOp overrides.
+export { resolveNativeDisplayOp } from './native-display-op-resolver.js';
 export { defaultTftCapabilities, deriveCapabilities } from './display-capabilities.js';
 export { getStdLibSupport, DEFAULT_STDLIB_SUPPORT } from './polyfill-types.js';
 export { parseCompileErrors, collectCppFiles } from './toolchain-types.js';
@@ -15,7 +23,23 @@ export { POLYFILL_HELPER_MAP, filterPolyfillHelpers } from './polyfill-helper-re
 export { STRING_METHODS, STRING_METHOD_NAMES, applyStringMethodRewrites } from './string-method-registry.js';
 // Runtime helpers
 export { isStringEnum } from './ir-declarations.js';
+// IR transform helpers (used by the optional @typecad/safety package's pass)
+export { mapProgramStatements } from '../../ir/utils/map-statements.js';
+// Safety-use detector (used by framework strategies to gate __tc_gpio_read
+// shim emission — mirrors programUsesWdt for the watchdog).
+export { programUsesSafety } from '../../emit/emitters/setup.js';
 // Promise runtime generator (heap-based: ESP32/ESP8266/rp2040/samd/…)
 export { generatePromiseRuntime } from './promise-runtime.js';
 // Heap-free static async runtime generator (AVR / megaavr / no-<vector> targets)
 export { generateStaticAsyncRuntime } from './async-runtime-static.js';
+// No-STL cooperative scheduler (priority + time-budget) — Zephyr-friendly
+export { generateCoopScheduler, buildCoopSchedInjection } from './coop-scheduler.js';
+// Worker offload runtime (generalized request-in / poll-out)
+export { generateWorkerRuntime, lowerWorkerOp } from './worker-runtime.js';
+export { buildWorkerRuntimePolyfill } from './worker-runtime-polyfill.js';
+// Framework manifest schema + helper
+export { FrameworkManifestSchema, defineFrameworkManifest, HAL_CATEGORIES, POLYFILL_BACKED_OPS, } from './framework-manifest.js';
+// Framework manifest discovery
+export { KNOWN_FRAMEWORK_PACKAGES, loadFrameworkManifest, } from './framework-manifest-registry.js';
+// Framework manifest validator
+export { validateFrameworkManifest } from './validate-framework-manifest.js';

package/dist/api/shared/ir-core.d.ts

@@ -134,7 +134,11 @@ export type ExpressionIR = {
     isPointer?: boolean;
     restElementType?: string;
     cppType?: string;
+    receiverExpr?: ExpressionIR;
+    methodName?: string;
 }
+/** A receiverless call: `Name(args)` (free function or constructor). Method-on-receiver calls lower as "method-call"; this is the receiverless form, e.g. `SafeInt(x)`. */
+ | CallExpressionIR
 /** Array element access: `object[index]`. */
  | {
     kind: "element-access";

package/dist/api/shared/ir-declarations.d.ts

@@ -19,6 +19,10 @@ export interface FunctionIR {
     isGenerator?: boolean;
     /** True when the function is exported (has `export` keyword). */
     isExported?: boolean;
+    /** Decorators applied to this function (e.g. ["asilD"]). Mirrors
+     *  ClassIR.decorators. Used by the safety hook's analyzeIR to gate
+     *  ISO 26262 rule enforcement by ASIL level. */
+    decorators?: string[];
 }
 export interface StructDefIR {
     name: string;
@@ -80,6 +84,8 @@ export interface ClassMethodIR {
     typeParameters?: string[];
     /** True when this is a generator method. */
     isGenerator?: boolean;
+    /** Decorators applied to this method (e.g. ["asilD"]). */
+    decorators?: string[];
 }
 export interface ClassGetterIR {
     name: string;

package/dist/api/shared/native-display-op-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { DisplayHALOp } from "./display-op-ir.js";
+/**
+ * Resolve a display HAL op to a call into the native adapter surface
+ * (display_init / display_targetFillRect / etc.). Returns undefined for ops
+ * this resolver does not handle.
+ */
+export declare function resolveNativeDisplayOp(op: DisplayHALOp): {
+    code?: string;
+    expression?: string;
+} | undefined;

package/dist/api/shared/native-display-op-resolver.js

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Shared display-op resolver for native (non-Arduino) display strategies.
+//
+// Both NativeAVRStrategy and Esp32Strategy override resolveDisplayOp to return
+// undefined for display.* ops (the design intent: display ops are resolved
+// through the adapter path, not per-op HAL lowering). But the HAL lowering
+// layer still calls resolveDisplayOp for every display.* op emitted by user
+// code (display.init via ui.mount, display.fill_rect/draw_rect/draw_text via
+// direct HAL calls, display.flush per frame).
+//
+// Those ops need to lower to CALLS INTO the adapter surface — the same
+// display_init() / display_targetFillRect() / etc. functions the Adafruit
+// path calls. The native adapters emit those functions with identical
+// signatures, so the lowering is identical across native strategies.
+//
+// This module provides that lowering. Each native strategy's resolveDisplayOp
+// delegates here instead of returning undefined.
+// ---------------------------------------------------------------------------
+/** Render a color value as a C++ hex literal (e.g. 0x07e0) for readable RGB565. */
+function hexColor(c) {
+    return `0x${c.toString(16)}`;
+}
+/**
+ * Resolve a display HAL op to a call into the native adapter surface
+ * (display_init / display_targetFillRect / etc.). Returns undefined for ops
+ * this resolver does not handle.
+ */
+export function resolveNativeDisplayOp(op) {
+    switch (op.operation) {
+        case "display.init":
+            // The adapter's display_init() does bus setup, panel init sequence,
+            // rotation, and the initial fillScreen. No backlight GPIO parameter
+            // on native paths — the Adafruit-style backlight pin is handled in
+            // the mount config if needed.
+            return { code: `display_init();` };
+        case "display.fill_rect":
+            // Delegate to the polymorphic target draw so the same call works
+            // whether the active target is the panel or an offscreen canvas.
+            return {
+                code: `display_targetFillRect(display_defaultTarget(), ${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+            };
+        case "display.draw_rect":
+            return {
+                code: `display_targetDrawRect(display_defaultTarget(), ${op.x}, ${op.y}, ${op.w}, ${op.h}, ${hexColor(op.color)});`,
+            };
+        case "display.draw_text":
+            return {
+                code: [
+                    `display_targetSetCursor(display_defaultTarget(), ${op.x}, ${op.y});`,
+                    `display_targetSetTextColor(display_defaultTarget(), ${hexColor(op.color)});`,
+                    `display_targetSetTextSize(display_defaultTarget(), 2);`,
+                    `display_targetPrint(display_defaultTarget(), ${JSON.stringify(op.text)});`,
+                ].join("\n"),
+            };
+        case "display.flush":
+            // Direct-mode panels (ILI9341, ST7796S) draw immediately — no flush.
+            // Buffered panels (SSD1309) flush via display_partial_refresh, which
+            // the runtime calls through display_partial_refresh directly (not via
+            // HAL op) at frame end.
+            return { code: `/* flush: ${op.rects.length} rect(s) — native display */` };
+        default:
+            return undefined;
+    }
+}

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

@@ -108,8 +108,13 @@ export interface PlatformTypeStrategy {
      * when the enum members map directly to platform preprocessor macros.
      */
     passthroughEnumNames?(): ReadonlySet<string>;
-    /** Default numeric type for the platform (e.g. "int" on hosted, "int32_t" on embedded). */
-    defaultNumericType(): string;
+    /**
+     * Default numeric type for the platform (e.g. "int" on hosted, "int32_t" on embedded).
+     * Optional compliance context: when A3-9-1 is enforced, returns a fixed-width type.
+     */
+    defaultNumericType(compliance?: {
+        isBanned(ruleId: string): boolean;
+    }): string;
     /**
      * Inform the strategy which enums have values exceeding the signed 16-bit range.
      * The strategy can use this to choose an appropriate underlying type.
@@ -279,6 +284,15 @@ export interface PlatformSafetyStrategy {
      * StaticArray wrapper's methods or the std::vector/__tc_* helper form.
      */
     promotesArrayLiteralsToStaticArray?(): boolean;
+    /**
+     * Whether this target runs on a preemptive RTOS where blocking calls
+     * (e.g. vTaskDelay) yield the CPU to other tasks. When true, delay() inside
+     * loop() does NOT freeze the async queue or UI rendering — the timing
+     * validator suppresses the 'blocking-delay-in-loop' warning for plain delay().
+     * Defaults to false (Arduino/AVR use cooperative scheduling where delay
+     * freezes everything). ESP-IDF (FreeRTOS) returns true.
+     */
+    isRtosTarget?(): boolean;
 }
 export interface PlatformBuildStrategy {
     /** Queue capacity for the async microtask ring buffer. */
@@ -298,12 +312,32 @@ export interface PlatformBuildStrategy {
     /** Standard library support for the given architecture. */
     getStdLibSupport(architecture?: string): StdLibSupport;
 }
+/**
+ * Coarse C++ type category carried per debug variable, so printf-based codegens
+ * (ESP-IDF) can pick the right format specifier. Inferred by the debug
+ * preprocessor from AST shape (no TypeChecker); `unknown` is the fallback.
+ * Mirrors `DebugCppType` in cuttlefish/src/debug/types.ts — duplicated here to
+ * avoid a cross-module import from the api surface.
+ */
+export type DebugCppType = 'bool' | 'int' | 'long' | 'float' | 'string' | 'unknown';
 /**
  * Debug code generation sub-interface.
  * Frameworks implement these to provide platform-specific debug output
  * (e.g., Serial.println on embedded, std::cout on hosted targets).
  */
 export interface PlatformDebugStrategy {
+    /**
+     * Debug mode for the given build target. Controls whether `--debug` emits
+     * GDB-oriented output (`#line` directives + debug config artifacts, value
+     * `'gdb'`) or the legacy printf/Serial instrumentation (`'printf'`).
+     *
+     * Frameworks that support native source-level debugging for a chip return
+     * `'gdb'` for that target; everything else inherits the `'printf'` default
+     * and the existing instrumentation path is used unchanged.
+     *
+     * @param target the frameworkData.buildTarget value (e.g. 'esp32s3')
+     */
+    debugMode?(target?: string): 'gdb' | 'printf';
     /** Generate initialization code for the debug subsystem. */
     generateDebugInitCode?(): string[];
     /** Generate code for a breakpoint with optional condition and variable dump. */
@@ -314,8 +348,16 @@ export interface PlatformDebugStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: DebugCppType;
         }>;
         normalizedCondition?: string;
+        /**
+         * Stable per-file ID assigned by the preprocessor. When present, the
+         * codegen emits a `static bool __tc_bp_disabled_<id>` flag and wraps the
+         * halt in `if (!__tc_bp_disabled_<id>)`, so the user can skip/disable this
+         * one breakpoint for the rest of the run (the 's' key sets the flag).
+         */
+        breakpointId?: number;
     }): string[];
     /** Generate code for a logpoint with interpolated message parts. */
     generateDebugLogpointCode?(params: {
@@ -328,6 +370,7 @@ export interface PlatformDebugStrategy {
         variables: Array<{
             name: string;
             isFunction?: boolean;
+            cppType?: DebugCppType;
         }>;
     }): string[];
 }
@@ -362,6 +405,27 @@ export interface PlatformAsyncStrategy {
         preIteration: string;
         postIteration: string;
     } | null;
+    /**
+     * C++ statements that spawn the worker for slot `handleId`, running
+     * `fn(arg)`. Emitted as the body of __tc_worker_submit. Return undefined
+     * to declare worker offload unsupported on this framework.
+     *
+     * The shared runtime has already recorded `waiter`/set `done=false` before
+     * this runs; the hook need only spawn. `fn` and `arg` are C++ expressions
+     * (a function pointer and a void*).
+     */
+    workerSpawnLines?(handleId: number, fn: string, arg: string): string[] | undefined;
+    /**
+     * C++ expression the worker calls AFTER completing its work and writing its
+     * outputs, to signal completion to the waiter. Emitted inside the worker
+     * trampoline. Must issue a memory barrier. Return undefined if unsupported.
+     */
+    workerSignalDoneExpr?(handleId: number): string | undefined;
+    /**
+     * C++ boolean expression polled by __tc_worker_done to test completion.
+     * Must observe the signal's memory barrier. Return undefined if unsupported.
+     */
+    workerIsDoneExpr?(handleId: number): string | undefined;
 }
 /**
  * Strategy for resolving semantic HAL operations to framework-specific C++.
@@ -394,6 +458,53 @@ export interface PlatformHALStrategy {
      * Default true (preserves existing behavior for hardware strategies).
      */
     modelsGpio?(): boolean;
+    /**
+     * C++ expression that reads the digital level of a pin (HIGH/LOW).
+     * ArduinoStrategy returns `digitalRead(${pin})`. GenericStrategy returns a
+     * documented no-op stub (no GPIO on host).
+     */
+    readDigitalPin?(pin: string): string;
+    /**
+     * C++ expression that reads a raw analog value from an ADC pin.
+     * ArduinoStrategy returns `analogRead(${pin})`. GenericStrategy stubs.
+     */
+    readAnalogPin?(pin: string): string;
+    /**
+     * C++ statement that writes a digital level to a pin.
+     * ArduinoStrategy returns `digitalWrite(${pin}, ${val})`. Cuttlefish does not
+     * call this in the current emit path (display reset moves to the framework),
+     * but it is part of the atomic surface for completeness/future use.
+     */
+    writeDigitalPin?(pin: string, val: string): string;
+    /**
+     * C++ statement that configures a pin's mode.
+     * ArduinoStrategy returns `pinMode(${pin}, ${mode})`.
+     */
+    setPinMode?(pin: string, mode: string): string;
+    /**
+     * C++ statement that blocks for a number of milliseconds.
+     * ArduinoStrategy returns `delay(${ms})`.
+     */
+    delayMs?(ms: string): string;
+    /**
+     * C++ statement that blocks for a number of microseconds.
+     * ArduinoStrategy returns `delayMicroseconds(${us})`.
+     */
+    delayMicroseconds?(us: string): string;
+    /**
+     * The full set of HAL call names this framework's emitted code may contain
+     * (digitalRead, analogRead, Serial, tone, millis, …). Used to recognize HAL
+     * calls in rendered C++ text where no structured HAL-IR node is available.
+     */
+    halCallNames?(): ReadonlySet<string>;
+    /** Membership test against {@link halCallNames}. Default false on generic. */
+    isHalCall?(name: string): boolean;
+    /**
+     * The subset of {@link halCallNames} that return an analog-read integer
+     * value (e.g. analogRead). Used by adc-range-validation to detect ADC reads
+     * in lowered raw text.
+     */
+    analogReadCallNames?(): ReadonlySet<string>;
 }
 /**
  * Full platform strategy composed from focused sub-interfaces.

package/dist/api/shared/polyfill-helper-registry.js

@@ -62,6 +62,22 @@ export const POLYFILL_HELPER_MAP = {
     // JSON helpers
     '__tc_jsonStringify(': ['__tc_jsonStringify'],
     '__tc_jsonParse(': ['__tc_jsonParse'],
+    // Safety helpers — emitted by @typecad/safety's polyfills as global-scope
+    // __tc_safety_* free functions (the polyfill-helper-registry extractor
+    // expects __tc_* immediately followed by `(`, so namespaced names would be
+    // missed). The call-pattern keys are the substrings program analysis scans
+    // source for; the values are the __tc_safety_* names that
+    // filterPolyfillHelpers matches in helperFunctions text.
+    //
+    // Two key forms per helper: the user-facing safe.* source spelling (which
+    // program analysis sees in raw IR before lowering) and the lowered
+    // __tc_safety_* spelling (which appears after the safety call-statement
+    // transformer emits hal-op resolution text). Both map to the same helper.
+    'safe.read(': ['__tc_safety_read_safe'],
+    'safe.write(': ['__tc_safety_write_verify'],
+    '__tc_safety_record_pin_mode(': ['__tc_safety_record_pin_mode'],
+    '__tc_safety_read_safe(': ['__tc_safety_read_safe'],
+    '__tc_safety_write_verify(': ['__tc_safety_write_verify'],
 };
 function extractHelperFunctionNames(funcDef) {
     const matches = funcDef.matchAll(/\b(__tc_[A-Za-z0-9_]+)\s*\(/g);
@@ -82,5 +98,6 @@ export function filterPolyfillHelpers(polyfills, usedHelpers) {
         }),
     })).filter(polyfill => polyfill.helperFunctions.length > 0 ||
         polyfill.forwardDeclarations.length > 0 ||
-        polyfill.helperStructs.length > 0);
+        polyfill.helperStructs.length > 0 ||
+        polyfill.shimMacros.length > 0);
 }

package/dist/api/shared/promise-runtime.d.ts

@@ -7,4 +7,4 @@
  * @param includeWaitForPinEdge Whether to include the `waitForPinEdge` stub
  *   (used by Arduino targets).
  */
-export declare function generatePromiseRuntime(queueCapacity: number, includeWaitForPinEdge?: boolean): string;
+export declare function generatePromiseRuntime(queueCapacity: number, includeWaitForPinEdge?: boolean, strategy?: import("./platform-strategy.js").PlatformStrategy): string;