@colixsystems/widget-sdk 0.38.0 → 0.40.0

package/dist/devserver.js

@@ -7,12 +7,40 @@
 // text → rewrite bare imports to host shims → blob `import()` → register), so a
 // widget that renders under `dev` will publish unchanged.
 //
+// Two modes (sc-1027 — directory mode is the v2 default):
+//
+//   directory mode (multi-file, runs against `first-party-widgets/<name>/`)
+//     • reads `widget.json` for the canonical manifest + component source(s);
+//     • picks the WEB variant (`componentSources["widget.web.jsx"]` if split-
+//       impl, else `componentSource`/`componentSources["widget.jsx"]`);
+//     • serves the entry at `/widget.mjs` (unchanged for back-compat with the
+//       loader) with its relative imports rewritten to absolute `/file/<rel>`
+//       URLs so the browser fetches sibling files from the dev server directly;
+//     • serves every sibling `.jsx` at `/file/<rel>` — Sucrase-transpiled, with
+//       bare imports rewritten to `/shim/<spec>` URLs (vetted statically-shimmed
+//       set only — see `dev-shims.shimmableSpecifiersForSiblings`) and relative
+//       imports rewritten to absolute `/file/<resolved-rel>` URLs;
+//     • serves `/shim/<slug>` ESM shims that re-export from
+//       `globalThis.__appstudioWidgetHost__` — the same global the Studio's
+//       blob shims populate, so the dev path stays in lockstep with the
+//       published path;
+//     • watches the whole widget directory recursively for `.jsx`/`.json` and
+//       broadcasts `reload` to every connected client.
+//
+//   single-file mode (legacy v1 — passed a bare `.jsx` entry)
+//     • original REQ-WSDK-DEVKIT behaviour. Kept so existing tasks don't
+//       break, but `dev-widgets/` is gone and the documented home for new
+//       dev widgets is `first-party-widgets/<slug>/`. Relative imports in a
+//       single-file entry still return 422 (they have no sibling to point
+//       at). Slated for removal in a follow-up once everything has moved.
+//
 // What this module owns:
-//   * transpile the single-file entry JSX→JS with the SAME Sucrase pass the
-//     publish path runs (`transforms:["jsx"]`, automatic runtime, production),
-//     so the served `/widget.mjs` is byte-for-byte the shape the loader expects;
-//   * serve it (plus a best-effort `/manifest.json`) over HTTP with permissive
-//     CORS for the Vite dev origin;
+//   * transpile each served file JSX→JS with the SAME Sucrase pass the publish
+//     path runs (`transforms:["jsx"]`, automatic runtime, production), so the
+//     dev bundle is byte-for-byte the shape the loader expects;
+//   * serve `/widget.mjs` + best-effort `/manifest.json` + (directory mode)
+//     `/file/<rel>` + `/shim/<slug>` over HTTP with permissive CORS for the
+//     Studio dev origin;
 //   * a Server-Sent-Events channel (`/__dev/events`) that emits `reload` on
 //     every source change so the Builder re-fetches + re-registers + re-renders;
 //   * re-lint (reusing `lintSource`) on every change, printing findings without
@@ -23,18 +51,49 @@
 // weight; only the dev command pulls the transform in.
 
 import { createServer } from "node:http";
-import { readFileSync, existsSync, watch } from "node:fs";
-import { resolve, dirname, join, sep } from "node:path";
+import {
+  readFileSync,
+  existsSync,
+  statSync,
+  watch,
+  realpathSync,
+} from "node:fs";
+import { resolve, dirname, join, sep, relative, posix } from "node:path";
 import { lintSource } from "./linter.js";
+import {
+  getShimSource,
+  shimmableSpecifiersForSiblings,
+  shimSlugFor,
+  shimSpecifierFromSlug,
+} from "./dev-shims.js";
+import { bundleWebEntry } from "./webbundle.js";
 
 // Bare-import / relative-import detection. The loader rewrites bare specifiers
 // in the ENTRY to client-side blob shims, so they resolve fine. Relative
-// imports do NOT — a sibling fetched over HTTP can't be handed the loader's
-// blob shims for its own bare imports — so v1 refuses them with guidance
-// rather than serving a module the browser silently fails to resolve.
+// imports in a SINGLE-FILE entry have nowhere to resolve — single-file mode
+// refuses them with guidance. In directory mode, relative imports in the entry
+// AND in siblings are rewritten to absolute dev-server URLs.
 const RELATIVE_IMPORT_RE =
   /(?:^|\n)\s*(?:import|export)[^;\n]*?from\s*['"](\.\.?\/[^'"]+)['"]/g;
 
+// Static-import / static-export-from anchored at a statement boundary
+// (start-of-line, `;`, or newline before `import`/`export`) so the rewriter
+// doesn't touch occurrences inside string literals or comment bodies. The
+// dynamic-import form (`import("...")`) is matched separately by
+// `DYNAMIC_IMPORT_RE` below — it's safe to anchor in the same way because
+// it's also valid only as an expression.
+//
+// Capture groups for both regexes:
+//   1 = leading keyword + whitespace (and the leading boundary char, which we
+//       preserve verbatim during replace so the surrounding statement isn't
+//       glued onto the previous line)
+//   2 = opening quote
+//   3 = specifier
+const STATIC_IMPORT_RE =
+  /((?:^|[\n;])\s*(?:import|export)\s+(?:[^'";\n]*?\s+from\s*)?)(['"])([^'"]+)\2/gm;
+const DYNAMIC_IMPORT_RE =
+  /((?:^|[\s;\(,!?:=])import\s*\(\s*)(['"])([^'"]+)\2/g;
+
 /**
  * Lazily resolve `sucrase`'s `transform`. Kept out of the module's static
  * imports so the published SDK (runtime + types) never forces the dependency;
@@ -74,9 +133,9 @@ export function transpile(transform, source) {
 }
 
 /**
- * Find relative (`./` / `../`) import specifiers in a source string. Used to
- * reject split-impl bundles in v1 with a clear message instead of serving a
- * module the browser can't resolve.
+ * Find relative (`./` / `../`) import specifiers in a source string. Used in
+ * single-file mode to reject split-impl bundles with a clear message instead
+ * of serving a module the browser can't resolve.
  *
  * @param {string} source
  * @returns {string[]} unique relative specifiers
@@ -89,6 +148,95 @@ export function findRelativeImports(source) {
   return Array.from(out);
 }
 
+/**
+ * Resolve a relative specifier (`./foo` / `../bar/baz`) into an absolute
+ * `/file/<rel>` path under the widget directory. The result is what the dev
+ * server serves and what the browser fetches. Returns null when the resolved
+ * path escapes the widget directory — the caller refuses to bundle it.
+ *
+ * Specifiers without a `.jsx`/`.js`/`.json` extension get a `.jsx` default so
+ * `import Helper from "./helper"` works without forcing the author to type
+ * the extension (matches Vite / Metro behaviour).
+ *
+ * @param {string} fromRel  the rel-path of the importing file (POSIX-style,
+ *   relative to the widget dir, e.g. "MapWidget.web.jsx" or "lib/util.jsx").
+ * @param {string} specifier  the relative specifier as written in source.
+ * @returns {string | null} POSIX-style rel-path under the widget dir, or null
+ *   if the resolution escapes it.
+ */
+export function resolveRelativeImport(fromRel, specifier) {
+  if (!specifier.startsWith("./") && !specifier.startsWith("../")) return null;
+  const fromDir = posix.dirname(fromRel.replace(/\\/g, "/"));
+  const joined = posix.normalize(posix.join(fromDir, specifier));
+  if (joined.startsWith("..") || joined.startsWith("/")) return null;
+  // Default the extension when omitted. A specifier with a non-JS extension
+  // (asset imports like `./icon.svg`) is rejected — the dev server only
+  // serves JS modules; static asset bundling needs a real build step.
+  if (/\.(jsx?|json)$/.test(joined)) return joined;
+  if (/\.[A-Za-z0-9]+$/.test(joined)) return null;
+  return `${joined}.jsx`;
+}
+
+/**
+ * Rewrite imports inside a served file so the browser can resolve every
+ * specifier without help from the host loader:
+ *   • relative `./foo` / `../bar` → absolute `${baseUrl}/file/<resolved-rel>`
+ *   • bare `<shimmable>` → absolute `${baseUrl}/shim/<slug>`
+ *   • other bare specifiers (non-shimmable for siblings) are LEFT ALONE so
+ *     the browser surfaces a clear "Failed to resolve module specifier" error
+ *     and the dev server logs it as a lint finding alongside.
+ *
+ * Pure string-level — no AST.
+ *
+ * @param {string} source  transpiled JS source (post-Sucrase).
+ * @param {object} ctx
+ * @param {string} ctx.fromRel  POSIX-style rel-path of the file being served
+ *   (so relative imports resolve from its directory).
+ * @param {string} ctx.baseUrl  origin of the dev server (e.g. http://127.0.0.1:4400).
+ * @param {string[]} ctx.shimmable  bare specifiers the dev server has shims for.
+ * @returns {{ code: string, unresolved: string[] }} rewritten source plus the
+ *   list of bare specifiers that were not shimmable (informational; the dev
+ *   server logs these so the author sees them in the terminal).
+ */
+export function rewriteImportsForDirectoryMode(source, ctx) {
+  const { fromRel, baseUrl, shimmable } = ctx;
+  const unresolved = new Set();
+  const handler = (match, prefix, quote, spec) => {
+    // Relative — resolve under the widget dir.
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      const rel = resolveRelativeImport(fromRel, spec);
+      if (!rel) {
+        unresolved.add(spec);
+        return match;
+      }
+      return `${prefix}${quote}${baseUrl}/file/${rel}${quote}`;
+    }
+    // Absolute or already-resolved — leave alone.
+    if (
+      spec.startsWith("/") ||
+      spec.startsWith("http:") ||
+      spec.startsWith("https:") ||
+      spec.startsWith("blob:") ||
+      spec.startsWith("data:")
+    ) {
+      return match;
+    }
+    // Bare — rewrite if shimmable, else surface as unresolved.
+    if (shimmable.includes(spec)) {
+      return `${prefix}${quote}${baseUrl}/shim/${shimSlugFor(spec)}${quote}`;
+    }
+    unresolved.add(spec);
+    return match;
+  };
+  // Two passes: anchored static-import + anchored dynamic-import. The split
+  // (vs. one mega-regex) keeps each pattern simple AND lets us anchor each at
+  // its real statement boundary — so substrings inside string literals like
+  // `const s = "import x from 'react'"` never match.
+  let out = source.replace(STATIC_IMPORT_RE, handler);
+  out = out.replace(DYNAMIC_IMPORT_RE, handler);
+  return { code: out, unresolved: Array.from(unresolved) };
+}
+
 /**
  * Best-effort manifest resolution for bare-component bundles (the loader's
  * shape B, where the manifest does NOT ride in the bundle). Marketplace
@@ -121,6 +269,112 @@ export function resolveManifest(entryPath, manifestPath) {
   return null;
 }
 
+/**
+ * Load + validate a `first-party-widgets/<name>/widget.json` and resolve the
+ * canonical paths into absolute filesystem locations. Throws with a clear
+ * message on any missing/malformed field — failing here beats failing later
+ * when the browser dynamic-imports an empty `widget.mjs`.
+ *
+ * Returns:
+ *   {
+ *     widgetDir: <abs path of the widget directory>,
+ *     manifestPath: <abs path of the manifest .js>,
+ *     // The chosen WEB-platform entry file. For a split-impl widget that's
+ *     // `componentSources["widget.web.jsx"]`; for a single-source widget
+ *     // it's `componentSource` (or `componentSources["widget.jsx"]`).
+ *     entryPath: <abs path>,
+ *     entryRel: <POSIX-style rel-path under the widget dir>,
+ *   }
+ *
+ * @param {string} widgetDir  absolute path to the widget directory
+ * @returns {{widgetDir: string, manifestPath: string, entryPath: string, entryRel: string}}
+ */
+export function loadWidgetJson(widgetDir) {
+  const configPath = join(widgetDir, "widget.json");
+  if (!existsSync(configPath)) {
+    throw new Error(`No widget.json at ${configPath}`);
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch (err) {
+    throw new Error(`Could not parse ${configPath}: ${err.message}`);
+  }
+  if (!config.manifestSource || typeof config.manifestSource !== "string") {
+    throw new Error(`${configPath}: manifestSource is required`);
+  }
+  // `widget.json` paths are repo-root-relative for the canonical layout
+  // (first-party-widgets/<slug>/...), but the dev server doesn't need to
+  // assume the parent layout — it only needs to land under `widgetDir`. We
+  // try widget-dir-relative first (so a future widget.json with `./foo.js`
+  // works), then strip a `first-party-widgets/<slug>/` prefix as a back-
+  // compat path for today's widget.json files. `_isUnder` catches anything
+  // that resolves outside `widgetDir`.
+  const widgetSlug = widgetDir.split(sep).pop();
+  function _resolveUnderWidget(label, p) {
+    const candidates = [
+      resolve(widgetDir, p),
+      p.startsWith(`first-party-widgets/${widgetSlug}/`)
+        ? resolve(widgetDir, p.slice(`first-party-widgets/${widgetSlug}/`.length))
+        : null,
+      resolve(widgetDir, "..", "..", p),
+    ].filter(Boolean);
+    for (const abs of candidates) {
+      if (_isUnder(widgetDir, abs) && existsSync(abs)) return abs;
+    }
+    throw new Error(
+      `${configPath}: ${label} must point at a file under ${widgetDir} (got "${p}")`,
+    );
+  }
+  const manifestAbs = _resolveUnderWidget("manifestSource", config.manifestSource);
+
+  let entryAbs;
+  if (config.componentSources && typeof config.componentSources === "object") {
+    const map = config.componentSources;
+    // Prefer the web variant; fall back to the cross-platform `widget.jsx` if a
+    // dev'd widget is native-only (rare for the dev loop — the Studio Player
+    // is web).
+    const pick =
+      (typeof map["widget.web.jsx"] === "string" && map["widget.web.jsx"]) ||
+      (typeof map["widget.jsx"] === "string" && map["widget.jsx"]) ||
+      null;
+    if (!pick) {
+      throw new Error(
+        `${configPath}: componentSources has no web-runnable entry ` +
+          `(expected "widget.web.jsx" or "widget.jsx").`,
+      );
+    }
+    entryAbs = _resolveUnderWidget("componentSources entry", pick);
+  } else if (typeof config.componentSource === "string") {
+    entryAbs = _resolveUnderWidget("componentSource", config.componentSource);
+  } else {
+    throw new Error(
+      `${configPath}: must set componentSource OR componentSources.`,
+    );
+  }
+  const entryRel = relative(widgetDir, entryAbs).split(sep).join("/");
+  return { widgetDir, manifestPath: manifestAbs, entryPath: entryAbs, entryRel };
+}
+
+function _isUnder(parentAbs, childAbs) {
+  const prefix = parentAbs.endsWith(sep) ? parentAbs : parentAbs + sep;
+  return childAbs === parentAbs || childAbs.startsWith(prefix);
+}
+
+// Defense-in-depth — resolve symlinks before the containment check. The dev
+// server runs on 127.0.0.1 and the developer is the only attacker, but a
+// poisoned symlink under `widgetDir` would otherwise let `/file/<rel>` serve
+// arbitrary repo content. Falls back to the lexical check when realpath
+// can't follow (e.g. broken symlink) so a typo doesn't 500 the server.
+function _isUnderReal(parentRealAbs, childAbs) {
+  try {
+    const childReal = realpathSync(childAbs);
+    return _isUnder(parentRealAbs, childReal);
+  } catch {
+    return false;
+  }
+}
+
 function setCors(res) {
   res.setHeader("Access-Control-Allow-Origin", "*");
   res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
@@ -134,71 +388,256 @@ function setCors(res) {
  * `broadcastReload()` the watcher calls, and a `manifestId` getter for the
  * health route + CLI banner.
  *
+ * Either `entryPath` (single-file mode) OR `widgetDir` (directory mode) is
+ * required. Directory mode reads `widget.json` from `widgetDir` and chooses
+ * the web entry; single-file mode behaves as v1.
+ *
  * @param {object} opts
- * @param {string} opts.entryPath  absolute path to the widget entry
- * @param {string|null} [opts.manifestPath]  explicit `--manifest` path
+ * @param {string} [opts.entryPath]  absolute path to a single-file widget entry
+ * @param {string} [opts.widgetDir]  absolute path to a directory with widget.json
+ * @param {string|null} [opts.manifestPath]  explicit `--manifest` path (single-file mode)
+ * @param {string[]} [opts.sdkExports]  named-export list for the SDK shim
+ *   (directory mode passes this; single-file mode doesn't need it because the
+ *   single entry's bare imports are blob-shimmed by the loader).
  * @param {(code: string, opts: object) => { code: string }} opts.transform
  * @param {(msg: string) => void} [opts.onLint]  receives lint summary lines
  */
-export function createDevServer({ entryPath, manifestPath = null, transform, onLint }) {
+export function createDevServer({
+  entryPath,
+  widgetDir,
+  manifestPath = null,
+  sdkExports = [],
+  transform,
+  onLint,
+}) {
   if (!transform) throw new Error("createDevServer: transform is required");
-  const entryDir = dirname(entryPath);
+  if (!entryPath && !widgetDir) {
+    throw new Error("createDevServer: entryPath or widgetDir is required");
+  }
+  if (entryPath && widgetDir) {
+    throw new Error(
+      "createDevServer: pass either entryPath OR widgetDir, not both",
+    );
+  }
+
+  const directoryMode = !!widgetDir;
+  let resolvedEntryPath = entryPath;
+  let resolvedManifestPath = manifestPath;
+  let entryRel = null;
+  let watchRoot;
+
+  if (directoryMode) {
+    const cfg = loadWidgetJson(widgetDir);
+    resolvedEntryPath = cfg.entryPath;
+    resolvedManifestPath = cfg.manifestPath;
+    entryRel = cfg.entryRel;
+    watchRoot = cfg.widgetDir;
+  } else {
+    watchRoot = dirname(resolvedEntryPath);
+  }
+
+  // sc-1064: extra node_modules roots for the web-entry bundler so it resolves
+  // a widget's vetted web deps (`react-leaflet`, `leaflet`, …). A first-party
+  // widget lives at `<repo>/first-party-widgets/<slug>/`; the vetted web
+  // packages install under `<repo>/frontend/node_modules` (adding-vetted-
+  // packages skill §3a). Walk up to that root; esbuild also searches the
+  // entry's own ancestor node_modules by default, so a widget that vendored
+  // its deps locally still resolves.
+  const bundleNodePaths = [];
+  const _frontendNm = resolve(watchRoot, "..", "..", "frontend", "node_modules");
+  if (existsSync(_frontendNm)) bundleNodePaths.push(_frontendNm);
+
   const sseClients = new Set();
   let manifest = null;
   try {
-    manifest = resolveManifest(entryPath, manifestPath);
+    manifest = directoryMode
+      ? _importManifestJs(resolvedManifestPath)
+      : resolveManifest(resolvedEntryPath, resolvedManifestPath);
   } catch (err) {
-    // A malformed manifest file shouldn't crash the server — surface it and
-    // serve shape-A bundles (manifest in the bundle) regardless.
     if (onLint) onLint(`manifest: ${err.message}`);
   }
   const manifestId = manifest?.id || null;
+  const shimmable = shimmableSpecifiersForSiblings();
+  // Resolve the watch root once for the symlink-aware containment check.
+  // `realpathSync` is sync + cheap; failure (broken symlink) falls back to
+  // the lexical watchRoot.
+  let watchRootReal = watchRoot;
+  try {
+    watchRootReal = realpathSync(watchRoot);
+  } catch {
+    /* keep lexical */
+  }
+  // Pin the base URL from the listening server's bound interface (set after
+  // `listen`). Until then, fall back to a placeholder that the rewriter only
+  // uses for resolving relative URLs — `startDevServer` writes the real value
+  // once the socket is bound. NOT derived from `req.headers["host"]`: a
+  // request with a forged `Host: evil.com` header would otherwise have every
+  // /file/ + /shim/ URL rewritten to point at the attacker.
+  let boundBaseUrl = "http://127.0.0.1";
+  const setBoundBaseUrl = (u) => {
+    boundBaseUrl = u;
+  };
 
-  function readEntry() {
-    return readFileSync(entryPath, "utf8");
+  // Resolve a `/file/<rel>` request to an absolute filesystem path under the
+  // widget directory, or null when the path escapes / doesn't exist.
+  // `_isUnderReal` resolves symlinks before the containment check so a
+  // poisoned symlink under the widget dir can't serve arbitrary repo content.
+  function resolveFileRel(rel) {
+    if (!directoryMode) return null;
+    if (!rel || rel.includes("\0")) return null;
+    // Posix-style on the wire; normalize and refuse `..` traversal.
+    const normalised = posix.normalize(rel.replace(/^\/+/, ""));
+    if (normalised.startsWith("..") || normalised.startsWith("/")) return null;
+    const abs = join(watchRoot, normalised.split("/").join(sep));
+    if (!_isUnder(watchRoot, abs)) return null;
+    if (!_isUnderReal(watchRootReal, abs)) return null;
+    if (!existsSync(abs)) return null;
+    try {
+      if (!statSync(abs).isFile()) return null;
+    } catch {
+      return null;
+    }
+    return { abs, rel: normalised };
   }
 
-  function serveWidget(res) {
+  function transpileWithGuards(absPath) {
+    const source = readFileSync(absPath, "utf8");
+    try {
+      return { ok: true, code: transpile(transform, source) };
+    } catch (err) {
+      return { ok: false, error: err };
+    }
+  }
+
+  async function serveEntry(req, res) {
+    if (directoryMode) {
+      // sc-1064: bundle the WEB entry with the SAME routine the publish packer
+      // runs, so `dev` and the published `.tgz` are byte-shape-identical. The
+      // bundler inlines siblings + vetted web deps (`react-leaflet`, `leaflet`,
+      // CSS, PNG assets) and leaves ONLY the host-resolved set
+      // (`hostExternalSpecifiers()`) as bare imports — the Studio loader's
+      // blob-shim path rewrites those exactly as it does for a published bundle
+      // (CLAUDE.md §3, one path). Siblings no longer need the `/file/` rewrite:
+      // esbuild has already inlined them.
+      let code;
+      try {
+        code = await bundleWebEntry({
+          entryPath: resolvedEntryPath,
+          nodePaths: bundleNodePaths,
+        });
+      } catch (err) {
+        const safe = JSON.stringify(String(err.message || err));
+        res.writeHead(200, { "Content-Type": "text/javascript" });
+        res.end(`throw new Error(${safe});`);
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/javascript" });
+      res.end(code);
+      return;
+    }
+
+    // Single-file mode — transpile-only (kept for v1 back-compat).
     let source;
     try {
-      source = readEntry();
+      source = readFileSync(resolvedEntryPath, "utf8");
     } catch (err) {
       res.writeHead(404, { "Content-Type": "text/plain" });
-      res.end(`Could not read entry ${entryPath}: ${err.message}`);
+      res.end(`Could not read entry ${resolvedEntryPath}: ${err.message}`);
       return;
     }
+    let code;
+    try {
+      code = transpile(transform, source);
+    } catch (err) {
+      const safe = JSON.stringify(String(err.message || err));
+      res.writeHead(200, { "Content-Type": "text/javascript" });
+      res.end(`throw new Error(${safe});`);
+      return;
+    }
+    // Single-file mode has no sibling to resolve relative imports against.
     const relatives = findRelativeImports(source);
     if (relatives.length > 0) {
       const msg =
         `Entry imports relative modules (${relatives.join(", ")}). ` +
-        "v1 of `appstudio-widget dev` serves a single-file entry only — " +
-        "bundle split-impl widgets with a real build step (esbuild/rollup) " +
-        "and load the built widget.mjs, or inline the helpers into the entry.";
+        "Single-file mode of `appstudio-widget dev` serves one file only. " +
+        "Move the widget under `first-party-widgets/<slug>/` with a " +
+        "widget.json pointer, then point the dev task at that directory — " +
+        "the dev server picks up siblings automatically (REQ-WSDK-DEVKIT v2).";
       res.writeHead(422, { "Content-Type": "text/plain" });
       res.end(msg);
       return;
     }
-    let code;
-    try {
-      code = transpile(transform, source);
-    } catch (err) {
-      // Surface the transpile error as the module body so the browser console
-      // (and the Builder dev panel) shows the real syntax error, not an opaque
-      // "failed to fetch dynamically imported module".
-      const safe = JSON.stringify(String(err.message || err));
+
+    res.writeHead(200, { "Content-Type": "text/javascript" });
+    res.end(code);
+  }
+
+  function serveFile(req, res, rel) {
+    if (!directoryMode) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("/file/ is directory-mode only");
+      return;
+    }
+    const resolved = resolveFileRel(rel);
+    if (!resolved) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end(`File not found under widget directory: ${rel}`);
+      return;
+    }
+    const tx = transpileWithGuards(resolved.abs);
+    if (!tx.ok) {
+      const safe = JSON.stringify(String(tx.error.message || tx.error));
       res.writeHead(200, { "Content-Type": "text/javascript" });
       res.end(`throw new Error(${safe});`);
       return;
     }
+    const baseUrl = boundBaseUrl;
+    const rewritten = rewriteImportsForDirectoryMode(tx.code, {
+      fromRel: resolved.rel,
+      baseUrl,
+      shimmable,
+    });
+    if (rewritten.unresolved.length > 0 && onLint) {
+      onLint(
+        `file ${resolved.rel}: unshimmable bare imports — ${rewritten.unresolved.join(", ")}`,
+      );
+    }
     res.writeHead(200, { "Content-Type": "text/javascript" });
-    res.end(code);
+    res.end(rewritten.code);
+  }
+
+  function serveShim(res, slug) {
+    if (!directoryMode) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("/shim/ is directory-mode only");
+      return;
+    }
+    const specifier = shimSpecifierFromSlug(slug);
+    if (!shimmable.includes(specifier)) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end(
+        `No shim for "${specifier}". Sibling files may only import: ` +
+          `${shimmable.join(", ")}. Move the import to the widget entry where ` +
+          `the Studio loader's blob-shim path handles the full vetted set.`,
+      );
+      return;
+    }
+    const src = getShimSource(specifier, { sdkExports });
+    if (!src) {
+      res.writeHead(500, { "Content-Type": "text/plain" });
+      res.end(`Could not build shim for ${specifier}`);
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/javascript" });
+    res.end(src);
   }
 
   function serveManifest(res) {
-    // Re-read so an edited sibling manifest.json is picked up live.
     let m = null;
     try {
-      m = resolveManifest(entryPath, manifestPath);
+      m = directoryMode
+        ? _importManifestJs(resolvedManifestPath)
+        : resolveManifest(resolvedEntryPath, resolvedManifestPath);
     } catch {
       m = null;
     }
@@ -223,6 +662,20 @@ export function createDevServer({ entryPath, manifestPath = null, transform, onL
     req.on("close", () => sseClients.delete(res));
   }
 
+  // Once the server starts listening, the bound port is known — derive the
+  // canonical base URL from it. This keeps every /file/ + /shim/ URL pinned
+  // to the dev server's actual origin no matter what `Host` header a request
+  // carries. The caller may also call setBoundBaseUrl explicitly (e.g. when
+  // running behind a tunnel that needs a specific public URL).
+  function _autoBindOnListen(server) {
+    server.on("listening", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        setBoundBaseUrl(`http://127.0.0.1:${addr.port}`);
+      }
+    });
+  }
+
   const server = createServer((req, res) => {
     setCors(res);
     if (req.method === "OPTIONS") {
@@ -231,17 +684,35 @@ export function createDevServer({ entryPath, manifestPath = null, transform, onL
       return;
     }
     const url = (req.url || "/").split("?")[0];
-    if (url === "/widget.mjs") return serveWidget(res);
+    if (url === "/widget.mjs") {
+      // serveEntry is async (it bundles the web entry). Catch a rejected
+      // promise so a bundler failure never crashes the dev process — it
+      // surfaces as a 500 the browser logs instead.
+      serveEntry(req, res).catch((err) => {
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "text/plain" });
+          res.end(`Bundle failed: ${err?.message || err}`);
+        }
+      });
+      return;
+    }
     if (url === "/manifest.json") return serveManifest(res);
     if (url === "/__dev/events") return serveEvents(req, res);
     if (url === "/__dev/health") {
       res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ ok: true, manifestId }));
+      res.end(JSON.stringify({ ok: true, manifestId, mode: directoryMode ? "directory" : "single-file" }));
       return;
     }
+    if (directoryMode && url.startsWith("/file/")) {
+      return serveFile(req, res, url.slice("/file/".length));
+    }
+    if (directoryMode && url.startsWith("/shim/")) {
+      return serveShim(res, url.slice("/shim/".length));
+    }
     res.writeHead(404, { "Content-Type": "text/plain" });
     res.end("Not found");
   });
+  _autoBindOnListen(server);
 
   function broadcastReload() {
     for (const res of sseClients) {
@@ -256,7 +727,7 @@ export function createDevServer({ entryPath, manifestPath = null, transform, onL
   function lintEntry() {
     let source;
     try {
-      source = readEntry();
+      source = readFileSync(resolvedEntryPath, "utf8");
     } catch {
       return;
     }
@@ -274,7 +745,10 @@ export function createDevServer({ entryPath, manifestPath = null, transform, onL
     server,
     broadcastReload,
     lintEntry,
-    entryDir,
+    entryDir: watchRoot,
+    watchRoot,
+    directoryMode,
+    setBoundBaseUrl,
     get manifestId() {
       return manifest?.id || null;
     },
@@ -284,27 +758,110 @@ export function createDevServer({ entryPath, manifestPath = null, transform, onL
   };
 }
 
+// Import a manifest .js file (pure ESM data module) so the dev server can
+// serve a parsed manifest at `/manifest.json` from a first-party widget that
+// stores the manifest as JS (the canonical shape). Falls back to JSON when
+// the file is JSON. The published-bundle path imports the manifest the same
+// way, keeping both in lockstep.
+function _importManifestJs(manifestAbsPath) {
+  if (manifestAbsPath.endsWith(".json")) {
+    return JSON.parse(readFileSync(manifestAbsPath, "utf8"));
+  }
+  // For .js / .mjs files we read and `Function`-eval the export — same shape
+  // pack-first-party-widget.mjs uses (a tiny ESM data module). Async import is
+  // available but synchronous here keeps the createDevServer call signature
+  // simple; the file is tiny and re-read on every manifest request.
+  const src = readFileSync(manifestAbsPath, "utf8");
+  // Match `export const manifest = {...};` or `export default {...};`.
+  const m = src.match(/export\s+const\s+manifest\s*=\s*(\{[\s\S]*?\});?\s*$/m);
+  if (m) return _safeEvalObjectLiteral(m[1], manifestAbsPath);
+  const m2 = src.match(/export\s+default\s+(\{[\s\S]*?\});?\s*$/m);
+  if (m2) return _safeEvalObjectLiteral(m2[1], manifestAbsPath);
+  throw new Error(
+    `Could not find an exported manifest in ${manifestAbsPath} — ` +
+      "expected `export const manifest = { ... }` or `export default { ... }`.",
+  );
+}
+
+function _safeEvalObjectLiteral(src, path) {
+  // Wrap in parens so the JS parser treats `{...}` as an expression, not a block.
+  // Manifests are pure data (no requires, no side effects) so a Function-eval
+  // is safe — same shape the canonical pack script's dynamic import produces.
+  try {
+    // eslint-disable-next-line no-new-func
+    return Function(`"use strict";return (${src});`)();
+  } catch (err) {
+    throw new Error(
+      `Could not parse manifest object in ${path}: ${err.message}`,
+    );
+  }
+}
+
 /**
  * Resolve sucrase, create the dev server, start listening, watch the entry's
- * directory, and wire change → re-lint + reload broadcast. Returns the running
- * dev-server handle. The caller (the CLI) owns logging the banner.
+ * directory (recursively in directory mode), and wire change → re-lint +
+ * reload broadcast. Returns the running dev-server handle.
  *
  * @param {object} opts
- * @param {string} opts.entry  path to the widget entry (relative or absolute)
+ * @param {string} opts.entry  path to a widget entry file OR a widget
+ *   directory containing widget.json. Directory mode is autodetected.
  * @param {number} [opts.port]
- * @param {string|null} [opts.manifest]  explicit manifest path
+ * @param {string|null} [opts.manifest]  explicit manifest path (single-file)
+ * @param {string[]} [opts.sdkExports]  caller-supplied SDK named-export list
+ *   (only used in directory mode for the /shim/@colixsystems/widget-sdk shim).
+ *   Defaults to a small core set; richer callers (the SDK CLI) can pass the
+ *   full list from the loaded SDK.
  * @param {(line: string) => void} [opts.log]
- * @returns {Promise<{ server: import("node:http").Server, port: number, url: string, manifestId: string|null, close: () => Promise<void> }>}
+ * @returns {Promise<{ server: import("node:http").Server, port: number, url: string, manifestId: string|null, directoryMode: boolean, close: () => Promise<void> }>}
  */
-export async function startDevServer({ entry, port = 4400, manifest = null, log = () => {} }) {
-  const entryPath = resolve(entry);
-  if (!existsSync(entryPath)) {
-    throw new Error(`Entry not found: ${entryPath}`);
+export async function startDevServer({
+  entry,
+  port = 4400,
+  manifest = null,
+  sdkExports,
+  log = () => {},
+}) {
+  const entryAbs = resolve(entry);
+  if (!existsSync(entryAbs)) {
+    throw new Error(`Entry not found: ${entryAbs}`);
+  }
+  let directoryMode = false;
+  try {
+    if (statSync(entryAbs).isDirectory()) directoryMode = true;
+  } catch {
+    /* fall through */
   }
+  if (directoryMode && !existsSync(join(entryAbs, "widget.json"))) {
+    throw new Error(
+      `${entryAbs} is a directory but has no widget.json. Pass a single-file ` +
+        ".jsx entry OR a first-party widget directory (widget.json + sources).",
+    );
+  }
+
   const transform = await loadTransform();
+  // Default SDK exports list — derived from the actual SDK namespace via
+  // Object.keys, matching exactly what the Studio's `buildShims()` does. This
+  // keeps the dev server's /shim/@colixsystems/widget-sdk surface in lockstep
+  // with the published path: if the SDK adds a new export, both paths pick it
+  // up on the next dev-server restart without any hand-list maintenance.
+  // Caller-supplied `sdkExports` still wins, so tests can pin a fixed list.
+  let defaultSdkExports = sdkExports;
+  if (!defaultSdkExports) {
+    try {
+      const sdk = await import("@colixsystems/widget-sdk");
+      defaultSdkExports = Object.keys(sdk).filter((k) => k !== "default");
+    } catch {
+      // SDK not resolvable from this Node process (e.g. dev server running
+      // in a detached workspace). Fall back to a small core set — broken
+      // dev experience for unusual exports, but better than crashing the CLI.
+      defaultSdkExports = ["defineWidget", "View", "Text", "Pressable"];
+    }
+  }
   const dev = createDevServer({
-    entryPath,
+    entryPath: directoryMode ? undefined : entryAbs,
+    widgetDir: directoryMode ? entryAbs : undefined,
     manifestPath: manifest,
+    sdkExports: defaultSdkExports,
     transform,
     onLint: log,
   });
@@ -315,30 +872,33 @@ export async function startDevServer({ entry, port = 4400, manifest = null, log
   });
   const actualPort = dev.server.address().port;
   // Advertise 127.0.0.1, not "localhost": the server binds the IPv4 loopback,
-  // but "localhost" resolves to IPv6 (::1) first on Windows, so a browser/CLI
-  // hitting http://localhost:<port> would fail to connect. 127.0.0.1 is
-  // unambiguous, loopback-only (not LAN-exposed), and works cross-platform.
+  // but "localhost" resolves to IPv6 (::1) first on Windows.
   const url = `http://127.0.0.1:${actualPort}`;
+  // Pin the rewriter's base URL from the bound interface — NOT the request's
+  // Host header — so every /file/ + /shim/ URL is anchored at the server's
+  // real origin regardless of what an attacker on the same host puts in Host.
+  dev.setBoundBaseUrl(url);
 
-  // Watch the entry's directory (non-recursive — reliable cross-platform).
-  // Debounce bursts (editors emit multiple events per save) before linting +
-  // broadcasting a single reload.
+  // Watch the entry's directory (recursive in directory mode so siblings
+  // anywhere under widgetDir trigger a reload). Debounce bursts (editors emit
+  // multiple events per save) before re-linting + broadcasting a single reload.
   let timer = null;
-  const watcher = watch(dev.entryDir, (_event, filename) => {
-    if (filename && !/\.(jsx?|json)$/.test(String(filename))) return;
-    if (timer) clearTimeout(timer);
-    timer = setTimeout(() => {
-      timer = null;
-      dev.lintEntry();
-      dev.broadcastReload();
-      log(`reload → ${dev.sseClientCount()} client(s)`);
-    }, 60);
-  });
+  const watcher = watch(
+    dev.watchRoot,
+    { recursive: directoryMode },
+    (_event, filename) => {
+      if (filename && !/\.(jsx?|json)$/.test(String(filename))) return;
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        dev.lintEntry();
+        dev.broadcastReload();
+        log(`reload → ${dev.sseClientCount()} client(s)`);
+      }, 60);
+    },
+  );
 
-  // Guard against the watched path not existing under some sandboxes.
   watcher.on("error", (err) => log(`watch error: ${err.message}`));
-
-  // Initial lint pass so the author sees findings immediately.
   dev.lintEntry();
 
   async function close() {
@@ -346,5 +906,12 @@ export async function startDevServer({ entry, port = 4400, manifest = null, log
     await new Promise((res) => dev.server.close(res));
   }
 
-  return { server: dev.server, port: actualPort, url, manifestId: dev.manifestId, close };
+  return {
+    server: dev.server,
+    port: actualPort,
+    url,
+    manifestId: dev.manifestId,
+    directoryMode: dev.directoryMode,
+    close,
+  };
 }