@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.14

package/dist/library/validate.js

@@ -0,0 +1,175 @@
+// ---------------------------------------------------------------------------
+// `cuttlefish library validate` — the standalone library-package validator.
+//
+// Before this, manifest errors only surfaced at import time inside a
+// transpile. This runs the same checks (and more) on a package directory:
+// manifest schema, file existence, include/gateToken consistency, npm
+// keyword consistency, and an AUTOSAR --strict pass over the shim bytes —
+// the same self-check the generated application runs over them.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { ComplianceContext, runSelfCheck } from "../emit/compliance/index.js";
+import { LIBRARY_MARKER_KEYWORD, libraryCategory } from "./catalog.js";
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function validateLibraryPackage(dir) {
+    const errors = [];
+    const warnings = [];
+    const root = path.resolve(dir);
+    const fail = (message) => {
+        errors.push(message);
+    };
+    // ── Manifest ───────────────────────────────────────────────────────────
+    const manifestPath = path.join(root, "cuttlefish.library.json");
+    let manifest;
+    if (!fs.existsSync(manifestPath)) {
+        fail("cuttlefish.library.json not found — is this a library package directory?");
+    }
+    else {
+        try {
+            manifest = readJson(manifestPath);
+        }
+        catch (e) {
+            fail(`cuttlefish.library.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (manifest) {
+        for (const field of ["id", "module", "framework", "include", "gateToken"]) {
+            if (typeof manifest[field] !== "string" || manifest[field].length === 0) {
+                fail(`Manifest field '${field}' must be a non-empty string.`);
+            }
+        }
+        if (!Array.isArray(manifest.shims) || manifest.shims.length === 0) {
+            fail("Manifest 'shims' must be a non-empty array.");
+        }
+        const include = typeof manifest.include === "string" ? manifest.include : "";
+        const gateToken = typeof manifest.gateToken === "string" ? manifest.gateToken : "";
+        if (include.length > 0 && gateToken.length > 0 && !include.includes(gateToken)) {
+            fail(`The gate token '${gateToken}' does not appear in the include '${include}' — ` +
+                `the include line is the only guaranteed emission, so contributions would never gate on.`);
+        }
+        // ── Shim files ───────────────────────────────────────────────────────
+        if (Array.isArray(manifest.shims)) {
+            for (const entry of manifest.shims) {
+                if (typeof entry !== "object" ||
+                    entry === null ||
+                    typeof entry.path !== "string" ||
+                    typeof entry.outName !== "string") {
+                    fail("Every 'shims' entry needs string 'path' and 'outName' fields.");
+                    continue;
+                }
+                const shimPath = path.join(root, entry.path);
+                if (!fs.existsSync(shimPath)) {
+                    fail(`Shim file listed in the manifest is missing: ${entry.path}`);
+                }
+            }
+        }
+        // ── Overlay fragment ─────────────────────────────────────────────────
+        if (typeof manifest.overlay === "string" && manifest.overlay.length > 0) {
+            const overlayPath = path.join(root, manifest.overlay);
+            if (!fs.existsSync(overlayPath)) {
+                fail(`Overlay fragment listed in the manifest is missing: ${manifest.overlay}`);
+            }
+        }
+    }
+    // ── package.json consistency ───────────────────────────────────────────
+    const pkgJsonPath = path.join(root, "package.json");
+    let pkgName;
+    let pkgKeywords = [];
+    if (!fs.existsSync(pkgJsonPath)) {
+        warnings.push("No package.json — nothing published, so keyword checks are skipped.");
+    }
+    else {
+        try {
+            const pkg = readJson(pkgJsonPath);
+            if (typeof pkg.name === "string") {
+                pkgName = pkg.name;
+            }
+            if (Array.isArray(pkg.keywords)) {
+                pkgKeywords = pkg.keywords.filter((k) => typeof k === "string");
+            }
+            if (Array.isArray(pkg.files) && !pkg.files.includes("cuttlefish.library.json")) {
+                fail("package.json 'files' must include 'cuttlefish.library.json' or the manifest will not ship.");
+            }
+        }
+        catch (e) {
+            fail(`package.json is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (pkgKeywords.length > 0 && !pkgKeywords.map((k) => k.toLowerCase()).includes(LIBRARY_MARKER_KEYWORD)) {
+        fail(`package.json keywords must include the marker '${LIBRARY_MARKER_KEYWORD}' — it is what library search scans for.`);
+    }
+    const categoryKeywords = pkgKeywords.filter((k) => k.startsWith("cuttlefish-") && k !== LIBRARY_MARKER_KEYWORD);
+    if (pkgKeywords.length > 0 && categoryKeywords.length === 0) {
+        warnings.push(`No category keyword in package.json — add one of ${LIBRARY_MARKER_KEYWORD}'s siblings (e.g. cuttlefish-led) so the library is browsable by category.`);
+    }
+    for (const kw of categoryKeywords) {
+        const id = kw.slice("cuttlefish-".length);
+        if (!libraryCategory(id)) {
+            warnings.push(`Keyword '${kw}' is not a known category keyword (cuttlefish-<id>).`);
+        }
+    }
+    if (categoryKeywords.length > 1) {
+        warnings.push(`Multiple category keywords (${categoryKeywords.join(", ")}) — search results show the first taxonomy match only.`);
+    }
+    if (manifest && pkgName !== undefined && typeof manifest.module === "string" && manifest.module !== pkgName) {
+        fail(`Manifest 'module' (${manifest.module}) must equal the package.json name (${pkgName}) — ` +
+            `the import specifier users write resolves against the package name.`);
+    }
+    // ── AUTOSAR strict over the shim bytes ─────────────────────────────────
+    const autosarFindings = [];
+    if (manifest && Array.isArray(manifest.shims)) {
+        const headerLines = [];
+        const sourceLines = [];
+        let anyReadable = false;
+        for (const entry of manifest.shims) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const rel = entry.path;
+            if (typeof rel !== "string")
+                continue;
+            const abs = path.join(root, rel);
+            if (!fs.existsSync(abs))
+                continue;
+            anyReadable = true;
+            const content = fs.readFileSync(abs, "utf8").split("\n");
+            if (abs.endsWith(".h") || abs.endsWith(".hpp")) {
+                headerLines.push(...content, "");
+            }
+            else {
+                sourceLines.push(...content, "");
+            }
+        }
+        if (anyReadable) {
+            const ctx = new ComplianceContext("strict");
+            autosarFindings.push(...runSelfCheck(ctx, sourceLines, headerLines));
+        }
+    }
+    for (const finding of autosarFindings) {
+        fail(`AUTOSAR ${finding.ruleId} (${finding.file} line ${finding.line}): ${finding.snippet}`);
+    }
+    return {
+        valid: errors.length === 0,
+        dir: root,
+        errors,
+        warnings,
+        autosarFindings,
+    };
+}
+/** Render the human-readable report. Returns the process exit code (0/1). */
+export function printValidationReport(report) {
+    for (const warning of report.warnings) {
+        console.log(`  ! ${warning}`);
+    }
+    for (const error of report.errors) {
+        console.log(`  x ${error}`);
+    }
+    if (report.valid) {
+        console.log(`  Valid library package${report.warnings.length > 0 ? ` (${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"})` : ""}.`);
+        return 0;
+    }
+    console.log(`  ${report.errors.length} error${report.errors.length === 1 ? "" : "s"}.`);
+    return 1;
+}

package/dist/library-packages.d.ts

@@ -0,0 +1,95 @@
+import type { LibraryDefinition } from "./types.js";
+/** A native source file a library contributes to the emitted sources. */
+export interface CuttlefishLibraryShim {
+    /** Path of the shim file, relative to the library package root. */
+    path: string;
+    /** File name the shim is written as, in the emitted source directory. */
+    outName: string;
+}
+/** The parsed `cuttlefish.library.json` manifest. */
+export interface CuttlefishLibraryManifest {
+    /** Stable library id (diagnostics / sidecar records). */
+    id: string;
+    /** The import specifier this library resolves (e.g. '@typecad/zephyr-esp32s3-rgb'). */
+    module: string;
+    /** The framework (strategy id) this library requires, e.g. 'zephyr'. */
+    framework: string;
+    /** Build-target prefixes this library supports (matched against buildTarget). */
+    targets?: string[];
+    /** C++ include directive content for the import, e.g. '"__tc_rgbled.h"'. */
+    include: string;
+    /** Token whose presence in emitted sources gates the library's artifacts. */
+    gateToken: string;
+    /** Native shim files written into the emitted source directory. */
+    shims: CuttlefishLibraryShim[];
+    /** CONFIG_ lines contributed to the framework's prj.conf. */
+    kconfig?: string[];
+    /** Path of a devicetree overlay fragment, relative to the package root. */
+    overlay?: string;
+}
+/** A registered library: manifest + resolved package root. */
+export interface RegisteredCuttlefishLibrary {
+    manifest: CuttlefishLibraryManifest;
+    packageRoot: string;
+}
+/** One record of the `libraries.json` sidecar (build-time contribution set). */
+export interface LibrarySidecarEntry {
+    id: string;
+    module: string;
+    framework: string;
+    gateToken: string;
+    kconfig: string[];
+    /** Absolute path of the overlay fragment, or null. */
+    overlay: string | null;
+    /** Shim file names written into the emitted source directory. */
+    shims: string[];
+}
+/** Sidecar file name — written next to the emitted sources. */
+export declare const LIBRARY_SIDECAR_NAME = "libraries.json";
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export declare function resetCuttlefishLibraries(): void;
+/** All libraries registered during this transpilation (import-driven). */
+export declare function getRegisteredCuttlefishLibraries(): RegisteredCuttlefishLibrary[];
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export declare function isRegisteredCuttlefishLibrary(moduleSpecifier: string): boolean;
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export declare function registerCuttlefishLibraryFromSpecifier(fromFile: string, moduleSpecifier: string): boolean;
+/** Libdef entries for the registry: import → shim include. */
+export declare function cuttlefishLibraryLibdefs(): LibraryDefinition[];
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export declare function validateCuttlefishLibraries(frameworkId: string, buildTarget?: string): void;
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/sketch
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export declare function writeCuttlefishLibraryArtifacts(outDir: string, srcDir: string): void;
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export declare function readCuttlefishLibrarySidecar(outDir: string): LibrarySidecarEntry[];
+/** Re-exported for transpile.ts libdef injection convenience. */
+export declare function libraryDefinitionKey(module: string): string;

package/dist/library-packages.js

@@ -0,0 +1,275 @@
+// ---------------------------------------------------------------------------
+// Cuttlefish library packages
+//
+// A library package is an npm package whose root carries a
+// `cuttlefish.library.json` manifest. It contributes native artifacts to the
+// generated firmware application:
+//
+//   - an include mapping (the import emits `#include` of the shim header)
+//   - shim files (native C++ written into the emitted source directory)
+//   - framework build contributions (Kconfig lines, a devicetree overlay
+//     fragment) consumed by the framework toolchain via the sidecar
+//
+// Discovery is import-driven: when the transpile graph builder resolves an
+// import whose package ships the manifest, the package is registered at that
+// moment and its TypeScript is NOT transpiled — the package's own types are
+// the compile-time contract, and the native shim is the implementation.
+// Nothing scans node_modules; an installed-but-never-imported library
+// contributes nothing.
+//
+// The transpiler writes a `libraries.json` sidecar next to the emitted
+// sources (the board-constants.json convention) recording the libraries that
+// were actually used, so build-time consumers (framework toolchains) can
+// re-derive their contributions idempotently from disk.
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { toModuleKey } from "./utils/strings.js";
+/** Sidecar file name — written next to the emitted sources. */
+export const LIBRARY_SIDECAR_NAME = "libraries.json";
+const registered = new Map();
+/** Specifiers known NOT to be library packages (avoids repeated resolve attempts). */
+const knownNonLibraries = new Set();
+/** Clear all registrations. Called once per transpilation, before graph build. */
+export function resetCuttlefishLibraries() {
+    registered.clear();
+    knownNonLibraries.clear();
+}
+/** All libraries registered during this transpilation (import-driven). */
+export function getRegisteredCuttlefishLibraries() {
+    return [...registered.values()];
+}
+/**
+ * Whether the specifier resolves to a library registered in this
+ * transpilation. Library packages are exempt from the @typecad/* "SDK
+ * imports are type-level only" include skip — their import IS the include
+ * of the shim header.
+ */
+export function isRegisteredCuttlefishLibrary(moduleSpecifier) {
+    return registered.has(moduleSpecifier.toLowerCase());
+}
+function parseManifest(packageRoot) {
+    const manifestPath = path.join(packageRoot, "cuttlefish.library.json");
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const m = raw;
+    if (typeof m.id !== "string" ||
+        typeof m.module !== "string" ||
+        typeof m.framework !== "string" ||
+        typeof m.include !== "string" ||
+        typeof m.gateToken !== "string" ||
+        !Array.isArray(m.shims) ||
+        m.shims.length === 0) {
+        return undefined;
+    }
+    for (const shim of m.shims) {
+        if (typeof shim?.path !== "string" || typeof shim?.outName !== "string") {
+            return undefined;
+        }
+    }
+    return {
+        id: m.id,
+        module: m.module,
+        framework: m.framework,
+        targets: m.targets,
+        include: m.include,
+        gateToken: m.gateToken,
+        shims: m.shims,
+        kconfig: Array.isArray(m.kconfig) ? m.kconfig.filter((k) => typeof k === "string") : [],
+        overlay: typeof m.overlay === "string" ? m.overlay : undefined,
+    };
+}
+/**
+ * Resolve the package root for a bare npm specifier from the importing file,
+ * then register the package as a cuttlefish library if it ships a
+ * `cuttlefish.library.json`. Returns true when the specifier resolved to a
+ * registered library (the import must then be skipped by the graph builder).
+ */
+export function registerCuttlefishLibraryFromSpecifier(fromFile, moduleSpecifier) {
+    // Only bare npm specifiers ('pkg' or '@scope/pkg'[/subpath]) — relative
+    // imports and node builtins cannot be library packages.
+    if (moduleSpecifier.startsWith(".") || moduleSpecifier.startsWith("node:")) {
+        return false;
+    }
+    const cacheKey = moduleSpecifier.toLowerCase();
+    if (knownNonLibraries.has(cacheKey))
+        return false;
+    if (registered.has(cacheKey))
+        return true;
+    let packageRoot;
+    try {
+        const req = createRequire(path.resolve(fromFile));
+        // Resolve the package entry, then walk up to the nearest package.json —
+        // the package root. (Resolving the manifest subpath directly would be
+        // blocked by exports encapsulation; the entry point always resolves.)
+        const entry = req.resolve(moduleSpecifier);
+        let dir = path.dirname(entry);
+        while (dir !== path.dirname(dir)) {
+            if (fs.existsSync(path.join(dir, "package.json")))
+                break;
+            dir = path.dirname(dir);
+        }
+        if (dir !== path.dirname(dir))
+            packageRoot = dir;
+    }
+    catch {
+        packageRoot = undefined;
+    }
+    if (packageRoot === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    const manifest = parseManifest(packageRoot);
+    if (manifest === undefined) {
+        knownNonLibraries.add(cacheKey);
+        return false;
+    }
+    registered.set(cacheKey, { manifest, packageRoot });
+    return true;
+}
+/** Libdef entries for the registry: import → shim include. */
+export function cuttlefishLibraryLibdefs() {
+    return getRegisteredCuttlefishLibraries().map(({ manifest }) => ({
+        module: manifest.module,
+        include: manifest.include,
+    }));
+}
+/**
+ * Validate registered libraries against the loaded framework (and, when
+ * known, the build target). Throws with an actionable message when a library
+ * cannot work in this project — far earlier and clearer than the native
+ * compiler would.
+ */
+export function validateCuttlefishLibraries(frameworkId, buildTarget) {
+    for (const { manifest } of getRegisteredCuttlefishLibraries()) {
+        if (manifest.framework !== frameworkId) {
+            throw new Error(`Library ${manifest.module} requires the '${manifest.framework}' framework, ` +
+                `but this project uses '${frameworkId}'. ` +
+                `Install the matching framework or a '${frameworkId}' counterpart of this library.`);
+        }
+        if (buildTarget !== undefined &&
+            manifest.targets !== undefined &&
+            manifest.targets.length > 0 &&
+            !manifest.targets.some((t) => buildTarget.toLowerCase().startsWith(t.toLowerCase()))) {
+            throw new Error(`Library ${manifest.module} supports board targets ` +
+                `[${manifest.targets.join(", ")}], but this project builds for '${buildTarget}'.`);
+        }
+    }
+}
+function writeIfChanged(filePath, content) {
+    try {
+        if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8") === content)
+            return;
+    }
+    catch {
+        /* fall through and write */
+    }
+    fs.writeFileSync(filePath, content);
+}
+function readEmittedTokens(srcDir) {
+    let out = "";
+    let names = [];
+    try {
+        names = fs.readdirSync(srcDir);
+    }
+    catch {
+        return "";
+    }
+    for (const name of names) {
+        if (!/\.(cpp|cc|c|h|hpp|ino)$/.test(name))
+            continue;
+        try {
+            out += fs.readFileSync(path.join(srcDir, name), "utf8");
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return out;
+}
+function readSidecar(sidecarPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, "utf8"));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((e) => typeof e === "object" && e !== null && typeof e.module === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Emit the library artifacts for the libraries actually used in this
+ * transpilation, and write the `libraries.json` sidecar:
+ *
+ *   1. scan the emitted sources for each library's gate token;
+ *   2. write (write-if-changed) the shims of every gated library into the
+ *      emitted source directory — the framework scaffold's CMake/sketch
+ *      regen picks the sources up automatically;
+ *   3. delete shim files recorded in the previous sidecar that are no longer
+ *      used, so removing an import removes its native code;
+ *   4. persist the sidecar (even when empty — that clears stale state).
+ */
+export function writeCuttlefishLibraryArtifacts(outDir, srcDir) {
+    const sidecarPath = path.join(outDir, LIBRARY_SIDECAR_NAME);
+    const previous = readSidecar(sidecarPath);
+    const previousShims = new Set(previous.flatMap((e) => e.shims));
+    const emitted = readEmittedTokens(srcDir);
+    const usedShims = new Set();
+    const entries = [];
+    for (const { manifest, packageRoot } of getRegisteredCuttlefishLibraries()) {
+        if (!emitted.includes(manifest.gateToken))
+            continue;
+        for (const shim of manifest.shims) {
+            let content;
+            try {
+                content = fs.readFileSync(path.join(packageRoot, shim.path), "utf8");
+            }
+            catch {
+                continue; // broken library packaging — the missing header surfaces at compile
+            }
+            writeIfChanged(path.join(srcDir, shim.outName), content);
+            usedShims.add(shim.outName);
+        }
+        entries.push({
+            id: manifest.id,
+            module: manifest.module,
+            framework: manifest.framework,
+            gateToken: manifest.gateToken,
+            kconfig: manifest.kconfig ?? [],
+            overlay: manifest.overlay ? path.join(packageRoot, manifest.overlay) : null,
+            shims: manifest.shims.map((s) => s.outName).filter((n) => usedShims.has(n)),
+        });
+    }
+    // Remove shims from a previous build whose library is no longer used.
+    for (const name of previousShims) {
+        if (usedShims.has(name))
+            continue;
+        try {
+            fs.rmSync(path.join(srcDir, name), { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    writeIfChanged(sidecarPath, JSON.stringify(entries, null, 2) + "\n");
+}
+/**
+ * Read the `libraries.json` sidecar for build-time consumers (framework
+ * toolchains). Tolerant of a missing or corrupt file (returns []).
+ */
+export function readCuttlefishLibrarySidecar(outDir) {
+    return readSidecar(path.join(outDir, LIBRARY_SIDECAR_NAME));
+}
+/** Re-exported for transpile.ts libdef injection convenience. */
+export function libraryDefinitionKey(module) {
+    return toModuleKey(module);
+}

package/dist/orchestrator/graph-builder.js

@@ -3,6 +3,7 @@ import ts from "typescript";
 import { readText } from "../utils/fs.js";
 import { detectNativeCppModule, getNpmPackageInfoForFile, isInNodeModules, resolveImport, isCuttlefishSDKPath, } from "../transpile/resolution.js";
 import { requireUIHook } from "../ui-hook.js";
+import { registerCuttlefishLibraryFromSpecifier } from "../library-packages.js";
 /**
  * Sort files in dependency order using Kahn's algorithm.
  * Dependencies come before dependents so that include ordering is correct
@@ -125,6 +126,14 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 }
                 if (!moduleSpecifier)
                     continue;
+                // Cuttlefish library package: an import whose package ships a
+                // cuttlefish.library.json contributes native shims + build fragments
+                // instead of transpiling — its own TypeScript types are the contract.
+                // Must precede the @typecad/* skips: scoped libraries would otherwise
+                // be dropped as "SDK packages" here (the .ui script loop skips ALL
+                // @typecad/* specifiers, unlike the selective main-loop skip list).
+                if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier))
+                    continue;
                 if (moduleSpecifier === "@typecad/expect" || moduleSpecifier === "@typecad/ui" || moduleSpecifier === "@typecad/safety")
                     continue;
                 if (moduleSpecifier.startsWith("@typecad/"))
@@ -158,6 +167,13 @@ export async function collectTranspileGraph(entryFile, boardPackage, imageDecode
                 nativeModules.set(moduleSpecifier, nativeModule);
                 continue; // Don't try to resolve as TypeScript
             }
+            // Cuttlefish library package: an import whose package ships a
+            // cuttlefish.library.json contributes native shims + build fragments
+            // instead of transpiling — its own TypeScript types are the contract.
+            // Checked before the @typecad/* skips so scoped libraries register.
+            if (registerCuttlefishLibraryFromSpecifier(filePath, moduleSpecifier)) {
+                continue;
+            }
             // Skip @typecad/expect — it provides type-level stubs only.
             // The AST preprocessor rewrites all expect calls before transpilation.
             if (moduleSpecifier === "@typecad/expect") {

package/dist/preview/client.js

@@ -8,6 +8,9 @@ let pendingPointerFrame = 0;
 let debugModes = { boxes: false, clips: false, dirty: false, inspect: false };
 let debugOverlay;
 let debugCtx;
+/** Re-syncs the overlay to the app canvas whenever layout changes its box
+ *  (aspect-ratio application, max-height, container reflow). */
+let overlayResizeObserver;
 let dirtyFlashAlpha = 0;
 /** CSS px per logical display px — the overlay backing store runs at this
  *  resolution so debug strokes are 1 CSS px thin (a 1-logical-px stroke on
@@ -263,11 +266,22 @@ async function start() {
         debugOverlay.height = Math.max(1, Math.round(rect.height * dpr));
         debugScale = (rect.width * dpr) / snapshot.program.width;
     };
-    syncOverlayBox();
-    window.addEventListener("resize", syncOverlayBox);
     // Set the canvas CSS aspect-ratio to match the display (e.g. 128:64 for
-    // OLED, 320:240 for TFT) so the browser scales it proportionally.
+    // OLED, 320:240 for TFT) BEFORE syncing the overlay: the canvas is
+    // vertically centered (place-items: center), so applying the real aspect
+    // after the sync SHRANK it and moved it DOWN — the overlay stayed at the
+    // old 4/3-fallback position and every debug box sat that far above its
+    // element. A ResizeObserver re-syncs on any later layout-driven size
+    // change (max-height kicking in, container reflow), not just window
+    // resizes.
     document.documentElement.style.setProperty("--display-aspect", `${snapshot.program.width} / ${snapshot.program.height}`);
+    syncOverlayBox();
+    window.addEventListener("resize", syncOverlayBox);
+    if (typeof ResizeObserver !== "undefined") {
+        overlayResizeObserver?.disconnect();
+        overlayResizeObserver = new ResizeObserver(() => syncOverlayBox());
+        overlayResizeObserver.observe(canvas);
+    }
     const status = byId("status");
     status.textContent = `${snapshot.profileName ?? snapshot.program.display?.driver ?? "display"} ${snapshot.program.width}x${snapshot.program.height} ${snapshot.program.colorFormat}`;
     const extraDiagnostics = [];

package/dist/testing.d.ts

@@ -19,8 +19,8 @@ export { transpileFile } from "./transpile.js";
 export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
 export { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
 export { setSafetyHook, hasSafetyHook } from "./safety-hook.js";
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
-export type { InitProjectOptions } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runCreateWizard, } from "./create/index.js";
+export type { CreateProjectOptions } from "./create/index.js";
 export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
 export type { BoardSpec, ScaffoldBoardResult } from "./create/index.js";
 export { BoardGenerators } from "./create/index.js";

package/dist/testing.js

@@ -23,7 +23,7 @@ export { resetUIEngine, __simulateUIAbsentForTest } from "./ui/ui-bridge.js";
 export { resetSafetyEngine, __simulateSafetyAbsentForTest } from "./safety/safety-bridge.js";
 export { setSafetyHook, hasSafetyHook } from "./safety-hook.js";
 // ── Project scaffolding ──────────────────────────────────────────────────────
-export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runInitWizard, } from "./create/index.js";
+export { scaffoldProject, normalizeProjectName, KNOWN_BOARDS, generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, runCreateWizard, } from "./create/index.js";
 // ── Board codegen (`cuttlefish board add`) ───────────────────────────────────
 export { scaffoldBoardPackages, parseBoardSpec, safeParseBoardSpec, stripJsonc, } from "./create/index.js";
 export { BoardGenerators } from "./create/index.js";