@glasshome/widget-cli 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glasshome/widget-cli",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "CLI for creating and managing GlassHome widgets",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "scripts": {
     "cli": "bun bin/cli.ts",
+    "test": "bun test",
     "typecheck": "tsc --noEmit"
   },
   "files": [
@@ -19,16 +20,17 @@
     "@iconify/types": "^2.0.0",
     "@types/bun": "latest",
     "@types/semver": "^7.0.0",
-    "playwright": "^1.40.0"
+    "playwright": "^1.40.0",
+    "typescript": "^5"
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
     "@fontsource-variable/caveat": "^5.2.8",
     "@fontsource-variable/geist": "^5.2.9",
     "@fontsource-variable/geist-mono": "^5.2.8",
-    "@glasshome/sync-layer": "0.4.0",
+    "@glasshome/sync-layer": "0.5.0",
     "@glasshome/widget-contract": "0.2.0",
-    "@glasshome/widget-sdk": "1.7.0",
+    "@glasshome/widget-sdk": "1.9.0",
     "@iconify-json/lucide": "^1.2.0",
     "@iconify-json/mdi": "^1.2.3",
     "@tailwindcss/vite": "^4.1.13",

package/src/commands/add.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { cancel, isCancel, log, text } from "@clack/prompts";
+import { defaultSdkRange, FALLBACK_SDK_RANGE } from "../utils/sdk-version";
 
 /** Capitalize kebab-case into PascalCase for component names. */
 function capitalize(str: string): string {
@@ -30,20 +31,30 @@ export function scaffoldWidget(
   const displayName = capitalize(widgetName);
   const widgetDescription = description || `A GlassHome dashboard widget: ${widgetName}`;
 
+  // The range the host checks before mounting, derived from the SDK this
+  // project actually builds against. Hardcoding it produced widgets that
+  // declared a 0.2-era range while running on 1.x, which reads as "pre-1.0" to
+  // `requiresCapabilities` and quietly excused them from declaring capabilities.
+  const sdkRange = defaultSdkRange(cwd) ?? FALLBACK_SDK_RANGE;
+
   // Read index.tsx template from the template directory
   const templateDir = resolve(import.meta.dir, "../../template");
   let srcContent = readFileSync(resolve(templateDir, "src/index.tsx.template"), "utf-8");
   srcContent = srcContent.replace(/WIDGET_NAME/g, displayName);
+  srcContent = srcContent.replace(/SDK_RANGE/g, sdkRange);
   writeFileSync(resolve(widgetDir, "index.tsx"), srcContent);
 
-  // Generate manifest.json
+  // Generate manifest.json. `capabilities` is required for any SDK >= 1.0.0
+  // range and an empty array is the honest default: a fresh widget reads
+  // nothing from Home Assistant, and the declaration is what consent shows.
   const manifest = {
     name: displayName,
     description: widgetDescription,
     minSize: { w: 1, h: 1 },
     maxSize: { w: 4, h: 4 },
     defaultSize: { w: 2, h: 2 },
-    sdkVersion: "^0.2.0",
+    sdkVersion: sdkRange,
+    capabilities: [],
     version: "0.1.0",
   };
   writeFileSync(resolve(widgetDir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);

package/src/commands/build.ts

@@ -2,8 +2,15 @@ import { log, spinner } from "@clack/prompts";
 import { buildWidgets } from "@glasshome/widget-sdk/vite";
 import { lintAndReport } from "../utils/lint-source";
 import { withQuietStdout } from "../utils/quiet";
+import { typecheckAndReport } from "../utils/typecheck";
 
 export async function runBuild(cwd: string): Promise<void> {
+  const check = spinner();
+  check.start("Checking types...");
+  const typesOk = typecheckAndReport(cwd);
+  check.stop(typesOk ? "Types checked" : "Typecheck failed");
+  if (!typesOk) process.exit(1);
+
   const s = spinner();
   s.start("Building widgets...");
 

package/src/commands/create.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join, resolve } from "node:path";
 import { cancel, confirm, isCancel, log, note, spinner, text } from "@clack/prompts";
 import color from "picocolors";
+import { defaultSdkRange, FALLBACK_SDK_RANGE } from "../utils/sdk-version";
 import { getCliVersion } from "../utils/version";
 import { promptWidgetDetails, scaffoldWidget } from "./add";
 
@@ -125,6 +126,9 @@ export async function runCreate() {
     pkgContent = pkgContent.replace(/PROJECT_NAME/g, projectName as string);
     pkgContent = pkgContent.replace(/PROJECT_DESCRIPTION/g, projectDesc);
     pkgContent = pkgContent.replace(/CLI_VERSION/g, `^${getCliVersion()}`);
+    // Nothing is installed yet, so this comes from the SDK the CLI ships
+    // against. `bun widget upgrade` re-syncs it and every manifest later.
+    pkgContent = pkgContent.replace(/SDK_RANGE/g, defaultSdkRange() ?? FALLBACK_SDK_RANGE);
     writeFileSync(pkgPath, pkgContent);
 
     // Replace project-level placeholders in README.md

package/src/commands/preview.ts

@@ -43,46 +43,55 @@ export async function runPreview(cwd: string, names: string[], isolate: boolean)
     process.exit(1);
   }
 
-  log.success(`Captured ${summary.shots} shot(s) across ${summary.widgets} widget(s)`);
-
-  if (summary.skipped.length) {
-    log.info(`No examples (skipped): ${summary.skipped.join(", ")}`);
-  }
-
-  const network = summary.failures.filter((f) => f.kind === "network");
   const hangs = summary.failures.filter((f) => f.kind === "hang");
   const integrity = summary.failures.filter((f) => f.kind === "integrity");
+  const networkWidgets = [
+    ...new Set(summary.failures.filter((f) => f.kind === "network").map((f) => f.widget)),
+  ];
+  const attempted = summary.shots + hangs.length;
 
-  // Nothing can actually leave — DNS is blackholed. These are blocked attempts,
-  // i.e. what each widget wanted from the network and must degrade without.
-  if (network.length) {
-    log.warn(
-      `NETWORK: ${network.length} blocked request(s) — all denied, none left the machine\n` +
-        network.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
-    );
+  // Headline: plain count of what landed in preview/. A miss only matters if a
+  // render could not complete (hangs) or a bundle changed under us (integrity).
+  const out = color.cyan("preview/");
+  if (hangs.length || integrity.length) {
+    log.warn(`Rendered ${summary.shots} of ${attempted} previews into ${out}`);
   } else {
-    log.success("NETWORK: no widget attempted to reach the network");
+    log.success(`Rendered ${summary.shots} previews (light + dark) into ${out}`);
   }
 
+  if (summary.skipped.length) {
+    log.message(color.dim(`No examples to render: ${summary.skipped.join(", ")}`));
+  }
+
+  // Real miss: a render still too slow after one retry. Its slot is left without
+  // a PNG; everything else rendered.
   if (hangs.length) {
-    log.error(
-      `RENDER: ${hangs.length} render(s) failed or timed out\n` +
-        hangs.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
+    log.warn(
+      `Too slow to render, even after a retry (no image written):\n` +
+        hangs.map((f) => `  · ${f.widget}  ${f.detail}`).join("\n"),
     );
-  } else {
-    log.success("RENDER: every render settled inside the timeout");
   }
 
+  // Should never happen: a bundle's bytes changed mid-run. This is a real
+  // problem, not a slow render.
   if (integrity.length) {
     log.error(
-      `INTEGRITY: ${integrity.length} widget(s) changed after pinning\n` +
-        integrity.map((f) => `  ${f.widget}  ${f.detail}`).join("\n"),
+      `A bundle changed while rendering (report this):\n` +
+        integrity.map((f) => `  · ${f.widget}`).join("\n"),
     );
-  } else {
-    log.success("INTEGRITY: every bundle matched its pinned hash");
   }
 
-  log.info(`Previews written to ${color.cyan("preview/")}`);
+  // Informational, not a failure: some widgets have no offline data and reach
+  // for the network. The request is blocked and nothing leaves the machine; the
+  // widget renders a placeholder. Expected for camera; worth a glance if another
+  // widget shows up here.
+  if (networkWidgets.length) {
+    log.message(
+      color.dim(
+        `Used a placeholder (no offline data; network blocked, nothing left the machine): ${networkWidgets.join(", ")}`,
+      ),
+    );
+  }
 
   // Vite's dev server leaves live handles behind (file watchers, keep-alive
   // sockets from browsers that crashed mid-render), so the process would sit

package/src/commands/publish.ts

@@ -12,6 +12,7 @@ import {
   readManifest,
   writeManifest,
 } from "../utils/manifest";
+import { typecheckAndReport } from "../utils/typecheck";
 import { enforceCliVersion } from "../utils/version";
 import { runLogin } from "./login";
 
@@ -28,13 +29,7 @@ export async function runPublish(
 ): Promise<void> {
   const s = spinner();
 
-  // Step 1: Validate (quiet)
   const { runValidate } = await import("./validate");
-  const valid = await runValidate(cwd, undefined, { quiet: true });
-  if (!valid) {
-    log.error("Fix validation errors before publishing.");
-    process.exit(1);
-  }
 
   // Step 2: Authenticate
   const hubUrl = hubUrlOverride ?? getHubUrl();
@@ -167,7 +162,17 @@ export async function runPublish(
     writeManifest(cwd, widgetName, manifest);
   }
 
-  // Step 6: Build (async so spinner animates)
+  // Step 6: Typecheck, then build (async so spinner animates).
+  //
+  // Checked here rather than left to the project's own build script: a project
+  // scaffolded before the template ran tsc builds with a bare `vite build`, and
+  // publishing is the irreversible step. A project whose build already
+  // typechecks just pays it twice, which is cheap next to a bad publish.
+  s.start("Checking types...");
+  const typesOk = typecheckAndReport(cwd);
+  s.stop(typesOk ? "Types checked" : "Typecheck failed");
+  if (!typesOk) process.exit(1);
+
   s.start("Building widget...");
   const buildProc = Bun.spawn(["bun", "run", "build"], { cwd, stdout: "pipe", stderr: "pipe" });
   const buildExit = await buildProc.exited;
@@ -179,6 +184,15 @@ export async function runPublish(
   }
   s.stop("Build complete");
 
+  // Validate AFTER the build, not before: the build is what produces the
+  // manifest and bundle that get published, so validating beforehand checks a
+  // different document than the one that ships.
+  const valid = await runValidate(cwd, undefined, { quiet: true });
+  if (!valid) {
+    log.error("Fix validation errors before publishing.");
+    process.exit(1);
+  }
+
   // Step 7: Publish
   const distPath = resolve(cwd, "dist", `${widgetName}.js`);
 

package/src/commands/upgrade.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { log, note, spinner } from "@clack/prompts";
 import { discoverWidgets, readManifest, writeManifest } from "../utils/manifest";
+import { getInstalledSdkVersion } from "../utils/sdk-version";
 import { runValidate } from "./validate";
 
 /** Walk up from cwd looking for a package.json with a `workspaces` field. */
@@ -121,16 +122,30 @@ export async function runUpgrade(cwd: string): Promise<void> {
     } else {
       log.warn(`Synced to ${sdkVersion} but validation has warnings/errors. Check above.`);
     }
+    return;
+  }
+
+  // Standalone project. Bumping the dependency is still the author's call, but
+  // syncing the manifests to whatever is installed is not: a manifest range
+  // that excludes the installed SDK fails validation, and this is the command
+  // that error tells people to run.
+  const installed = getInstalledSdkVersion(cwd);
+  if (installed) {
+    syncManifestSdkVersions(cwd, installed);
+    const valid = await runValidate(cwd);
+    if (!valid) log.warn(`Synced manifests to ${installed}, but validation found problems above.`);
   } else {
-    log.info("Not inside the widget workspace. Upgrade @glasshome/widget-sdk manually:");
-    note(
-      [
-        "1. Bump @glasshome/widget-sdk in package.json peerDependencies",
-        "2. bun install",
-        "3. bun widget upgrade   (sync manifest files)",
-        "4. bun widget validate  (check compatibility)",
-      ].join("\n"),
-      "To upgrade",
-    );
+    log.warn("No @glasshome/widget-sdk installed here, so manifests were left alone.");
   }
+
+  log.info("To move to a different SDK version:");
+  note(
+    [
+      "1. Bump @glasshome/widget-sdk in package.json peerDependencies",
+      "2. bun install",
+      "3. bun widget upgrade   (sync manifest files)",
+      "4. bun widget validate  (check compatibility)",
+    ].join("\n"),
+    "To upgrade",
+  );
 }

package/src/commands/validate.ts

@@ -5,6 +5,7 @@ import {
   formatSchemaError,
   publishManifestSchema,
   requiresCapabilities,
+  satisfiesSdk,
 } from "@glasshome/widget-contract";
 import semver from "semver";
 import {
@@ -15,7 +16,7 @@ import {
   readRegistry,
   type WidgetManifest,
 } from "../utils/manifest";
-import { getProjectSdkVersion } from "../utils/version";
+import { getInstalledSdkVersion } from "../utils/sdk-version";
 
 interface ValidationResult {
   passed: boolean;
@@ -23,7 +24,7 @@ interface ValidationResult {
   warnings: string[];
 }
 
-function validateManifest(manifest: WidgetManifest): ValidationResult {
+function validateManifest(manifest: WidgetManifest, installedSdk: string | null): ValidationResult {
   const errors: string[] = [];
   const warnings: string[] = [];
   const hasValidMinSize =
@@ -47,6 +48,23 @@ function validateManifest(manifest: WidgetManifest): ValidationResult {
     }
   }
 
+  // The range must admit the SDK actually resolved in node_modules. Comparing
+  // it against the range declared in package.json only compares a claim with
+  // itself: both said "^0.2.0" while the build ran on 1.7.0, and it passed.
+  // An error, not a warning: a pre-1.0 range also excuses the widget from
+  // declaring capabilities, so a stale one silently leaves the 1.x contract.
+  if (
+    installedSdk &&
+    manifest.sdkVersion &&
+    manifest.sdkVersion !== "*" &&
+    semver.validRange(manifest.sdkVersion) &&
+    !satisfiesSdk(installedSdk, manifest.sdkVersion)
+  ) {
+    errors.push(
+      `sdkVersion "${manifest.sdkVersion}" excludes the installed SDK ${installedSdk}, so it claims a compatibility it was not built for; run \`bun widget upgrade\``,
+    );
+  }
+
   // INS-05: "*" sdkVersion is rejected at publish time, authors must declare
   // a real range (e.g. "^0.3.0"). Installed widgets that already ship "*" are
   // still tolerated by the loader with a warn-and-mount, but new publishes
@@ -157,8 +175,7 @@ export async function runValidate(
 
   const failed: string[] = [];
 
-  // Manifest sdkVersion range must admit the pinned SDK, else it lies about compatibility.
-  const projectSdk = getProjectSdkVersion(cwd);
+  const installedSdk = getInstalledSdkVersion(cwd);
 
   for (const name of toValidate) {
     if (!quiet) log.step(name);
@@ -175,7 +192,7 @@ export async function runValidate(
       continue;
     }
 
-    const result = validateManifest(manifest);
+    const result = validateManifest(manifest, installedSdk);
 
     if (result.errors.length > 0) {
       for (const err of result.errors) {
@@ -189,19 +206,6 @@ export async function runValidate(
       }
     }
 
-    if (
-      !quiet &&
-      projectSdk &&
-      manifest.sdkVersion &&
-      manifest.sdkVersion !== "*" &&
-      semver.validRange(manifest.sdkVersion) &&
-      !semver.satisfies(projectSdk, manifest.sdkVersion)
-    ) {
-      log.warn(
-        `  - manifest sdkVersion "${manifest.sdkVersion}" excludes the installed SDK ${projectSdk}; run \`bun widget upgrade\``,
-      );
-    }
-
     // Check bundle exists
     const bundlePath = resolve(cwd, "dist", `${name}.js`);
     if (!existsSync(bundlePath)) {

package/src/preview/capture.ts

@@ -202,8 +202,8 @@ export async function runPreview(opts: PreviewOptions): Promise<PreviewSummary>
               for (const a of lock.attempts) widgetAttempts.add(a);
             };
 
-            try {
-              await withRenderTimeout(`${widget} / ${label} / ${theme}`, async () => {
+            const attempt = () =>
+              withRenderTimeout(`${widget} / ${label} / ${theme}`, async () => {
                 if (shared) {
                   const page = await shared.newPage();
                   try {
@@ -220,17 +220,22 @@ export async function runPreview(opts: PreviewOptions): Promise<PreviewSummary>
                   await withFreshBrowser(shoot);
                 }
               });
-              shot++;
-            } catch (err) {
-              failures.push({
-                widget,
-                kind: "hang",
-                detail: `${label}/${theme}: ${err instanceof Error ? err.message : String(err)}`,
-              });
-              // A timed-out render leaves the browser wedged; drop it so the next
-              // shot starts clean instead of cascading into more timeouts.
-              await shared?.recycle().catch(() => {});
+
+            // Two tries. A render that crosses 30s is usually a heavy widget
+            // flaking under load, not a real failure: recycle (the wedged
+            // browser is why it stalled) and give it one clean retry before
+            // recording a miss.
+            let ok = false;
+            for (let tries = 0; tries < 2 && !ok; tries++) {
+              try {
+                await attempt();
+                ok = true;
+              } catch {
+                await shared?.recycle().catch(() => {});
+              }
             }
+            if (ok) shot++;
+            else failures.push({ widget, kind: "hang", detail: `${label} (${theme})` });
           }
         }
 

package/src/preview/harness/harness.tsx

@@ -155,7 +155,6 @@ async function main(): Promise<void> {
   stage.style.height = `${height}px`;
 
   const ctx: ReactiveWidgetContext = {
-    isEditMode: () => false,
     updateConfig: () => {},
     dimensions: () => ({ width, height }),
   };

package/src/utils/resolution.ts

@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+
+/**
+ * Whether a resolved module path is bun's global install cache rather than a
+ * real install.
+ *
+ * With a package absent, bun still resolves its bare name, from
+ * `~/.bun/install/cache/typescript@7.0.2@@@1/`. Tools that shell out to what
+ * they resolved would then run a version the project never installed.
+ *
+ * Testing for a `node_modules` segment instead looks equivalent and is not: in
+ * a workspace, `@glasshome/widget-sdk` resolves through a symlink to its real
+ * source directory, which has no such segment, so that test rejects the very
+ * install it should accept and the guard silently does nothing.
+ */
+export function isBunGlobalCache(modulePath: string): boolean {
+  const cacheDir =
+    process.env.BUN_INSTALL_CACHE_DIR ??
+    join(process.env.BUN_INSTALL ?? join(homedir(), ".bun"), "install", "cache");
+  return resolve(modulePath).startsWith(resolve(cacheDir) + sep);
+}

package/src/utils/sdk-version.test.ts

@@ -0,0 +1,85 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { isBunGlobalCache } from "./resolution";
+import { bareVersion, defaultSdkRange, getInstalledSdkVersion } from "./sdk-version";
+
+const tmpDir = mkdtempSync(join(tmpdir(), "glasshome-sdk-version-"));
+
+afterAll(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+let fixtureCount = 0;
+
+/** A fake installed SDK, either under node_modules or as a workspace symlink
+    to a source tree, which is how a monorepo actually resolves it. */
+function project(opts: { version?: string; asWorkspaceLink?: boolean }): string {
+  const dir = join(tmpDir, `project-${fixtureCount++}`);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture" }));
+
+  if (opts.version) {
+    const target = opts.asWorkspaceLink
+      ? join(dir, "packages", "widget-sdk")
+      : join(dir, "node_modules", "@glasshome", "widget-sdk");
+    mkdirSync(target, { recursive: true });
+    writeFileSync(
+      join(target, "package.json"),
+      JSON.stringify({ name: "@glasshome/widget-sdk", version: opts.version }),
+    );
+    if (opts.asWorkspaceLink) {
+      mkdirSync(join(dir, "node_modules", "@glasshome"), { recursive: true });
+      symlinkSync(target, join(dir, "node_modules", "@glasshome", "widget-sdk"), "dir");
+    }
+  }
+  return dir;
+}
+
+describe("getInstalledSdkVersion", () => {
+  test("reads the version from a normal install", () => {
+    expect(getInstalledSdkVersion(project({ version: "1.8.1" }))).toBe("1.8.1");
+  });
+
+  test("reads it through a workspace symlink to a source tree", () => {
+    // Regression: an earlier version required a `node_modules` segment in the
+    // resolved path. A workspace symlink resolves to the SDK's real source
+    // directory, which has none, so the check returned null and every guard
+    // built on it silently did nothing in the monorepo.
+    expect(getInstalledSdkVersion(project({ version: "1.7.0", asWorkspaceLink: true }))).toBe(
+      "1.7.0",
+    );
+  });
+
+  test("returns null when no SDK is installed", () => {
+    // Must not fall back to bun's global cache copy.
+    expect(getInstalledSdkVersion(project({}))).toBeNull();
+  });
+});
+
+describe("defaultSdkRange", () => {
+  test("carets the installed version", () => {
+    expect(defaultSdkRange(project({ version: "1.8.1" }))).toBe("^1.8.1");
+  });
+
+  test("falls back to the SDK this CLI ships against", () => {
+    // No project SDK, so it must still produce a 1.x range rather than nothing:
+    // a pre-1.0 range would excuse the widget from declaring capabilities.
+    const range = defaultSdkRange(project({}));
+    expect(range).toMatch(/^\^\d+\.\d+\.\d+/);
+    expect(bareVersion(range as string).startsWith("0.")).toBe(false);
+  });
+});
+
+describe("isBunGlobalCache", () => {
+  test("recognises the cache directory", () => {
+    const cache = join(tmpDir, "cache");
+    process.env.BUN_INSTALL_CACHE_DIR = cache;
+    expect(isBunGlobalCache(join(cache, "typescript@7.0.2@@@1", "package.json"))).toBe(true);
+    expect(isBunGlobalCache(join(tmpDir, "node_modules", "typescript", "package.json"))).toBe(
+      false,
+    );
+    delete process.env.BUN_INSTALL_CACHE_DIR;
+  });
+});

package/src/utils/sdk-version.ts

@@ -0,0 +1,76 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { isBunGlobalCache } from "./resolution";
+
+/**
+ * The SDK a widget actually builds against.
+ *
+ * `@glasshome/widget-sdk` is host-provided (`HOST_PROVIDED_MODULES`), so the
+ * build externalizes it and the published bundle runs against whatever SDK the
+ * host serves. That is why `manifest.sdkVersion` exists: it is the range the
+ * host checks before mounting. It must be derived from, and checked against,
+ * the SDK really resolved here — comparing it to the range declared in
+ * package.json only ever compares a claim with itself.
+ */
+
+const SDK_PKG = "@glasshome/widget-sdk";
+
+/**
+ * Last resort when neither the project nor this CLI can be read. Deliberately a
+ * 1.x range: anything below 1.0.0 excuses a widget from declaring capabilities,
+ * so a wrong-but-modern default fails loudly instead of silently opting out of
+ * the security contract.
+ */
+export const FALLBACK_SDK_RANGE = "^1.0.0";
+
+/**
+ * Version of the installed SDK, or null when none is installed.
+ *
+ * An ancestor's `node_modules` is fine and expected (hoisted installs put it
+ * there), as is a workspace symlink resolving to the SDK's own source tree.
+ * Bun's global install cache is not: with nothing installed it still resolves
+ * the bare name, and that is not what the build would use.
+ */
+export function getInstalledSdkVersion(cwd: string): string | null {
+  try {
+    const require = createRequire(join(cwd, "package.json"));
+    const pkgPath = resolve(require.resolve(`${SDK_PKG}/package.json`));
+    if (isBunGlobalCache(pkgPath)) return null;
+    const version = JSON.parse(readFileSync(pkgPath, "utf-8")).version;
+    return typeof version === "string" ? version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The SDK this CLI itself was built against, used when scaffolding a project
+ * that has nothing installed yet.
+ */
+export function getCliSdkVersion(): string | null {
+  try {
+    const pkgPath = resolve(import.meta.dir, "../../package.json");
+    if (!existsSync(pkgPath)) return null;
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    const range = pkg.dependencies?.[SDK_PKG] ?? pkg.peerDependencies?.[SDK_PKG];
+    return typeof range === "string" ? range.replace(/^[\^~]/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `^x.y.z` range to write when scaffolding: what the project has installed,
+ * else what this CLI ships against. A caret, so patch and minor SDK releases do
+ * not invalidate every published widget.
+ */
+export function defaultSdkRange(cwd?: string): string | null {
+  const version = (cwd ? getInstalledSdkVersion(cwd) : null) ?? getCliSdkVersion();
+  return version ? `^${version}` : null;
+}
+
+/** Strip a leading caret/tilde so a range can be compared as a version. */
+export function bareVersion(range: string): string {
+  return range.replace(/^[\^~]/, "");
+}

package/src/utils/typecheck.test.ts

@@ -0,0 +1,128 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { cpSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { runTypecheck } from "./typecheck";
+
+// Inside the package so fixtures can resolve typescript from its node_modules,
+// which is what a hoisted or workspace install looks like.
+const tmpDir = mkdtempSync(join(import.meta.dir, ".typecheck-test-"));
+// Outside it, for the one case that must find no typescript anywhere above it.
+const isolatedDir = mkdtempSync(join(tmpdir(), "glasshome-typecheck-"));
+
+afterAll(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+  rmSync(isolatedDir, { recursive: true, force: true });
+});
+
+/**
+ * A real installed typescript to link into fixtures, or null.
+ *
+ * Resolved lazily and allowed to be absent: this package does not declare
+ * typescript, so in the monorepo it comes from the root's node_modules and in a
+ * standalone checkout there may be none at all. A hard resolve at module load
+ * would take the whole file down there. The `node_modules` check keeps bun's
+ * global-cache fallback out, which would not be a real install.
+ */
+function findTypescript(): string | null {
+  try {
+    const pkg = createRequire(import.meta.url).resolve("typescript/package.json");
+    return pkg.split(sep).includes("node_modules") ? dirname(pkg) : null;
+  } catch {
+    return null;
+  }
+}
+
+const typescriptDir = findTypescript();
+const noTypescript = typescriptDir === null;
+
+let fixtureCount = 0;
+
+interface ProjectOptions {
+  source?: string;
+  tsconfig?: boolean;
+  typescript?: boolean;
+  /** Somewhere with no node_modules above it, so nothing can be inherited. */
+  isolated?: boolean;
+}
+
+function project({
+  source,
+  tsconfig = true,
+  typescript = true,
+  isolated = false,
+}: ProjectOptions): string {
+  const dir = join(isolated ? isolatedDir : tmpDir, `project-${fixtureCount++}`);
+  mkdirSync(join(dir, "src"), { recursive: true });
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ name: "fixture", type: "module" }));
+  if (tsconfig) {
+    writeFileSync(
+      join(dir, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: {
+          strict: true,
+          noEmit: true,
+          module: "ESNext",
+          target: "ESNext",
+          moduleResolution: "bundler",
+          // Hermetic: without this tsc auto-loads every @types package it finds
+          // walking up to the monorepo root, which is both irrelevant to what
+          // is under test and slow enough to blow the test timeout.
+          types: [],
+        },
+        include: ["src"],
+      }),
+    );
+  }
+  if (typescript && typescriptDir) {
+    mkdirSync(join(dir, "node_modules"), { recursive: true });
+    symlinkSync(typescriptDir, join(dir, "node_modules", "typescript"), "dir");
+  }
+  writeFileSync(join(dir, "src", "index.ts"), source ?? "export const n: number = 1;\n");
+  return dir;
+}
+
+describe("runTypecheck", () => {
+  test.skipIf(noTypescript)("passes a project whose types are sound", () => {
+    expect(runTypecheck(project({})).status).toBe("ok");
+  });
+
+  test.skipIf(noTypescript)("fails on a type error and reports the file and message", () => {
+    const result = runTypecheck(project({ source: `export const n: number = "nope";\n` }));
+    expect(result.status).toBe("failed");
+    if (result.status !== "failed") return;
+    expect(result.output).toContain("src/index.ts");
+    expect(result.output).toContain("TS2322");
+  });
+
+  test("skips a project with no tsconfig rather than failing it", () => {
+    // A JS-only or custom-setup project is not broken, it is just not ours to check.
+    const result = runTypecheck(project({ tsconfig: false }));
+    expect(result.status).toBe("skipped");
+    if (result.status !== "skipped") return;
+    expect(result.reason).toContain("tsconfig");
+  });
+
+  test("skips when typescript is not installed in the project", () => {
+    // Load-bearing: with nothing installed, bun still resolves a bare
+    // "typescript" from its global install cache, so without the node_modules
+    // check this would silently check against whatever major is cached there.
+    const result = runTypecheck(project({ typescript: false, isolated: true }));
+    expect(result.status).toBe("skipped");
+    if (result.status !== "skipped") return;
+    expect(result.reason).toContain("not installed");
+  });
+
+  test.skipIf(noTypescript)("uses an ancestor's typescript, as hoisted and workspace installs give", () => {
+    // Requiring a copy inside the project itself would skip every monorepo.
+    const parent = project({ typescript: true });
+    const child = join(parent, "nested");
+    mkdirSync(join(child, "src"), { recursive: true });
+    cpSync(join(parent, "package.json"), join(child, "package.json"));
+    cpSync(join(parent, "tsconfig.json"), join(child, "tsconfig.json"));
+    writeFileSync(join(child, "src", "index.ts"), `export const n: number = "nope";\n`);
+
+    expect(runTypecheck(child).status).toBe("failed");
+  });
+});

package/src/utils/typecheck.ts

@@ -0,0 +1,84 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { log } from "@clack/prompts";
+import { isBunGlobalCache } from "./resolution";
+
+/**
+ * Typecheck a widget project before building it.
+ *
+ * Scaffolded projects build with a bare `vite build`, which strips types without
+ * checking them, so a widget could bundle and publish with its config type and
+ * its `configSchema` disagreeing — including `examples` whose config the widget
+ * would never accept. tsc is the only thing that catches that at authoring time.
+ *
+ * Skips (loudly) rather than failing when the project has no tsconfig or no
+ * local typescript: a guard that cannot run has to say so.
+ */
+
+export type TypecheckResult =
+  | { status: "ok" }
+  | { status: "failed"; output: string }
+  | { status: "skipped"; reason: string };
+
+/**
+ * An installed typescript, never bun's global cache.
+ *
+ * Load-bearing: when a project has no typescript installed, bun still resolves
+ * the bare name, from `~/.bun/install/cache/typescript@7.0.2@@@1/`, so the CLI
+ * would silently check against whatever major happens to be cached there.
+ * Resolving to an *ancestor's* `node_modules` is fine and deliberate: hoisted
+ * and workspace installs put it there, so requiring a copy inside the project
+ * would skip every monorepo.
+ */
+function resolveTsc(cwd: string): string | null {
+  try {
+    const require = createRequire(join(cwd, "package.json"));
+    const pkg = resolve(require.resolve("typescript/package.json"));
+    if (isBunGlobalCache(pkg)) return null;
+    const bin = join(dirname(pkg), "bin", "tsc");
+    return existsSync(bin) ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+export function runTypecheck(cwd: string): TypecheckResult {
+  const tsconfig = join(cwd, "tsconfig.json");
+  if (!existsSync(tsconfig)) return { status: "skipped", reason: "no tsconfig.json" };
+
+  const tsc = resolveTsc(cwd);
+  if (!tsc) {
+    return { status: "skipped", reason: "typescript is not installed in this project" };
+  }
+
+  const proc = Bun.spawnSync([process.execPath, tsc, "--noEmit", "-p", tsconfig], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (proc.exitCode === 0) return { status: "ok" };
+
+  const output = [proc.stdout.toString(), proc.stderr.toString()].join("").trim();
+  return { status: "failed", output: output || `tsc exited ${proc.exitCode}` };
+}
+
+/**
+ * Typecheck and report. Returns false when the build should stop.
+ *
+ * Blocking on purpose: a type error here means the bundle that reaches the Hub
+ * is built from code the author never checked.
+ */
+export function typecheckAndReport(cwd: string): boolean {
+  const result = runTypecheck(cwd);
+  if (result.status === "ok") return true;
+
+  if (result.status === "skipped") {
+    log.warn(`Types were NOT checked: ${result.reason}.`);
+    return true;
+  }
+
+  log.error("Typecheck failed:");
+  log.message(result.output);
+  return false;
+}

package/template/README.md.template

@@ -18,7 +18,12 @@ bun install
 bun run build
 ```
 
-This produces `dist/{widget}.js` for each widget and generates `dist/registry.json`.
+This typechecks the project, produces `dist/{widget}.js` for each widget and
+generates `dist/registry.json`. To check types on their own:
+
+```bash
+bun run typecheck
+```
 
 ## Adding widgets
 

package/template/package.json.template

@@ -7,13 +7,14 @@
     "dist"
   ],
   "scripts": {
-    "build": "vite build",
+    "build": "tsc --noEmit && vite build",
+    "typecheck": "tsc --noEmit",
     "dev": "vite build --watch",
     "widget": "glasshome-widget"
   },
   "peerDependencies": {
     "solid-js": "^1.9.11",
-    "@glasshome/widget-sdk": "^0.2.0"
+    "@glasshome/widget-sdk": "SDK_RANGE"
   },
   "devDependencies": {
     "@glasshome/widget-cli": "CLI_VERSION",

package/template/src/index.tsx.template

@@ -31,7 +31,7 @@ export default defineWidget<WidgetConfig>({
     minSize: { w: 1, h: 1 },
     maxSize: { w: 4, h: 4 },
     defaultSize: { w: 2, h: 2 },
-    sdkVersion: "^0.2.0",
+    sdkVersion: "SDK_RANGE",
     schema: {
       type: "object",
       properties: {