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

package/dist/theme-tokens.js

@@ -0,0 +1,172 @@
+// ---------------------------------------------------------------------------
+// shadcn kit themes — the included token sets under assets/shadcn/themes/.
+//
+// A theme file is two CSS blocks (:root = light tokens, .dark = dark tokens)
+// plus an optional header comment. Selecting a theme MERGES each block into
+// the kit's stylesheet: declarations the theme defines override the kit's,
+// and kit-specific extras the theme lacks (notably --destructive-background,
+// which stock shadcn themes don't carry) keep their current values — so any
+// stock theme from ui.shadcn.com or tweakcn pastes cleanly.
+//
+// Used by `cuttlefish add shadcn --theme <name>` (scaffold time) and
+// `cuttlefish theme <name>` (swap an existing project's kit stylesheet).
+// ---------------------------------------------------------------------------
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const THEMES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../assets/shadcn/themes");
+/** The tokens the kit's recipes reference; every merged theme must cover them. */
+const REQUIRED_TOKENS = [
+    "--background", "--foreground",
+    "--card", "--card-foreground",
+    "--primary", "--primary-foreground",
+    "--secondary", "--secondary-foreground",
+    "--muted", "--muted-foreground",
+    "--accent", "--accent-foreground",
+    "--destructive", "--destructive-foreground", "--destructive-background",
+    "--border", "--input", "--radius",
+];
+/** Blank out /* … *​/ comment interiors (same length) so selector searches
+ *  can't match inside a comment while byte offsets stay valid against the
+ *  original text. The kit's header comment literally contains `.dark { ... }`
+ *  as documentation — an unmasked search spliced tokens into the comment and
+ *  left the real block untouched. */
+function maskComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, (m) => " ".repeat(m.length));
+}
+/** Locate `selector {` in css, skipping comment spans. Custom-property values
+ *  contain no braces, so the block ends at the first `}` after the opening
+ *  one. */
+function blockRange(css, selector) {
+    const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const m = new RegExp(escaped + "\\s*\\{").exec(maskComments(css));
+    if (!m)
+        return null;
+    const open = m.index + m[0].length;
+    const close = css.indexOf("}", open);
+    if (close < 0)
+        return null;
+    return { selStart: m.index, open, close };
+}
+/** Parse a token block's declarations (line-oriented; one decl per line, the
+ *  format both the kit and stock shadcn themes use). */
+function parseDecls(block) {
+    const out = [];
+    for (const line of block.split("\n")) {
+        const m = /^\s*(--[\w-]+)\s*:\s*([^;]+);/.exec(line);
+        if (m)
+            out.push([m[1], m[2].trim()]);
+    }
+    return out;
+}
+function emitBlock(selector, decls) {
+    const body = decls.map(([k, v]) => `  ${k}: ${v};`).join("\n");
+    return `${selector} {\n${body}\n}`;
+}
+/** Order-preserving override merge: base order, overrides in place, theme-only
+ *  declarations appended. */
+function mergeDecls(base, override) {
+    const out = base.map(([k, v]) => [k, v]);
+    const indexByName = new Map(out.map(([k], i) => [k, i]));
+    for (const [k, v] of override) {
+        const existing = indexByName.get(k);
+        if (existing !== undefined)
+            out[existing][1] = v;
+        else {
+            indexByName.set(k, out.length);
+            out.push([k, v]);
+        }
+    }
+    return out;
+}
+/** Where a project keeps its own themes: src/styles/themes/*.css next to
+ *  the kit stylesheet. Project themes win over same-named package ones —
+ *  pasting a theme is dropping a file into YOUR project, never node_modules. */
+export function projectThemesDir(projectRoot) {
+    return path.resolve(projectRoot, "src/styles/themes");
+}
+function themeNamesIn(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((f) => f.endsWith(".css") && !f.startsWith("_"))
+        .map((f) => f.replace(/\.css$/, ""))
+        .sort();
+}
+/** Theme names, project-local (src/styles/themes/) first, then the ones
+ *  shipped in the package (assets/shadcn/themes/). */
+export function listShadcnThemes(projectRoot) {
+    const local = projectRoot ? themeNamesIn(projectThemesDir(projectRoot)) : [];
+    const included = themeNamesIn(THEMES_DIR);
+    return [...new Set([...local, ...included])].sort();
+}
+function formatThemeList(projectRoot) {
+    const local = projectRoot ? themeNamesIn(projectThemesDir(projectRoot)) : [];
+    const included = themeNamesIn(THEMES_DIR);
+    const lines = [];
+    if (local.length > 0) {
+        lines.push("project (src/styles/themes/):");
+        for (const n of local)
+            lines.push(`  ${n}`);
+    }
+    lines.push("included with cuttlefish:");
+    for (const n of included)
+        lines.push(`  ${n}`);
+    lines.push("(paste your own: src/styles/themes/<name>.css in this project)");
+    return lines.join("\n");
+}
+/** Load a theme by name — project-local directory first, then the package
+ *  included set. Throws with the available names when missing. */
+export function loadShadcnTheme(name, projectRoot) {
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        throw new Error(`Invalid theme name "${name}" — use letters, digits, and dashes.`);
+    }
+    const candidates = projectRoot
+        ? [path.join(projectThemesDir(projectRoot), `${name}.css`), path.join(THEMES_DIR, `${name}.css`)]
+        : [path.join(THEMES_DIR, `${name}.css`)];
+    const file = candidates.find((c) => fs.existsSync(c));
+    if (!file) {
+        throw new Error(`Unknown theme "${name}". Available themes:\n${formatThemeList(projectRoot)}`);
+    }
+    const text = fs.readFileSync(file, "utf-8");
+    const rootRange = blockRange(text, ":root");
+    const darkRange = blockRange(text, ".dark");
+    if (!rootRange || !darkRange) {
+        throw new Error(`Theme "${name}" must define both a :root and a .dark token block.`);
+    }
+    const light = parseDecls(text.slice(rootRange.open, rootRange.close));
+    const dark = parseDecls(text.slice(darkRange.open, darkRange.close));
+    if (light.length === 0 || dark.length === 0) {
+        throw new Error(`Theme "${name}" has empty token blocks — paste the theme's :root and .dark declarations.`);
+    }
+    return { name, light, dark };
+}
+/** Merge a theme's tokens into a kit stylesheet's :root/.dark blocks and
+ *  return the rewritten text. Throws when a merged block is missing any
+ *  token the kit's recipes reference. */
+export function applyShadcnTheme(cssText, theme) {
+    let out = cssText;
+    for (const [selector, themeDecls] of [[".dark", theme.dark], [":root", theme.light]]) {
+        const range = blockRange(out, selector);
+        if (!range) {
+            throw new Error(`The kit stylesheet has no ${selector} token block to replace.`);
+        }
+        const merged = mergeDecls(parseDecls(out.slice(range.open, range.close)), themeDecls);
+        out = out.slice(0, range.selStart) + emitBlock(selector, merged) + out.slice(range.close + 1);
+    }
+    // Validate AFTER both merges (a token can live in either block).
+    const rootRange = blockRange(out, ":root");
+    const darkRange = blockRange(out, ".dark");
+    const names = new Set();
+    if (rootRange)
+        for (const [k] of parseDecls(out.slice(rootRange.open, rootRange.close)))
+            names.add(k);
+    if (darkRange)
+        for (const [k] of parseDecls(out.slice(darkRange.open, darkRange.close)))
+            names.add(k);
+    const missing = REQUIRED_TOKENS.filter((t) => !names.has(t));
+    if (missing.length > 0) {
+        throw new Error(`Theme "${theme.name}" leaves required tokens unset: ${missing.join(", ")}`);
+    }
+    return out;
+}

package/dist/transpile.js

@@ -26,11 +26,12 @@ import { requireUIHook, hasUIHook } from "./ui-hook.js";
 import { loadUIEngine } from "./ui/ui-bridge.js";
 import { hasSafetyHook, requireSafetyHook } from "./safety-hook.js";
 import { loadSafetyEngine } from "./safety/safety-bridge.js";
-import { setDisplayProfile, resetDisplayProfile } from "./stores/display-profile-store.js";
+import { setDisplayProfile, resetDisplayProfile, getDisplayProfile } from "./stores/display-profile-store.js";
 import { setThemeCss, resetThemeCss, setThemeClass } from "./stores/theme-store.js";
 import { emitCpp, registerAllEnumNames } from "./emit/cpp-emitter.js";
-import { readText, writeText } from "./utils/fs.js";
+import { readText, writeText, resetWrittenFiles, wasWrittenThisRun } from "./utils/fs.js";
 import { debug as logDebug, info } from "./utils/logger.js";
+import { printDebugStrategy } from "./utils/ui.js";
 import { loadLibraryDefinitions, generateLibdefStubs } from "./libdef/registry.js";
 import { buildCallGraph } from "./ir/call-graph.js";
 import { clearCaches, } from "./cache.js";
@@ -66,12 +67,53 @@ function loadExpectPreprocessor() {
     }
 }
 function cleanOutput(_entryDir, outDir) {
-    // Preserved for incremental-build support: writeText now skips writing when
-    // content is identical, so keeping the existing output dir intact lets
-    // downstream build tools (idf.py/ninja, arduino-cli) reuse their build
-    // caches. Stale files from removed source modules are harmless — they're
-    // not referenced by the current entry file and won't be compiled.
-    // The output dir is still created (via writeText → ensureDir) on first run.
+    // The out dir is NOT wiped: writeText skips writing when content is
+    // identical, so keeping it lets downstream build tools (idf.py/ninja,
+    // arduino-cli) reuse their build caches. Stale generated SOURCES are handled
+    // precisely instead — after emission, sweepStaleGeneratedSources() removes
+    // compiled-source files in the out dir that this run did not write (e.g. a
+    // main.cpp left behind by the old emit naming next to the current src.cpp;
+    // Zephyr's CMakeLists globs src/*.cpp, so a leftover compiles into
+    // duplicate-symbol link errors). The output dir is still created (via
+    // writeText → ensureDir) on first run.
+    void outDir;
+    resetWrittenFiles();
+}
+const GENERATED_SOURCE_EXTENSIONS = [".cpp", ".cc", ".c", ".h", ".ino"];
+/**
+ * Remove stale generated source files from the out dir: compiled-source files
+ * that THIS transpile run did not write. Sweeps only the source layouts the
+ * emit pipeline uses (out dir root, src/, main/) and never recurses — build
+ * trees (e.g. Zephyr's out/build with its own generated .c files) are
+ * untouched, and neither are sidecar JSONs.
+ */
+function sweepStaleGeneratedSources(outDir) {
+    for (const sub of ["", "src", "main"]) {
+        const dir = sub ? path.join(outDir, sub) : outDir;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // layout subdir not used by this framework
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!GENERATED_SOURCE_EXTENSIONS.some((ext) => entry.name.toLowerCase().endsWith(ext)))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (wasWrittenThisRun(full))
+                continue;
+            try {
+                fs.unlinkSync(full);
+                info(`Removed stale generated source: ${path.relative(process.cwd(), full)}`);
+            }
+            catch {
+                // Locked/read-only file — leave it; best-effort cleanup.
+            }
+        }
+    }
 }
 /**
  * Auto-generates .d.ts files for C++ modules that are missing declarations.
@@ -160,6 +202,15 @@ import { loadFrameworkPackage } from "./framework-package.js";
 export { loadFrameworkPackage };
 export { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
 import { getLoadedFramework, hasLoadedFramework } from "./framework-registry.js";
+/** Under --strict-css, UI CSS-compatibility warnings (code css-*: ignored
+ *  alpha, quantized font sizes, unsupported display/position values, ...) are
+ *  upgraded to errors so the build fails instead of approximating silently. */
+function upgradeStrictCss(d, strict) {
+    if (strict && d.severity === "warning" && typeof d.code === "string" && d.code.startsWith("css-")) {
+        return { ...d, severity: "error" };
+    }
+    return d;
+}
 function formatFatalDiagnostics(entries) {
     const errors = entries.filter(({ diagnostic }) => diagnostic.severity === "error");
     const lines = [
@@ -219,7 +270,11 @@ function loadPlatformStrategy(frameworkPackage, _boardPackage, fromDir, debug) {
         if (hasLoadedFramework()) {
             const { strategy } = getLoadedFramework();
             if (debug) {
-                logDebug(`Loaded FrameworkStrategy from ${frameworkPackage}`, true);
+                // Styled like the other step lines (cyan ⇉) — says what the debug
+                // build is actually doing, in user terms. Falls back to the package
+                // name when the strategy carries no id.
+                const frameworkName = strategy.id || frameworkPackage.replace(/^@typecad\/framework-/, "");
+                printDebugStrategy(frameworkName);
             }
             return strategy;
         }
@@ -310,7 +365,19 @@ export async function transpileFile(options) {
     // see incremental-cache.ts — so we always transpile the full graph.)
     cleanOutput(entryDir, outDir);
     profiler.startTimer("graph:collect");
-    const graphResult = collectTranspileGraph(entryFile, options.boardPackage);
+    // Image-conversion cap: never decode larger than the physical panel —
+    // converted <img> assets downscale to fit (no 24MB C arrays from photos).
+    const imageDecodeMax = await (async () => {
+        try {
+            const { effectiveDisplaySize } = await import("./api/shared/display-profile.js");
+            const size = effectiveDisplaySize(getDisplayProfile());
+            return { maxW: size.width, maxH: size.height };
+        }
+        catch {
+            return {};
+        }
+    })();
+    const graphResult = await collectTranspileGraph(entryFile, options.boardPackage, imageDecodeMax);
     profiler.endTimer("graph:collect");
     const transpileFiles = graphResult.files;
     // ── Type-check all files before transpiling ────────────────────────────────
@@ -408,10 +475,12 @@ export async function transpileFile(options) {
     // parser warnings (unknown CSS properties, unknown HTML tags) here so the
     // author sees typos and unsupported features instead of silent drops.
     // Guarded: @typecad/ui is optional, so there may be no UI engine loaded.
+    // --strict-css upgrades the css-* compatibility warnings to errors.
     if (hasUIHook()) {
         for (const mod of requireUIHook().allUIModules()) {
             for (const d of mod.diagnostics) {
-                diagnostics.push({ ...d, filePath: d.filePath ?? path.basename(mod.htmlPath) });
+                const upgraded = upgradeStrictCss(d, options.strictCss);
+                diagnostics.push({ ...upgraded, filePath: d.filePath ?? path.basename(mod.htmlPath) });
             }
         }
     }
@@ -541,10 +610,12 @@ export async function transpileFile(options) {
     profiler.endTimer("ir:build-all");
     // ── UI mount-time warnings (scroll memory budget, etc.) ─────────────────
     // Guarded: @typecad/ui is optional; no engine means no UI modules.
+    // --strict-css upgrades the css-* compatibility warnings to errors.
     if (hasUIHook()) {
         for (const mod of requireUIHook().allUIModules()) {
             for (const d of mod.mountDiagnostics) {
-                diagnostics.push({ ...d, filePath: d.filePath ?? path.basename(mod.htmlPath) });
+                const upgraded = upgradeStrictCss(d, options.strictCss);
+                diagnostics.push({ ...upgraded, filePath: d.filePath ?? path.basename(mod.htmlPath) });
             }
         }
     }
@@ -822,6 +893,13 @@ export async function transpileFile(options) {
         }
     }
     profiler.endTimer("post:flatten");
+    // Remove stale generated sources (renamed entries, removed modules) so
+    // downstream globs (Zephyr's CMakeLists src/*.cpp) don't compile leftovers
+    // into duplicate-symbol link errors. Runs after every write of this run,
+    // including the toolchain prepare hook above.
+    profiler.startTimer("post:sweep-stale");
+    sweepStaleGeneratedSources(outDir);
+    profiler.endTimer("post:sweep-stale");
     // Profiler session ends (profiling disabled - no report generation)
     // ── Generate diagnostics report if enabled ──────────────────────────────
     let diagnosticsReportPath;

package/dist/types.d.ts

@@ -100,6 +100,8 @@ export interface TranspileOptions {
     autosar?: ComplianceMode;
     /** When true (and autosar is warn/strict), also emit the .autosar-deviations.arxml sidecar. */
     autosarArxml?: boolean;
+    /** Upgrade UI CSS-compatibility warnings (css-* diagnostics) to errors. */
+    strictCss?: boolean;
 }
 export interface LibraryDefinitionCondition {
     target?: TargetProfile;
@@ -179,6 +181,8 @@ export interface CommandLineOptions {
     autosar?: ComplianceMode;
     /** When true (and autosar is warn/strict), also emit the .autosar-deviations.arxml sidecar. */
     autosarArxml?: boolean;
+    /** Upgrade UI CSS-compatibility warnings (css-* diagnostics) to errors. */
+    strictCss?: boolean;
     /** Config file for preview command */
     configPath?: string;
     /** Project root (dir of cuttlefish.config.ts); passed to transpileFile for the ESLint gate. */
@@ -188,6 +192,7 @@ export interface GenerateLibdefOptions {
     inputFile: string;
     outDir: string;
 }
+/** `cuttlefish add <preset>` — scaffold a copy-and-own asset into the project. */
 export interface GeneratedOutputs {
     headerPath?: string;
     sourcePath: string;

package/dist/ui-hook.d.ts

@@ -75,6 +75,13 @@ export interface TranspilerUIHook {
         nativeDisplayActive?: boolean;
     }): string;
     splitUiFile(src: string): UiFileParts;
+    /** Pre-decode src="…" image references (png/jpg/ico/…) into the RGB565
+     *  asset cache. Must be awaited BEFORE loadUIModule/loadUIModuleFromText —
+     *  the synchronous asset reader and natural-size layout read the cache. */
+    warmUpImageDecoding(sourceText: string, baseDir: string, opts?: {
+        maxW?: number;
+        maxH?: number;
+    }): Promise<void>;
     generateProjectUITypeDeclarations(projectRoot: string): {
         written: string[];
         errors: Array<{

package/dist/utils/cli.js

@@ -49,6 +49,10 @@ export function printHelp() {
     console.log(`  --autosar-arxml         Also write <name>.autosar-deviations.arxml (Artop/DaVinci).`);
     console.log(`                          No-op unless --autosar is warn or strict.`);
     console.log();
+    console.log(`  --strict-css            Treat UI CSS-compatibility warnings as errors (css-*`);
+    console.log(`                          diagnostics: ignored alpha, quantized font sizes,`);
+    console.log(`                          unsupported display/position values, viewport-hogging sizes).`);
+    console.log();
     console.log(chalk.cyan(`BUILD COMMANDS`) + chalk.gray(` (chain in order: --compile → --upload → --monitor)`));
     console.log();
     console.log(`  --compile               Compile the generated output using the framework toolchain.`);
@@ -277,6 +281,10 @@ function parsePipelineCommand(argv, command, inputFile) {
     // --autosar-arxml: also write the .autosar-deviations.arxml sidecar
     // (Artop/DaVinci tooling). No-op unless --autosar is warn or strict.
     const autosarArxml = readBooleanFlag(argv, ["--autosar-arxml"]);
+    // --strict-css: upgrade UI CSS-compatibility warnings (css-* diagnostics,
+    // e.g. ignored alpha, quantized font sizes, unsupported display values) to
+    // errors so builds fail instead of silently approximating.
+    const strictCss = readBooleanFlag(argv, ["--strict-css"]);
     const emitMode = emitFlag === "cpp" || emitFlag === "split" ? emitFlag : "split";
     const emitMaps = emitMapsFlag === undefined ? true : emitMapsFlag !== "false";
     // Accept any target string — the framework package registers its own strategy id.
@@ -329,6 +337,7 @@ function parsePipelineCommand(argv, command, inputFile) {
         frameworkPackage: frameworkFlag,
         autosar,
         autosarArxml,
+        strictCss,
     };
 }
 export function parseCommandLine(argv) {

package/dist/utils/fs.d.ts

@@ -1,5 +1,7 @@
 export declare function ensureDir(dirPath: string): void;
 export declare function readText(filePath: string): string;
+export declare function resetWrittenFiles(): void;
+export declare function wasWrittenThisRun(filePath: string): boolean;
 export declare function writeText(filePath: string, content: string): void;
 export declare function listFiles(dirPath: string, extension: string): string[];
 /**

package/dist/utils/fs.js

@@ -8,10 +8,26 @@ export function ensureDir(dirPath) {
 export function readText(filePath) {
     return fs.readFileSync(filePath, "utf8");
 }
+// Paths written (or confirmed identical) via writeText since the last
+// resetWrittenFiles() call. The transpiler uses this to sweep stale generated
+// sources from the out dir — files left behind by renamed entries or removed
+// source modules that a downstream glob (e.g. Zephyr's CMakeLists
+// `file(GLOB src/*.cpp)`) would otherwise compile, producing duplicate-symbol
+// link errors.
+const writtenFiles = new Set();
+export function resetWrittenFiles() {
+    writtenFiles.clear();
+}
+export function wasWrittenThisRun(filePath) {
+    return writtenFiles.has(path.resolve(filePath));
+}
 export function writeText(filePath, content) {
     ensureDir(path.dirname(filePath));
+    const resolved = path.resolve(filePath);
     // Skip writing when content is identical — preserves mtime so downstream
     // build tools (idf.py/ninja, arduino-cli, make) can skip recompilation.
+    // The file still counts as "written this run" (it is current output).
+    writtenFiles.add(resolved);
     try {
         if (fs.readFileSync(filePath, "utf8") === content)
             return;

package/dist/utils/ui.d.ts

@@ -27,6 +27,11 @@ export declare function printTranspiling(): void;
  * Print compiling step
  */
 export declare function printCompiling(target: string): void;
+/**
+ * Print the debug-session strategy notice (debug builds only): which
+ * framework's code-generation strategy is preparing the debug build.
+ */
+export declare function printDebugStrategy(framework: string): void;
 /**
  * Print uploading step
  */

package/dist/utils/ui.js

@@ -69,6 +69,13 @@ export function printTranspiling() {
 export function printCompiling(target) {
     console.log(chalk.cyan(`${ICON_COMPILE} Compiling for `) + chalk.white(target));
 }
+/**
+ * Print the debug-session strategy notice (debug builds only): which
+ * framework's code-generation strategy is preparing the debug build.
+ */
+export function printDebugStrategy(framework) {
+    console.log(chalk.cyan(`${ICON_COMPILE} Preparing to debug using `) + chalk.white(framework));
+}
 /**
  * Print uploading step
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/cuttlefish",
-  "version": "1.0.0-alpha.11",
+  "version": "1.0.0-alpha.13",
   "description": "TypeScript to C++ transpiler — native, Arduino, and bare-metal targets",
   "type": "module",
   "main": "./dist/transpile.js",
@@ -83,7 +83,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "assets"
   ],
   "publishConfig": {
     "access": "public"
@@ -99,8 +100,8 @@
     "zod": "^3.24.0"
   },
   "peerDependencies": {
-    "@typecad/ui": "1.0.0-alpha.11",
-    "@typecad/safety": "1.0.0-alpha.11"
+    "@typecad/ui": "1.0.0-alpha.13",
+    "@typecad/safety": "1.0.0-alpha.13"
   },
   "peerDependenciesMeta": {
     "@typecad/ui": {
@@ -111,7 +112,8 @@
     }
   },
   "optionalDependencies": {
-    "@typecad/framework-native": "1.0.0-alpha.11"
+    "@typecad/expect": "1.0.0-alpha.13",
+    "@typecad/framework-native": "1.0.0-alpha.13"
   },
   "devDependencies": {
     "@types/node": "^22.10.7"