@colixsystems/widget-sdk 0.117.0 → 0.119.0

package/dist/flatten-entry.js

@@ -0,0 +1,817 @@
+// sc-6086: fold a widget entry's SIBLING modules into one ESM source.
+//
+// A first-party bundle carries exactly one component module, but
+// `appstudio-widget dev` serves the widget DIRECTORY — so a multi-file widget
+// runs locally and publishes an entry importing files the tarball does not
+// have. Flattening here is what makes the two loops agree (CLAUDE.md §3).
+//
+// Why a textual splice and not esbuild: the marketplace analyzer lints this
+// exact text, and licenses several of its rules by COMMENT
+// (`// appstudio-design-ok: <reason>`). esbuild drops comments, which silently
+// revokes every licence — on `chart` that turns 0 `no-hardcoded-design`
+// findings into 48. First-party versions are auto-published, so the analyzer
+// is the only gate they pass. Splicing keeps comments and identifiers exact.
+//
+// WHAT to splice is decided by a real parser, not by pattern matching. Two
+// rounds of review found holes a scanner cannot close — a `}` inside a regex
+// character class skewing brace depth, `return /[{]/` reading as division, a
+// Unicode identifier in an import clause — each of which silently published a
+// bundle that was wrong rather than refused. The caller injects `parse`
+// (`@babel/parser`) so this module stays dependency-free for the SDK runtime.
+//
+// The supported shape is narrow and anything outside it throws, naming the
+// file and line: siblings may only use named declaration exports, and may only
+// be imported by name.
+//
+// One divergence this design cannot close: modules share one scope after
+// inlining, so a sibling's top-level `const URL = …` shadows an ambient global
+// another module relies on. Renaming would fix it and would also destroy the
+// premise — the analyzer lints THIS text, so identifiers and comments have to
+// stay exactly as the author wrote them. Duplicate DECLARATIONS are refused;
+// a declaration capturing another module's free reference is not detectable
+// without scope analysis this deliberately does not do.
+
+import { stripNonCode } from "./source-mask.js";
+
+// ---------------------------------------------------------------------------
+// Best-effort scanner — the dev-server guard only.
+//
+// `appstudio-widget dev` cannot load a parser (the SDK ships this file), and a
+// miss there only costs a warning, never a bad bundle. Everything the PACKER
+// relies on goes through the AST below instead.
+// ---------------------------------------------------------------------------
+
+/** Comments + template literals blanked; quoted specifiers kept, offsets intact. */
+function maskCode(source) {
+  return stripNonCode(source, { keepStrings: true, keepTemplates: false });
+}
+
+/** Index of a regex literal's closing `/`, or -1 when it isn't one. */
+function skipRegexLiteral(mask, start) {
+  let inClass = false;
+  for (let i = start + 1; i < mask.length; i += 1) {
+    const ch = mask[i];
+    if (ch === "\\") {
+      i += 1;
+      continue;
+    }
+    if (ch === "\n") return -1;
+    if (ch === "[") inClass = true;
+    else if (ch === "]") inClass = false;
+    else if (ch === "/" && !inClass) return i;
+  }
+  return -1;
+}
+
+// A `/` opens a regex unless the previous token can end an expression. The
+// keyword list matters: `return /[{]/` is a regex, and reading it as division
+// throws the brace count off.
+const REGEX_PRECEDING_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "case",
+  "yield",
+  "await",
+  "throw",
+]);
+
+function opensRegex(mask, at) {
+  let i = at - 1;
+  while (i >= 0 && /\s/.test(mask[i])) i -= 1;
+  if (i < 0) return true;
+  const ch = mask[i];
+  if (/[)\]]/.test(ch)) return false;
+  if (!/[\w$]/.test(ch)) return true;
+  let end = i + 1;
+  while (i >= 0 && /[\w$]/.test(mask[i])) i -= 1;
+  const word = mask.slice(i + 1, end);
+  return REGEX_PRECEDING_KEYWORDS.has(word);
+}
+
+/** Brace depth at every offset, skipping regex literals. */
+function braceDepths(mask) {
+  const depth = new Int32Array(mask.length);
+  let d = 0;
+  for (let i = 0; i < mask.length; i += 1) {
+    const ch = mask[i];
+    if (ch === "/" && opensRegex(mask, i)) {
+      const end = skipRegexLiteral(mask, i);
+      if (end > i) {
+        depth.fill(d, i, end + 1);
+        i = end;
+        continue;
+      }
+    }
+    if (ch === "}") d -= 1;
+    depth[i] = d;
+    if (ch === "{") d += 1;
+  }
+  return depth;
+}
+
+const CLAUSE_CHAR = /[A-Za-z0-9_$,{}*\s]/;
+
+// What may appear between the keyword and `from`. Non-ASCII counts, because a
+// JS identifier may be Unicode (`import { café } from "x"`) and treating one
+// as a clause break skips the whole statement — losing the import silently,
+// the failure sc-6670 closes. Still a whitelist, so `export const x = 1`
+// drops out at the `=`.
+const isClauseChar = (ch) => CLAUSE_CHAR.test(ch) || ch.charCodeAt(0) > 0x7f;
+
+/**
+ * EVERY top-level static `import` / `export … from` statement, whatever its
+ * specifier — relative, bare, absolute, or a URL.
+ *
+ * The clause body is walked character by character rather than matched by a
+ * regex, so a MULTI-LINE clause (`import {\n  a,\n  b,\n} from "x"`) is found
+ * like any other. sc-6670: the dev server's own `STATIC_IMPORT_RE` used a
+ * `[^'";\n]` body that could not span newlines, so it served multi-line
+ * imports verbatim; sc-6086 had already hit the same blind spot in the
+ * relative-import guard. One scanner, so the guard, the packer, and the dev
+ * server's rewriter agree on what an import is (CLAUDE.md §3).
+ *
+ * Offsets index the ORIGINAL source (the mask is length-preserving), so a
+ * caller may splice on `quoteStart` / `quoteEnd` — the positions of the
+ * opening and closing quote — without re-finding the specifier.
+ *
+ * Best-effort by contract: it may miss an exotic clause, which costs a missing
+ * warning or an un-rewritten import. Never use it to decide what the packer
+ * emits.
+ *
+ * @param {string} source
+ * @returns {Array<{start:number,end:number,specifier:string,quoteStart:number,quoteEnd:number}>}
+ */
+export function findImportStatements(source) {
+  const mask = maskCode(source);
+  const depth = braceDepths(mask);
+  const out = [];
+  // `[^\S\n]` is `\s` minus the newline that anchors the boundary — so a
+  // leading BOM or non-breaking space before the first `import` still scans.
+  const kw = /(?:^|[\n;])[^\S\n]*(import|export)\b/g;
+  let m;
+  while ((m = kw.exec(mask))) {
+    const keyword = m[1];
+    const startsAt = m.index + m[0].length - keyword.length;
+    if (depth[startsAt] !== 0) continue;
+
+    let i = m.index + m[0].length;
+    let ok = true;
+    while (i < mask.length) {
+      const ch = mask[i];
+      if (ch === '"' || ch === "'") break;
+      if (
+        ch === "f" &&
+        mask.startsWith("from", i) &&
+        !/[\w$]/.test(mask[i - 1] || " ") &&
+        !/[\w$]/.test(mask[i + 4] || " ")
+      ) {
+        i += 4;
+        while (i < mask.length && /\s/.test(mask[i])) i += 1;
+        break;
+      }
+      if (!isClauseChar(ch)) {
+        ok = false;
+        break;
+      }
+      i += 1;
+    }
+    if (!ok || i >= mask.length) continue;
+
+    const quote = mask[i];
+    if (quote !== '"' && quote !== "'") continue;
+    const close = mask.indexOf(quote, i + 1);
+    if (close === -1) continue;
+    const specifier = mask.slice(i + 1, close);
+    let end = close + 1;
+    if (mask[end] === ";") end += 1;
+    out.push({
+      start: startsAt,
+      end,
+      specifier,
+      quoteStart: i,
+      quoteEnd: close,
+    });
+    // Resume ON the closing quote: past the specifier's interior (so a `;`
+    // inside it opens no bogus match) but before a trailing `;`, which is
+    // still the boundary for a second import on the same line.
+    kw.lastIndex = close;
+  }
+  return out;
+}
+
+/**
+ * Relative import specifiers only, for the dev server's single-file guard.
+ *
+ * @param {string} source
+ * @returns {Array<{start:number,end:number,specifier:string,quoteStart:number,quoteEnd:number}>}
+ */
+export function findRelativeImportStatements(source) {
+  return findImportStatements(source).filter(
+    (s) => s.specifier.startsWith("./") || s.specifier.startsWith("../"),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// AST-driven analysis — what the packer actually acts on.
+// ---------------------------------------------------------------------------
+
+/** Every binding name a destructuring pattern introduces. */
+function patternNames(node, into) {
+  if (!node) return;
+  switch (node.type) {
+    case "Identifier":
+      into.push(node.name);
+      break;
+    case "ObjectPattern":
+      for (const p of node.properties) {
+        patternNames(p.type === "RestElement" ? p.argument : p.value, into);
+      }
+      break;
+    case "ArrayPattern":
+      for (const el of node.elements) patternNames(el, into);
+      break;
+    case "AssignmentPattern":
+      patternNames(node.left, into);
+      break;
+    case "RestElement":
+      patternNames(node.argument, into);
+      break;
+    default:
+      break;
+  }
+}
+
+function declarationBindings(decl, kinds) {
+  const names = [];
+  if (!decl) return names;
+  if (decl.type === "VariableDeclaration") {
+    for (const d of decl.declarations) patternNames(d.id, names);
+    for (const n of names) kinds?.set(n, decl.kind);
+  } else if (decl.id) {
+    names.push(decl.id.name);
+    kinds?.set(
+      decl.id.name,
+      decl.type === "ClassDeclaration" ? "class" : "function",
+    );
+  }
+  return names;
+}
+
+const FUNCTION_LIKE = new Set([
+  "FunctionDeclaration",
+  "FunctionExpression",
+  "ArrowFunctionExpression",
+  "ObjectMethod",
+  "ClassMethod",
+  "ClassPrivateMethod",
+]);
+
+/**
+ * `var` bindings nested in a block are still MODULE-scoped, so two modules can
+ * silently share one — `if (x) { var SEEN = … }` in both an entry and a sibling
+ * produced a bundle that parsed and read the wrong value. Descend through
+ * statements but never into a function, which starts a new var scope.
+ */
+function collectNestedVars(node, into, kinds) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) collectNestedVars(child, into, kinds);
+    return;
+  }
+  if (FUNCTION_LIKE.has(node.type)) return;
+  if (node.type === "VariableDeclaration" && node.kind === "var") {
+    for (const d of node.declarations) {
+      const names = [];
+      patternNames(d.id, names);
+      for (const n of names) {
+        into.push(n);
+        kinds?.set(n, "var");
+      }
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (
+      key === "loc" ||
+      key === "leadingComments" ||
+      key === "trailingComments"
+    )
+      continue;
+    collectNestedVars(node[key], into, kinds);
+  }
+}
+
+const line = (source, index) => source.slice(0, index).split("\n").length;
+
+/** Every node in an AST, depth-first. */
+function* walk(node) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) yield* walk(child);
+    return;
+  }
+  if (typeof node.type === "string") yield node;
+  for (const key of Object.keys(node)) {
+    if (
+      key === "loc" ||
+      key === "leadingComments" ||
+      key === "trailingComments"
+    )
+      continue;
+    yield* walk(node[key]);
+  }
+}
+
+/**
+ * Everything the flattener needs about one module, straight from its AST.
+ *
+ * @param {string} source
+ * @param {string} rel  for error messages.
+ * @param {Function} parse
+ * @param {boolean} isEntry  the entry keeps its own exports; a sibling may not.
+ */
+function analyze(source, rel, parse, isEntry) {
+  let ast;
+  try {
+    ast = parse(source, {
+      sourceType: "module",
+      errorRecovery: false,
+      plugins: ["jsx"],
+    });
+  } catch (err) {
+    throw new Error(`${rel}: does not parse — ${err.message}`, { cause: err });
+  }
+
+  const siblingImports = [];
+  const bareImports = [];
+  const cuts = [];
+  const names = [];
+  const exported = new Set();
+  const kinds = new Map();
+
+  for (const node of ast.program.body) {
+    if (node.type === "ImportDeclaration") {
+      const spec = node.source.value;
+      // EVERY import is spliced out: a sibling's because it is inlined, a bare
+      // one because the same package imported by two modules would otherwise
+      // emit two `import React from "react"` statements — a duplicate binding.
+      // They are merged and re-emitted once at the top of the bundle.
+      const record = {
+        start: node.start,
+        end: node.end,
+        specifier: spec,
+        line: line(source, node.start),
+        specifiers: node.specifiers,
+      };
+      if (spec.startsWith("./") || spec.startsWith("../"))
+        siblingImports.push(record);
+      else bareImports.push(record);
+      continue;
+    }
+
+    if (node.type === "ExportAllDeclaration") {
+      throw new Error(
+        `${rel}:${line(source, node.start)}: \`export * from "${node.source.value}"\` cannot ` +
+          `be inlined — the re-export would be silently dropped from the bundle.`,
+      );
+    }
+
+    if (node.type === "ExportNamedDeclaration") {
+      if (node.source) {
+        throw new Error(
+          `${rel}:${line(source, node.start)}: \`export … from "${node.source.value}"\` cannot ` +
+            `be inlined — the re-export would be silently dropped from the bundle. Import ` +
+            `the names, then export them from the entry.`,
+        );
+      }
+      if (isEntry) {
+        names.push(...declarationBindings(node.declaration, kinds));
+        collectNestedVars(node.declaration, names, kinds);
+        continue;
+      }
+      if (!node.declaration) {
+        throw new Error(
+          `${rel}:${line(source, node.start)}: a sibling module may only use named ` +
+            `declaration exports (export function|const|let|var|class NAME) — found ` +
+            `\`export { … }\`. Rewrite it as a named export, or move the code into the entry.`,
+        );
+      }
+      const decl = node.declaration;
+      if (
+        decl.type === "VariableDeclaration" &&
+        decl.declarations.some((d) => d.id.type !== "Identifier")
+      ) {
+        throw new Error(
+          `${rel}:${line(source, node.start)}: a sibling module may not export a destructuring ` +
+            `pattern — name each binding with its own \`export ${decl.kind} NAME = …\`.`,
+        );
+      }
+      const bound = declarationBindings(decl, kinds);
+      names.push(...bound);
+      for (const n of bound) exported.add(n);
+      // Cut ONLY the keyword, so a comment between it and the declaration
+      // survives — those comments carry the analyzer's rule licences.
+      cuts.push({ start: node.start, end: node.start + "export".length });
+      continue;
+    }
+
+    if (node.type === "ExportDefaultDeclaration") {
+      if (isEntry) continue;
+      throw new Error(
+        `${rel}:${line(source, node.start)}: a sibling module may only use named declaration ` +
+          `exports — found \`export default\`. Rewrite it as a named export, or move the ` +
+          `code into the widget entry.`,
+      );
+    }
+
+    names.push(...declarationBindings(node, kinds));
+    collectNestedVars(node, names, kinds);
+  }
+
+  for (const node of walk(ast.program)) {
+    const isDynamicImport =
+      node.type === "ImportExpression" ||
+      (node.type === "CallExpression" && node.callee?.type === "Import");
+    if (!isDynamicImport) continue;
+    const arg =
+      node.type === "ImportExpression" ? node.source : node.arguments[0];
+    // A non-literal argument cannot be resolved at pack time either, so a
+    // template-literal specifier must not slip through as "not relative".
+    const value = arg?.type === "StringLiteral" ? arg.value : null;
+    if (value === null || /^\.\.?\//.test(value)) {
+      throw new Error(
+        `${rel}:${line(source, node.start)}: dynamic import(${value ? `"${value}"` : "…"}) ` +
+          `cannot be inlined. The dev server rewrites it, so this works locally and breaks at ` +
+          `publish — use a static import.`,
+      );
+    }
+  }
+
+  // Names the module reassigns anywhere. Used to refuse an alias, which is a
+  // snapshot; a real ESM import tracks the reassignment.
+  const reassigned = new Set();
+  for (const node of walk(ast.program)) {
+    if (
+      node.type === "AssignmentExpression" &&
+      node.left?.type === "Identifier"
+    ) {
+      reassigned.add(node.left.name);
+    } else if (
+      node.type === "UpdateExpression" &&
+      node.argument?.type === "Identifier"
+    ) {
+      reassigned.add(node.argument.name);
+    }
+  }
+
+  return {
+    siblingImports,
+    bareImports,
+    cuts,
+    names,
+    exported,
+    kinds,
+    reassigned,
+  };
+}
+
+/** Remove spans from a source, leaving every other byte untouched. */
+function spliceOut(source, spans) {
+  const ordered = [...spans].sort((a, b) => a.start - b.start);
+  let out = "";
+  let cursor = 0;
+  for (const { start, end } of ordered) {
+    if (start < cursor) continue;
+    out += source.slice(cursor, start);
+    cursor = end;
+  }
+  return out + source.slice(cursor);
+}
+
+/**
+ * Merge every module's bare imports into one deduplicated block.
+ *
+ * Two modules importing `React` is ordinary — every first-party entry does it —
+ * so the same binding from the same package collapses to one statement. One
+ * local name meaning two different things is a real conflict and throws.
+ */
+const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/;
+
+function mergeBareImports(records) {
+  const bySource = new Map();
+  const boundBy = new Map(); // local -> descriptor, for conflict detection
+
+  const claim = (local, descriptor, rel) => {
+    const prev = boundBy.get(local);
+    if (prev && prev.descriptor !== descriptor) {
+      throw new Error(
+        `"${local}" is imported as both ${prev.descriptor} (in ${prev.rel}) and ` +
+          `${descriptor} (in ${rel}) — inlining puts every module in one scope, so a local ` +
+          `name cannot mean two bindings.`,
+      );
+    }
+    boundBy.set(local, { descriptor, rel });
+  };
+
+  for (const { rel, record } of records) {
+    const src = record.specifier;
+    if (!bySource.has(src)) {
+      bySource.set(src, {
+        // Sets, not single slots: an entry and a sibling may import the same
+        // package under DIFFERENT local names. Overwriting one erased it from
+        // the bundle while the body still referenced it — a ReferenceError on
+        // load, from a bundle that parsed and linted clean.
+        defaults: new Set(),
+        namespaces: new Set(),
+        named: new Map(),
+        sideEffect: false,
+      });
+    }
+    const entry = bySource.get(src);
+    if (record.specifiers.length === 0) {
+      entry.sideEffect = true;
+      continue;
+    }
+    for (const s of record.specifiers) {
+      if (s.type === "ImportDefaultSpecifier") {
+        claim(s.local.name, `the default export of "${src}"`, rel);
+        entry.defaults.add(s.local.name);
+      } else if (s.type === "ImportNamespaceSpecifier") {
+        claim(s.local.name, `a namespace of "${src}"`, rel);
+        entry.namespaces.add(s.local.name);
+      } else {
+        const imported = s.imported.name ?? s.imported.value;
+        // `{ default as X }` and a plain default import name one binding.
+        if (imported === "default") {
+          claim(s.local.name, `the default export of "${src}"`, rel);
+          entry.defaults.add(s.local.name);
+          continue;
+        }
+        claim(s.local.name, `"${imported}" from "${src}"`, rel);
+        entry.named.set(`${imported}::${s.local.name}`, {
+          imported,
+          local: s.local.name,
+        });
+      }
+    }
+  }
+
+  const lines = [];
+  for (const [src, entry] of bySource) {
+    const [firstDefault, ...extraDefaults] = [...entry.defaults];
+    const clause = [];
+    if (firstDefault) clause.push(firstDefault);
+    if (entry.named.size > 0) {
+      const inner = [...entry.named.values()]
+        .map(({ imported, local }) => {
+          // An arbitrary module-namespace name (`import { "a-b" as ab }`) is
+          // not an identifier and must stay quoted when re-emitted.
+          const name = IDENTIFIER_RE.test(imported)
+            ? imported
+            : JSON.stringify(imported);
+          return name === local ? local : `${name} as ${local}`;
+        })
+        .join(", ");
+      clause.push(`{ ${inner} }`);
+    }
+    if (clause.length > 0)
+      lines.push(`import ${clause.join(", ")} from "${src}";`);
+    // Each additional local for the same binding gets its own statement —
+    // legal ESM, and the only way to keep every one of them.
+    for (const extra of extraDefaults) {
+      lines.push(`import ${extra} from "${src}";`);
+    }
+    // A namespace cannot share a statement with a default or named clause.
+    for (const ns of entry.namespaces) {
+      lines.push(`import * as ${ns} from "${src}";`);
+    }
+    if (
+      clause.length === 0 &&
+      entry.namespaces.size === 0 &&
+      entry.sideEffect
+    ) {
+      lines.push(`import "${src}";`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Flatten `entryRel`'s sibling graph into a single ESM source.
+ *
+ * @param {object} opts
+ * @param {string} opts.entryRel  POSIX rel-path of the entry inside the widget dir.
+ * @param {(rel: string) => string} opts.readModule  reads a module by rel-path.
+ * @param {(fromRel: string, specifier: string) => string | null} opts.resolve
+ *   the SAME resolver `appstudio-widget dev` uses; null when the target
+ *   escapes the widget directory.
+ * @param {Function} opts.parse  `@babel/parser`'s `parse`.
+ * @returns {{ source: string, modules: string[] }} entry first.
+ */
+export function flattenEntry({ entryRel, readModule, resolve, parse }) {
+  if (typeof parse !== "function") {
+    throw new Error(
+      "flattenEntry needs a `parse` (@babel/parser) — refusing to guess.",
+    );
+  }
+
+  const sources = new Map();
+  const read = (rel) => {
+    if (!sources.has(rel)) sources.set(rel, readModule(rel));
+    return sources.get(rel);
+  };
+  const analyses = new Map();
+  const analysisOf = (rel) => {
+    if (!analyses.has(rel)) {
+      analyses.set(rel, analyze(read(rel), rel, parse, rel === entryRel));
+    }
+    return analyses.get(rel);
+  };
+
+  const visiting = new Set();
+  const emitted = new Map(); // rel -> { code, aliases: [string] }
+  const order = [];
+  const declaredBy = new Map();
+  // local -> { imported, target } — one alias declaration per bundle, emitted
+  // with the module that DECLARES the binding. Post-order guarantees a target
+  // precedes every module that imports from it, so the alias is always
+  // initialised before any module scope can read it. Attaching it to the
+  // importer instead put the entry's claim last, and a sibling reading it at
+  // module scope hit a TDZ error.
+  const aliasOwner = new Map();
+  const aliasesByTarget = new Map(); // target rel -> ["const p = pad;", …]
+
+  function visit(rel, stack) {
+    if (emitted.has(rel)) return;
+    if (visiting.has(rel)) {
+      throw new Error(
+        `circular sibling import: ${[...stack, rel].join(" → ")}. The packer inlines ` +
+          `siblings into one module, which a cycle cannot express — break the cycle.`,
+      );
+    }
+    visiting.add(rel);
+
+    const source = read(rel);
+    const { siblingImports, bareImports, cuts, names } = analysisOf(rel);
+
+    for (const st of siblingImports) {
+      const target = resolve(rel, st.specifier);
+      if (!target) {
+        throw new Error(
+          `${rel}:${st.line}: relative import "${st.specifier}" does not resolve to a file ` +
+            `inside the widget directory. A bundle may only inline its own sibling modules — ` +
+            `\`../\` escapes and asset imports are not packable.`,
+        );
+      }
+      if (/\.json$/i.test(target)) {
+        throw new Error(
+          `${rel}:${st.line}: cannot inline "${st.specifier}" — a JSON module has no ` +
+            `declarations to fold into the bundle. Move the data into a .js sibling.`,
+        );
+      }
+      visit(target, [...stack, rel]);
+      const targetAnalysis = analysisOf(target);
+
+      for (const s of st.specifiers) {
+        if (s.type === "ImportNamespaceSpecifier") {
+          throw new Error(
+            `${rel}:${st.line}: \`import * as ${s.local.name}\` from a sibling cannot be ` +
+              `inlined — the sibling's declarations are folded into this module's scope, so ` +
+              `there is no namespace object. Import the names individually.`,
+          );
+        }
+        if (s.type === "ImportDefaultSpecifier") {
+          throw new Error(
+            `${rel}:${st.line}: default-importing sibling "${st.specifier}" is not supported — ` +
+              `a sibling may only use named declaration exports.`,
+          );
+        }
+        const imported = s.imported.name ?? s.imported.value;
+        if (!targetAnalysis.exported.has(imported)) {
+          throw new Error(
+            `${rel}:${st.line}: imports "${imported}" from "${st.specifier}", which does not ` +
+              `export it. Inlining would leave the name undefined at runtime.`,
+          );
+        }
+        if (s.local.name === imported) continue;
+        // An alias becomes `const local = target`, which SNAPSHOTS the value.
+        // A real ESM import is a live binding, so aliasing anything the target
+        // module reassigns would silently diverge — including a `function` or
+        // `class` binding, which the old `let`/`var` proxy missed (the
+        // self-overwriting `config = () => v` memoisation idiom). Conservative
+        // by design: a same-named local inside a function also trips this, and
+        // refusing is the safe direction.
+        if (targetAnalysis.reassigned.has(imported)) {
+          throw new Error(
+            `${rel}:${st.line}: cannot alias "${imported}" as "${s.local.name}" — ${target} ` +
+              `reassigns it, and the inlined alias would snapshot its value instead of tracking ` +
+              `the reassignment the way a real ESM import does. Import it under its own name.`,
+          );
+        }
+        // One `const` per alias for the WHOLE bundle: two modules aliasing the
+        // same helper must not each emit one, or the bundle stops parsing.
+        const owner = aliasOwner.get(s.local.name);
+        if (owner) {
+          if (owner.imported !== imported) {
+            throw new Error(
+              `${rel}:${st.line}: "${s.local.name}" is aliased to "${imported}" here but to ` +
+                `"${owner.imported}" in ${owner.rel} — one local name cannot mean two bindings.`,
+            );
+          }
+          continue;
+        }
+        const collision = declaredBy.get(s.local.name);
+        if (collision !== undefined) {
+          throw new Error(
+            `${rel}:${st.line}: aliases "${imported}" as "${s.local.name}", but ${collision} ` +
+              `declares a top-level "${s.local.name}". Inlining puts them in one scope — ` +
+              `rename one of them.`,
+          );
+        }
+        aliasOwner.set(s.local.name, { imported, target, rel });
+        declaredBy.set(s.local.name, target);
+        if (!aliasesByTarget.has(target)) aliasesByTarget.set(target, []);
+        aliasesByTarget
+          .get(target)
+          .push(`const ${s.local.name} = ${imported};`);
+      }
+    }
+
+    for (const name of names) {
+      const prev = declaredBy.get(name);
+      if (prev !== undefined && prev !== rel) {
+        throw new Error(
+          `duplicate top-level name "${name}" — declared in both ${prev} and ${rel}. ` +
+            `Inlining siblings puts every module in one scope, so a top-level name must be ` +
+            `unique across the widget's modules.`,
+        );
+      }
+      declaredBy.set(name, rel);
+    }
+
+    emitted.set(rel, {
+      code: spliceOut(source, [...siblingImports, ...bareImports, ...cuts]),
+    });
+    visiting.delete(rel);
+    order.push(rel);
+  }
+
+  visit(entryRel, []);
+
+  if (order.length === 1) {
+    // No siblings — the entry packs byte-for-byte as it always has.
+    return { source: read(entryRel), modules: [entryRel] };
+  }
+
+  const siblings = order.filter((rel) => rel !== entryRel);
+  const bareRecords = order.flatMap((rel) =>
+    analysisOf(rel).bareImports.map((record) => ({ rel, record })),
+  );
+  // An imported local and a declared name share the bundle's one scope.
+  for (const { rel, record } of bareRecords) {
+    for (const s of record.specifiers) {
+      const owner = declaredBy.get(s.local.name);
+      if (owner !== undefined) {
+        throw new Error(
+          `${rel}: imports "${s.local.name}" from "${record.specifier}", but ${owner} declares a ` +
+            `top-level "${s.local.name}". Inlining puts them in one scope — rename one of them.`,
+        );
+      }
+    }
+  }
+  const importBlock = mergeBareImports(bareRecords);
+
+  // Each module's aliases sit with that module, so a sibling that uses an
+  // aliased binding at module scope reads an initialised `const`.
+  const render = (rel, header) => {
+    const { code } = emitted.get(rel);
+    // Aliases follow the body that declares what they name.
+    const aliases = aliasesByTarget.get(rel) ?? [];
+    return `${header}${code.trim()}\n${aliases.length ? `${aliases.join("\n")}\n` : ""}`;
+  };
+
+  const parts = [];
+  if (importBlock) parts.push(`${importBlock}\n`);
+  for (const rel of siblings) {
+    parts.push(
+      render(
+        rel,
+        `// ---- inlined from ${rel} (sc-6086: a first-party bundle ships as one module) ----\n`,
+      ),
+    );
+  }
+  parts.push(render(entryRel, ""));
+
+  // `;` between parts, not just a newline: a module whose last statement omits
+  // its semicolon would otherwise fuse with the next part's first token under
+  // ASI — `const f = () => x` followed by `(function(){})()` becomes a call,
+  // which parses cleanly and does the wrong thing.
+  return { source: parts.join("\n;\n"), modules: [entryRel, ...siblings] };
+}