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

package/dist/create/editor-integration.d.ts

@@ -0,0 +1,30 @@
+/** VS Code extension identifiers (publisher.name) of the bundled extensions. */
+export declare const TYPECAD_UI_EXTENSION_ID = "typecad.typecad-ui";
+export declare const TYPECAD_DEBUG_EXTENSION_ID = "typecad.vscode-typecad-debug";
+/**
+ * Source location of an unpacked bundled extension inside the cuttlefish
+ * package. Resolved from this module's location so it works from both src/
+ * (dev and tests importing source) and dist/ (the published CLI) — assets/
+ * sits at the package root either way.
+ */
+export declare function bundledExtensionSourceDir(dir: string): string;
+/** Kept for compatibility with the original single-extension helper. */
+export declare function typecadUiExtensionSourceDir(): string;
+/** Content of .vscode/extensions.json — auto-installs the workspace-bundled extensions. */
+export declare function generateExtensionsJson(): string;
+export declare const WATCH_TASK_LABEL = "cuttlefish: watch build";
+/** The watch task entry written to .vscode/tasks.json. */
+export declare function watchBuildTask(): Record<string, unknown>;
+/**
+ * Content of .vscode/tasks.json containing the watch task. Kept separate from
+ * the merge logic so tests can assert the shape without a filesystem.
+ */
+export declare function generateTasksJson(existingTasks?: ReadonlyArray<Record<string, unknown>>): string;
+/**
+ * Copy the bundled extensions into <outDir>/.vscode/extensions/, then write the
+ * companion .vscode/extensions.json and — when the project has a `dev` watch
+ * script — the .vscode/tasks.json watch task. Returns the absolute paths
+ * written, or [] when the extension assets are missing (warns, never throws).
+ * `assetsRoot` overrides the bundled-asset location (tests).
+ */
+export declare function writeEditorIntegration(outDir: string, assetsRoot?: string): string[];

package/dist/create/editor-integration.js

@@ -0,0 +1,218 @@
+// ---------------------------------------------------------------------------
+// editor-integration.ts — create-time editor scaffolding for .ui highlighting
+//
+// Cuttlefish projects keep their UI in .ui single-file components (TS script +
+// CSS style + Svelte-style markup), which no editor knows out of the box. The
+// package ships grammar-only VS Code extensions under
+// assets/editor-extensions/ and `cuttlefish create` copies them into the new
+// project's .vscode/extensions/ folder:
+//
+//   typecad-ui     — .ui syntax highlighting, snippets, file icons, markdown
+//                    ```ui fence highlighting (grammar-only, no code).
+//   typecad-debug  — the built TypeCAD Debug extension (breakpoint syncing +
+//                    F5 commands), so debugging works with zero install.
+//
+// VS Code (1.89+, trusted workspaces) detects workspace-bundled extensions and
+// installs them scoped to that workspace. The companion .vscode/extensions.json
+// carries forceInstall entries (microsoft/vscode#299830) so VS Code builds with
+// that feature skip the approval prompt; older builds show a one-time install
+// prompt instead.
+//
+// A .vscode/tasks.json watch task is also written: it runs the project's
+// `cuttlefish build --watch` dev script with NO_COLOR=1 and parses the
+// transpiler/ESLint diagnostic lines into Problems-panel squiggles. The task
+// merges by label (never clobbers user edits or the framework debug writer's
+// tasks, which merge the same way).
+//
+// Everything here is best-effort like the debug-artifact generation: a missing
+// or unreadable asset tree warns and skips rather than failing `cuttlefish
+// create`, because a project without editor integration still builds fine.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** VS Code extension identifiers (publisher.name) of the bundled extensions. */
+export const TYPECAD_UI_EXTENSION_ID = 'typecad.typecad-ui';
+export const TYPECAD_DEBUG_EXTENSION_ID = 'typecad.vscode-typecad-debug';
+/** Extensions to bundle, as { asset folder name → extension id } pairs. */
+const BUNDLED_EXTENSIONS = [
+    { dir: 'typecad-ui', id: TYPECAD_UI_EXTENSION_ID },
+    { dir: 'typecad-debug', id: TYPECAD_DEBUG_EXTENSION_ID },
+];
+const ASSETS_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'assets', 'editor-extensions');
+/**
+ * Source location of an unpacked bundled extension inside the cuttlefish
+ * package. Resolved from this module's location so it works from both src/
+ * (dev and tests importing source) and dist/ (the published CLI) — assets/
+ * sits at the package root either way.
+ */
+export function bundledExtensionSourceDir(dir) {
+    return path.join(ASSETS_ROOT, dir);
+}
+/** Kept for compatibility with the original single-extension helper. */
+export function typecadUiExtensionSourceDir() {
+    return bundledExtensionSourceDir('typecad-ui');
+}
+/** Content of .vscode/extensions.json — auto-installs the workspace-bundled extensions. */
+export function generateExtensionsJson() {
+    return `${JSON.stringify({ forceInstall: BUNDLED_EXTENSIONS.map(e => e.id) }, null, 2)}\n`;
+}
+// -- watch task + problem matchers ------------------------------------------------
+/**
+ * Problem matchers for cuttlefish's two diagnostic line formats:
+ *   transpiler:  "<file> error|warning [code] (line,column): message"
+ *   eslint gate: "error <file>(line,column) [rule]: message"
+ * NO_COLOR=1 is set on the task so chalk stays off and the lines stay greppable.
+ */
+const PROBLEM_MATCHERS = [
+    {
+        owner: 'cuttlefish-transpiler',
+        severity: 'error',
+        fileLocation: ['relative', '${workspaceFolder}'],
+        pattern: {
+            regexp: '^\\s*(.*?)\\s+(error|warning)(?:\\s+\\[[^\\]]*\\])?\\s*\\((\\d+),(\\d+)\\):\\s+(.*)$',
+            file: 1,
+            severity: 2,
+            line: 3,
+            column: 4,
+            message: 5,
+        },
+        background: {
+            beginsPattern: 'Transpiling',
+            endsPattern: 'Watching for changes',
+        },
+    },
+    {
+        owner: 'cuttlefish-eslint',
+        severity: 'error',
+        fileLocation: ['relative', '${workspaceFolder}'],
+        pattern: {
+            regexp: '^\\s*error\\s+(.*?)\\((\\d+),(\\d+)\\)\\s+\\[[^\\]]*\\]:\\s+(.*)$',
+            file: 1,
+            line: 2,
+            column: 3,
+            message: 4,
+        },
+        background: {
+            beginsPattern: 'Transpiling',
+            endsPattern: 'Watching for changes',
+        },
+    },
+];
+export const WATCH_TASK_LABEL = 'cuttlefish: watch build';
+/** The watch task entry written to .vscode/tasks.json. */
+export function watchBuildTask() {
+    return {
+        label: WATCH_TASK_LABEL,
+        command: 'npm run dev',
+        type: 'shell',
+        isBackground: true,
+        group: 'build',
+        options: { env: { NO_COLOR: '1' } },
+        problemMatcher: PROBLEM_MATCHERS,
+    };
+}
+/**
+ * Content of .vscode/tasks.json containing the watch task. Kept separate from
+ * the merge logic so tests can assert the shape without a filesystem.
+ */
+export function generateTasksJson(existingTasks = []) {
+    const tasks = [...existingTasks];
+    const idx = tasks.findIndex(t => t.label === WATCH_TASK_LABEL);
+    const task = watchBuildTask();
+    if (idx >= 0)
+        tasks[idx] = task;
+    else
+        tasks.push(task);
+    return `${JSON.stringify({ version: '2.0.0', tasks }, null, 2)}\n`;
+}
+/**
+ * Read-merge-write .vscode/tasks.json with the watch task (by label), so user
+ * edits and the framework debug writer's tasks survive. Mirrors the Zephyr
+ * debug-config merge semantics.
+ */
+function writeTasksJson(vscodeDir) {
+    const tasksPath = path.join(vscodeDir, 'tasks.json');
+    let existing = [];
+    if (fs.existsSync(tasksPath)) {
+        try {
+            const doc = JSON.parse(fs.readFileSync(tasksPath, 'utf-8'));
+            const tasks = doc.tasks;
+            if (Array.isArray(tasks)) {
+                existing = tasks.filter((t) => !!t && typeof t === 'object');
+            }
+        }
+        catch {
+            // malformed — start fresh
+        }
+    }
+    fs.writeFileSync(tasksPath, generateTasksJson(existing), 'utf-8');
+    return tasksPath;
+}
+// -- install -----------------------------------------------------------------
+/** All files under `dir`, as paths relative to `dir`. */
+function listFilesRecursive(dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            for (const nested of listFilesRecursive(path.join(dir, entry.name))) {
+                out.push(path.join(entry.name, nested));
+            }
+        }
+        else {
+            out.push(entry.name);
+        }
+    }
+    return out;
+}
+/**
+ * Whether <outDir> has an `npm run dev` script for the watch task to drive.
+ * The task is skipped when it doesn't (e.g. the monorepo root or hand-made
+ * projects), because a task referencing a missing script just errors on run.
+ */
+function hasDevScript(outDir) {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(outDir, 'package.json'), 'utf-8'));
+        const scripts = pkg.scripts;
+        return typeof scripts?.dev === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Copy the bundled extensions into <outDir>/.vscode/extensions/, then write the
+ * companion .vscode/extensions.json and — when the project has a `dev` watch
+ * script — the .vscode/tasks.json watch task. Returns the absolute paths
+ * written, or [] when the extension assets are missing (warns, never throws).
+ * `assetsRoot` overrides the bundled-asset location (tests).
+ */
+export function writeEditorIntegration(outDir, assetsRoot) {
+    const vscodeDir = path.join(outDir, '.vscode');
+    const extensionRoot = path.join(vscodeDir, 'extensions');
+    const root = assetsRoot ?? ASSETS_ROOT;
+    const written = [];
+    let copiedAny = false;
+    for (const ext of BUNDLED_EXTENSIONS) {
+        const src = path.join(root, ext.dir);
+        if (!fs.existsSync(path.join(src, 'package.json'))) {
+            console.warn(`! Editor integration: ${ext.dir} extension assets not found at ${src} — skipped`);
+            continue;
+        }
+        const dest = path.join(extensionRoot, ext.dir);
+        fs.mkdirSync(dest, { recursive: true });
+        fs.cpSync(src, dest, { recursive: true });
+        for (const rel of listFilesRecursive(dest))
+            written.push(path.join(dest, rel));
+        copiedAny = true;
+    }
+    if (!copiedAny)
+        return [];
+    const extensionsJsonPath = path.join(vscodeDir, 'extensions.json');
+    fs.writeFileSync(extensionsJsonPath, generateExtensionsJson(), 'utf-8');
+    written.push(extensionsJsonPath);
+    if (hasDevScript(outDir)) {
+        written.push(writeTasksJson(vscodeDir));
+    }
+    return written;
+}

package/dist/create/eslint-rules-template.d.ts

@@ -1,2 +1,2 @@
-import type { InitProjectOptions } from "./init-templates.js";
-export declare function generateEslintRules(_options: InitProjectOptions): string;
+import type { CreateProjectOptions } from "./templates.js";
+export declare function generateEslintRules(_options: CreateProjectOptions): string;

package/dist/create/framework-catalog.d.ts

@@ -53,6 +53,14 @@ export declare function frameworkTargetProfile(target: TargetProfileInput, frame
  * common framework is offered first in the prompt.
  */
 export declare function frameworksForTarget(target: BoardLike): FrameworkCatalogEntry[];
+/**
+ * Whether `frameworkId` is actually offered for `target`: compatible with the
+ * board's architecture AND installable. Auto-picking narrows via
+ * frameworksForTarget, but an explicit `--framework` bypasses that narrowing —
+ * callers accepting one must reject anything this returns false for (e.g.
+ * `--framework arduino` on the Zephyr-only xiao-nrf52840).
+ */
+export declare function frameworkCompatibleWithTarget(target: BoardLike, frameworkId: string): boolean;
 export type PackageManager = "npm" | "pnpm" | "yarn";
 /**
  * Detect the package manager for a directory. Priority:

package/dist/create/framework-catalog.js

@@ -21,7 +21,7 @@ export const FRAMEWORK_CATALOG = [
  * Architecture → compatible framework ids. Derived from each framework
  * package's framework.manifest.ts `profile.targets`:
  *   - arduino: avr, esp32 family, rp2040/rp2350, samd, stm32
- *   - zephyr:  nrf52 (xiao_ble), esp32, esp32s3
+ *   - zephyr:  nrf52 (xiao_ble), esp32 family (esp32, esp32s3, esp32c3, esp32c6)
  *   - native:  desktop only
  * Unknown embedded architectures fall back to [arduino] (the broadest core).
  */
@@ -30,11 +30,15 @@ const ARCHITECTURE_FRAMEWORKS = {
     esp32: ["arduino", "zephyr"],
     esp32s2: ["arduino"],
     esp32s3: ["arduino", "zephyr"],
-    esp32c3: ["arduino"],
-    esp32c6: ["arduino"],
+    esp32c3: ["arduino", "zephyr"],
+    esp32c6: ["arduino", "zephyr"],
     rp2040: ["arduino"],
     rp2350: ["arduino"],
     samd: ["arduino"],
+    // Per-chip key (esp32c3/c6 style). The generic 'stm32' entry stays
+    // ["arduino"] for future STM32duino support; the F411 Black Pill is
+    // Zephyr-only today.
+    stm32f411: ["zephyr"],
     stm32: ["arduino"],
     nrf52: ["zephyr"],
 };
@@ -66,8 +70,17 @@ const FRAMEWORK_TOOLCHAIN = {
 const ZEPHYR_BOARD_IDS = {
     "esp32-devkit": "esp32_devkitc/esp32/procpu",
     esp32s3: "esp32s3_devkitc/esp32s3/procpu",
-    // xiao_ble isn't currently a KNOWN_TARGETS entry, but keep the descriptor
-    // correct for completeness: nRF52840 (single core), base (non-sense) variant.
+    // Single-variant RISC-V board — the bare id is also accepted, but the
+    // qualified form is kept for consistency (verified against Zephyr 4.3
+    // boards/espressif/esp32c3_devkitm).
+    esp32c3: "esp32c3_devkitm/esp32c3",
+    // hpcore/lpcore cpucluster variants — the qualified form is required (the
+    // bare id is rejected); hpcore is the application core.
+    esp32c6: "esp32c6_devkitc/esp32c6/hpcore",
+    // First STM32 target — WeAct Black Pill V2.0 (STM32F411CEU6). Single
+    // variant; qualified for consistency with every other catalog target.
+    "blackpill-f411ce": "blackpill_f411ce/stm32f411xe",
+    // nRF52840 (single core), base (non-sense) variant.
     "xiao-nrf52840": "xiao_ble/nrf52840",
 };
 /**
@@ -105,6 +118,16 @@ export function frameworksForTarget(target) {
     // any id that has no catalog entry (defensive — keeps the prompt clean).
     return FRAMEWORK_CATALOG.filter((entry) => ids.includes(entry.id));
 }
+/**
+ * Whether `frameworkId` is actually offered for `target`: compatible with the
+ * board's architecture AND installable. Auto-picking narrows via
+ * frameworksForTarget, but an explicit `--framework` bypasses that narrowing —
+ * callers accepting one must reject anything this returns false for (e.g.
+ * `--framework arduino` on the Zephyr-only xiao-nrf52840).
+ */
+export function frameworkCompatibleWithTarget(target, frameworkId) {
+    return frameworksForTarget(target).some((f) => f.id === frameworkId && f.installable);
+}
 /**
  * Detect the package manager for a directory. Priority:
  *   1. package.json#packageManager field (the strongest signal, Corepack-style)

package/dist/create/index.d.ts

@@ -1,14 +1,15 @@
-export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
-export type { KnownTarget, KnownBoard, ScaffoldProjectResult } from './init-scaffold.js';
-export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
+export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printCreateNextSteps } from './scaffold.js';
+export type { KnownTarget, KnownBoard, ScaffoldProjectResult } from './scaffold.js';
+export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCompatibleWithTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
 export type { FrameworkCatalogEntry, BoardLike, PackageManager, FrameworkTargetProfile, TargetProfileInput } from './framework-catalog.js';
 export { installProjectDependencies, __setProjectInstallRunnerForTest } from './install-deps.js';
 export type { ProjectInstallResult } from './install-deps.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
-export type { InitProjectOptions } from './init-templates.js';
-export { runInitWizard } from './init-wizard.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEditorconfig, generateEslintConfig, } from './templates.js';
+export type { CreateProjectOptions } from './templates.js';
+export { runCreateWizard } from './wizard.js';
 export { generateFrameworkDebugArtifacts } from './debug-artifacts.js';
 export type { FrameworkDebugArtifactsOptions, FrameworkModuleLoader } from './debug-artifacts.js';
+export { generateExtensionsJson, generateTasksJson, watchBuildTask, writeEditorIntegration, bundledExtensionSourceDir, typecadUiExtensionSourceDir, TYPECAD_UI_EXTENSION_ID, TYPECAD_DEBUG_EXTENSION_ID, WATCH_TASK_LABEL, } from './editor-integration.js';
 export { scaffoldBoardPackages } from './board-codegen.js';
 export type { ScaffoldBoardResult } from './board-codegen.js';
 export { generateFrameworkChecklist } from './board-checklist.js';

package/dist/create/index.js

@@ -1,9 +1,10 @@
-export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printInitNextSteps } from './init-scaffold.js';
-export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
+export { scaffoldProject, normalizeProjectName, KNOWN_TARGETS, KNOWN_BOARDS, registerKnownTarget, printCreateNextSteps } from './scaffold.js';
+export { FRAMEWORK_CATALOG, frameworksForTarget, frameworkCompatibleWithTarget, frameworkCatalogEntry, detectPackageManager, frameworkTargetProfile } from './framework-catalog.js';
 export { installProjectDependencies, __setProjectInstallRunnerForTest } from './install-deps.js';
-export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEslintConfig, } from './init-templates.js';
-export { runInitWizard } from './init-wizard.js';
+export { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEditorconfig, generateEslintConfig, } from './templates.js';
+export { runCreateWizard } from './wizard.js';
 export { generateFrameworkDebugArtifacts } from './debug-artifacts.js';
+export { generateExtensionsJson, generateTasksJson, watchBuildTask, writeEditorIntegration, bundledExtensionSourceDir, typecadUiExtensionSourceDir, TYPECAD_UI_EXTENSION_ID, TYPECAD_DEBUG_EXTENSION_ID, WATCH_TASK_LABEL, } from './editor-integration.js';
 // Board codegen tool (`cuttlefish board add`)
 export { scaffoldBoardPackages } from './board-codegen.js';
 export { generateFrameworkChecklist } from './board-checklist.js';

package/dist/create/{init-scaffold.d.ts → scaffold.d.ts}

@@ -1,5 +1,5 @@
 import type { ArchitectureIdentifier } from "../api/index.js";
-import type { InitProjectOptions } from "./init-templates.js";
+import type { CreateProjectOptions } from "./templates.js";
 export interface KnownTarget {
     id: string;
     displayName: string;
@@ -28,10 +28,10 @@ export declare function normalizeProjectName(name: string): string;
 export interface ScaffoldProjectResult {
     createdFiles: string[];
     outDir: string;
-    options: InitProjectOptions;
+    options: CreateProjectOptions;
 }
-export declare function scaffoldProject(options: InitProjectOptions, outDir?: string): ScaffoldProjectResult;
-export declare function printInitNextSteps(options: InitProjectOptions, outDir: string, opts?: {
+export declare function scaffoldProject(options: CreateProjectOptions, outDir?: string): ScaffoldProjectResult;
+export declare function printCreateNextSteps(options: CreateProjectOptions, outDir: string, opts?: {
     installed?: boolean;
     debugProfile?: boolean;
 }): void;

package/dist/create/{init-scaffold.js → scaffold.js}

@@ -1,8 +1,9 @@
 import path from "node:path";
 import fs from "node:fs";
 import chalk from "chalk";
-import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateBoardForwardingFile, generateEslintConfig, } from "./init-templates.js";
+import { generateProjectPackageJson, generateProjectTsconfig, generateProjectConfig, generateProjectEnvDts, generateStarterSketch, generateStarterTest, generateStarterSim, generateGitignore, generateEditorconfig, generateBoardForwardingFile, generateEslintConfig, } from "./templates.js";
 import { generateEslintRules } from "./eslint-rules-template.js";
+import { writeEditorIntegration } from "./editor-integration.js";
 const _knownTargets = [
     {
         id: 'native',
@@ -74,6 +75,28 @@ const _knownTargets = [
         buildTarget: 'rp2040:rp2040:rpipico2',
         mcu: 'rp2350',
     },
+    {
+        id: 'xiao-nrf52840',
+        displayName: 'XIAO nRF52840',
+        isNative: false,
+        architecture: 'nrf52',
+        boardPackage: '@typecad/board-xiao-nrf52840',
+        // Zephyr-only target: the build target is the `west build -b` board id,
+        // not an Arduino FQBN (frameworkTargetProfile resolves it for Zephyr).
+        buildTarget: 'xiao_ble/nrf52840',
+        mcu: 'nrf52840',
+    },
+    {
+        id: 'blackpill-f411ce',
+        displayName: 'Black Pill (STM32F411)',
+        isNative: false,
+        architecture: 'stm32f411',
+        boardPackage: '@typecad/board-blackpill-f411ce',
+        // Zephyr-only target: the build target is the `west build -b` board id,
+        // not an Arduino FQBN (frameworkTargetProfile resolves it for Zephyr).
+        buildTarget: 'blackpill_f411ce/stm32f411xe',
+        mcu: 'stm32f411',
+    },
 ];
 export function registerKnownTarget(target) {
     const existing = _knownTargets.findIndex(t => t.id === target.id);
@@ -125,6 +148,11 @@ export function scaffoldProject(options, outDir) {
     writeFile('.cuttlefish/eslint.config.mjs', generateEslintConfig(options));
     writeFile('.cuttlefish/eslint-transpiler-rules.mjs', generateEslintRules(options));
     writeFile('.gitignore', generateGitignore(options));
+    writeFile('.editorconfig', generateEditorconfig(options));
+    // Editor integration: workspace-bundled VS Code extension for .ui syntax
+    // highlighting (best-effort — warns and skips if the assets are missing).
+    for (const file of writeEditorIntegration(resolvedOutDir))
+        createdFiles.push(file);
     if (options.boardPackage) {
         const boardFilePath = path.join(cuttlefishDir, 'board.ts');
         fs.writeFileSync(boardFilePath, generateBoardForwardingFile(options.boardPackage), 'utf-8');
@@ -156,7 +184,7 @@ export function scaffoldProject(options, outDir) {
     }
     return { createdFiles, outDir: resolvedOutDir, options };
 }
-export function printInitNextSteps(options, outDir, opts = {}) {
+export function printCreateNextSteps(options, outDir, opts = {}) {
     const relativeDir = path.relative(process.cwd(), outDir) || '.';
     console.log();
     console.log(chalk.cyan(`⤳ Cuttlefish`));
@@ -173,6 +201,9 @@ export function printInitNextSteps(options, outDir, opts = {}) {
         console.log(chalk.bold.white("To debug (VS Code):"));
         console.log(`  ${chalk.cyan("open the folder and press F5")} ${chalk.dim("(builds + flashes, then attaches GDB)")}`);
     }
+    console.log();
+    console.log(chalk.bold.white("To edit .ui files (VS Code):"));
+    console.log(`  ${chalk.cyan("open the folder and approve the workspace extension")} ${chalk.dim("(adds .ui syntax highlighting)")}`);
     if (!options.isNative) {
         const portHint = process.platform === 'win32' ? 'COM4' : '/dev/ttyACM0';
         console.log();

package/dist/create/templates.d.ts

@@ -0,0 +1,29 @@
+import type { ArchitectureIdentifier } from '../api/index.js';
+export interface CreateProjectOptions {
+    projectName: string;
+    targetId: string;
+    targetDisplayName: string;
+    isNative: boolean;
+    architecture?: ArchitectureIdentifier;
+    boardPackage?: string;
+    frameworkPackage: string;
+    framework: string;
+    buildTarget?: string;
+    mcu?: string;
+    baudRate?: number;
+    includeSketch: boolean;
+    toolchainType?: string;
+    /** Extra frameworkData fields (e.g. `{ target: 'esp32s3' }` for framework-esp32). */
+    frameworkData?: Record<string, unknown>;
+}
+export declare function generateProjectPackageJson(options: CreateProjectOptions): string;
+export declare function generateProjectTsconfig(options: CreateProjectOptions): string;
+export declare function generateProjectConfig(options: CreateProjectOptions): string;
+export declare function generateProjectEnvDts(options: CreateProjectOptions): string;
+export declare function generateStarterSketch(options: CreateProjectOptions): string;
+export declare function generateStarterTest(_options: CreateProjectOptions): string;
+export declare function generateStarterSim(options: CreateProjectOptions): string;
+export declare function generateBoardForwardingFile(boardPackage: string): string;
+export declare function generateGitignore(_options: CreateProjectOptions): string;
+export declare function generateEditorconfig(_options: CreateProjectOptions): string;
+export declare function generateEslintConfig(_options: CreateProjectOptions): string;

package/dist/create/{init-templates.js → templates.js}

@@ -557,6 +557,21 @@ dist/
 .cuttlefish/eslint-transpiler-rules.mjs
 `;
 }
+export function generateEditorconfig(_options) {
+    return `# Auto-generated by 'cuttlefish create'. Edit to customise your build.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{ts,js,mjs,cjs,json,css,ui,md,yml}]
+indent_style = space
+indent_size = 2
+`;
+}
 export function generateEslintConfig(_options) {
     // `no-restricted-syntax` selectors are generated from LINT_RULES
     // (packages/cuttlefish/src/ir/feature-registry.ts), the single source of

package/dist/create/wizard.d.ts

@@ -0,0 +1,8 @@
+import type { CreateProjectOptions } from "./templates.js";
+export declare function runCreateWizard(partialOptions?: {
+    projectName?: string;
+    board?: string;
+    framework?: string;
+    baud?: number;
+    noSketch?: boolean;
+}): Promise<CreateProjectOptions | null>;

package/dist/create/{init-wizard.js → wizard.js}

@@ -1,8 +1,8 @@
 import * as readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import chalk from "chalk";
-import { KNOWN_TARGETS } from "./init-scaffold.js";
-import { frameworksForTarget, frameworkCatalogEntry, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./framework-catalog.js";
+import { KNOWN_TARGETS } from "./scaffold.js";
+import { frameworksForTarget, frameworkCatalogEntry, frameworkCompatibleWithTarget, FRAMEWORK_CATALOG, frameworkTargetProfile } from "./framework-catalog.js";
 function validateProjectName(name) {
     if (!name || name.trim().length === 0) {
         return "Project name cannot be empty.";
@@ -53,7 +53,7 @@ async function promptConfirm(rl, prompt, defaultValue) {
         return defaultValue;
     return trimmed === "y" || trimmed === "yes";
 }
-export async function runInitWizard(partialOptions) {
+export async function runCreateWizard(partialOptions) {
     const rl = readline.createInterface({ input, output });
     try {
         console.log();
@@ -101,9 +101,16 @@ export async function runInitWizard(partialOptions) {
         if (partialOptions?.framework) {
             const requested = frameworkCatalogEntry(partialOptions.framework);
             if (!requested) {
-                const available = FRAMEWORK_CATALOG.filter((f) => f.installable).map((f) => f.id).join(", ");
+                const available = FRAMEWORK_CATALOG.filter(f => f.installable).map(f => f.id).join(", ");
                 throw new Error(`Unknown framework '${partialOptions.framework}'. Available: ${available}`);
             }
+            // Same compatibility guard as the non-interactive CLI path: a preseeded
+            // --framework bypasses the narrowing below, so validate it explicitly.
+            if (!frameworkCompatibleWithTarget(target, requested.id)) {
+                const list = compatible.map(f => f.id).join(", ");
+                throw new Error(`Framework '${requested.id}' is not compatible with target '${target.id}' (${target.displayName}). ` +
+                    `Compatible frameworks: ${list}`);
+            }
             framework = requested.id;
             frameworkPackage = requested.packageName;
             console.log(`${chalk.cyan("?")} Framework: ${chalk.white(requested.label)}`);

package/dist/emit/emitters/setup.js

@@ -5,6 +5,7 @@ import { analyzeProgram } from "../../ir/program-analysis.js";
 import { collectStatementIdentifiers } from "../../ir/identifier-collector.js";
 import { ensureDir } from "../../utils/fs.js";
 import { resolveImport } from "../../libdef/registry.js";
+import { isRegisteredCuttlefishLibrary } from "../../library-packages.js";
 import { emitPolyfillBoilerplate } from "../native-helpers-emitter.js";
 import { resolveStrategy } from "../../platform/registry.js";
 import { buildCoopSchedulerPolyfill } from "../../platform/coop-scheduler-runtime.js";
@@ -547,6 +548,14 @@ export function buildEmitterContext(program, options) {
         if (!programAnalysis.usesPreferences) {
             shimLines = filterShimBlock(shimLines, '// CUTTLEFISH_PREFERENCES_BEGIN', '// CUTTLEFISH_PREFERENCES_END');
         }
+        // Entry-TU marker for framework shims: the UI runtime header (ui_tick) is
+        // emitted ONLY into the entry file (emitUIRuntime gates on isEntryFile), so
+        // shim helpers that keep the UI alive during bounded blocking waits (e.g.
+        // Zephyr's wifi connect) must compile those calls down everywhere else.
+        // Defined before the shim lines land in the preamble, after all filters.
+        if (isEntryFile && entryHasUI() && shimLines.length > 0) {
+            shimLines.unshift("#define CUTTLEFISH_ENTRY_UI_TU 1");
+        }
         profileDiagnostics = [...strategy.profileDiagnostics(program, options.platformContext)];
     }
     for (const imported of program.imports) {
@@ -554,6 +563,19 @@ export function buildEmitterContext(program, options) {
         // named imports — add it to the symbolMap so cross-module references
         // resolve. Demo #12 Finding C — was skipped, so `encode` wasn't declared.
         const defaultName = imported.defaultImportName;
+        // Cuttlefish library packages: the import emits the shim-header include
+        // (resolved through the libdef registry from the library manifest) and
+        // contributes native shims + build fragments. This must run BEFORE the
+        // SDK skip below — @typecad-scoped libraries would otherwise be treated
+        // as type-level-only like the rest of the SDK.
+        if (isRegisteredCuttlefishLibrary(imported.moduleSpecifier)) {
+            const resolved = resolveImport(imported, options.libdefs, options.target, options.platformContext, program.fileName);
+            includes.push(normalizeInclude(resolved.include));
+            Object.assign(symbolMap, resolved.symbolMap);
+            if (defaultName)
+                symbolMap[defaultName] = defaultName;
+            continue;
+        }
         if (isCuttlefishSDKImport(imported.moduleSpecifier, program.fileName)) {
             for (const symbol of imported.namedImports) {
                 symbolMap[symbol] = symbol;