@ikas/component-cli 1.4.0-beta.23 → 1.4.0-beta.231

package/dist/utils/compile.js

@@ -4,6 +4,10 @@ import * as os from "os";
 import * as path from "path";
 import { resolveCssImports } from "./css-import-resolver.js";
 import { ikasComponentUtilsPlugin } from "./observer-runtime.js";
+import { storefrontTPlugin } from "./storefront-t.js";
+import { forbidDeepStorefrontImportsPlugin } from "./forbid-deep-imports.js";
+import { forbidExternalPackagesPlugin } from "./forbid-external-packages.js";
+import { isVendoredDependencyFile, vendorStorefrontPlugin } from "./vendor-storefront.js";
 /**
  * Shim that provides the JSX factory/fragment under collision-proof names.
  *
@@ -21,26 +25,45 @@ import { ikasComponentUtilsPlugin } from "./observer-runtime.js";
 const PREACT_JSX_SHIM = path.join(os.tmpdir(), "ikas-preact-jsx-shim.mjs");
 fs.writeFileSync(PREACT_JSX_SHIM, 'export{h as __ikas_h,Fragment as __ikas_Fragment}from"preact";\n');
 /**
- * External dependencies - these will be provided by the generated storefront
+ * External dependencies - these will be provided by the generated storefront.
+ *
+ * The `@ikas/bp-storefront*` packages are intentionally NOT listed here: they are externalized
+ * by `forbidDeepStorefrontImportsPlugin()` instead, which externalizes the allowed ROOT import
+ * and rejects private deep subpaths. (esbuild applies this `external` array before plugin
+ * onResolve, so keeping them here would let `/dist/...` deep imports slip through unchecked.)
  */
 const SERVER_EXTERNALS = [
     "preact",
     "preact/hooks",
     "preact-render-to-string",
-    "mobx",
-    "@ikas/bp-storefront",
-    "@ikas/bp-storefront-models",
-    "@ikas/bp-storefront-config",
-    "@ikas/bp-storefront-api"
+    "mobx"
 ];
 const CLIENT_EXTERNALS = [
     "preact",
     "preact/hooks",
-    "mobx",
-    "@ikas/bp-storefront",
-    "@ikas/bp-storefront-models",
-    "@ikas/bp-storefront-config"
+    "mobx"
 ];
+/**
+ * The server and client builds MUST compile with the SAME esbuild `target` so
+ * syntax is lowered identically and code-split shared chunks come out
+ * byte-identical (same content hash) on both sides.
+ *
+ * If the targets diverge (previously server=node18 vs client=es2020), esbuild
+ * lowers modern syntax differently: e.g. a class field (`x = 1`, ES2022) stays
+ * native on node18 but is down-leveled into a `__publicField` helper on es2020.
+ * That helper lands in the shared runtime-helper chunk, so the helper chunk's
+ * hash differs between builds — and every chunk that imports it by hashed name
+ * (`./chunk-<hash>.js`) diverges too. The result is "server-only" shared chunks
+ * with no client twin, which the client-derived `usedSharedModuleIds` never
+ * lists, so they get pruned/dropped downstream ("Could not resolve
+ * ./chunk-XXXX.js" at SSR build).
+ *
+ * es2020 is the floor the browser build needs; node18 executes es2020 fine, so
+ * both builds use es2020 and produce identical shared chunks. Keep this the
+ * single source of truth for both `platform: node` and `platform: browser`
+ * builds — do not set per-build `target` overrides.
+ */
+const SHARED_BUILD_TARGET = "es2020";
 /**
  * Compile a single component's TSX and CSS
  */
@@ -52,10 +75,15 @@ export async function compileComponent(entryPath, stylesPath, componentId) {
             entryPoints: [path.resolve(process.cwd(), entryPath)],
             format: "esm",
             platform: "node",
-            target: "node18",
+            target: SHARED_BUILD_TARGET,
             write: false,
             external: SERVER_EXTERNALS,
-            plugins: [ikasComponentUtilsPlugin()],
+            plugins: [
+                forbidDeepStorefrontImportsPlugin(),
+                forbidExternalPackagesPlugin(),
+                ikasComponentUtilsPlugin(),
+                storefrontTPlugin(),
+            ],
         });
         // Build client bundle (for hydration)
         const clientResult = await esbuild.build({
@@ -63,17 +91,37 @@ export async function compileComponent(entryPath, stylesPath, componentId) {
             entryPoints: [path.resolve(process.cwd(), entryPath)],
             format: "esm",
             platform: "browser",
-            target: "es2020",
+            target: SHARED_BUILD_TARGET,
             write: false,
             external: CLIENT_EXTERNALS,
-            plugins: [ikasComponentUtilsPlugin()],
+            // Needed for the sibling-CSS collection below: the input list tells us which
+            // sub-component directories this entry actually pulled in.
+            metafile: true,
+            plugins: [
+                forbidDeepStorefrontImportsPlugin(),
+                forbidExternalPackagesPlugin(),
+                ikasComponentUtilsPlugin(),
+                storefrontTPlugin(),
+            ],
         });
-        // Read CSS (with import resolution)
+        // Read CSS (with import resolution). Track what the @imports inlined so the
+        // sibling pass below cannot append the same file twice.
         const cssPath = path.resolve(process.cwd(), stylesPath);
+        const inlinedCssPaths = new Set();
         let css = "";
         if (fs.existsSync(cssPath)) {
             const rawCss = fs.readFileSync(cssPath, "utf-8");
-            css = resolveCssImports(rawCss, cssPath);
+            css = resolveCssImports(rawCss, cssPath, inlinedCssPaths);
+        }
+        // Collect each bundled sub-component's sibling styles.css, the same way the
+        // multi-component pipeline (`dev`/`publish`) does. Without this, CSS that works
+        // under `dev` silently vanishes from a `build` artifact.
+        const entryDir = path.dirname(path.resolve(process.cwd(), entryPath));
+        for (const depCssPath of collectSourceCssFiles(Object.keys(clientResult.metafile.inputs), entryDir)) {
+            if (inlinedCssPaths.has(path.resolve(depCssPath)))
+                continue;
+            const rawDepCss = fs.readFileSync(depCssPath, "utf-8");
+            css += "\n" + resolveCssImports(rawDepCss, depCssPath, inlinedCssPaths);
         }
         // Scope CSS
         const scopedCss = scopeCSS(css, componentId);
@@ -90,16 +138,32 @@ export async function compileComponent(entryPath, stylesPath, componentId) {
             serverJs: "",
             clientJs: "",
             scopedCss: "",
-            error: error.message || String(error)
+            error: withCssImportHint(error.message || String(error))
         };
     }
 }
+// esbuild's raw message when a TSX file does `import "./styles.css"` gives no clue about the
+// ikas conventions; append a hint pointing at the two supported CSS paths.
+function withCssImportHint(message) {
+    if (/Cannot import "[^"]*\.css"/.test(message) || /No loader is configured for "\.css" files/.test(message)) {
+        return (message +
+            "\n\nHint: do not import CSS from TSX. A sub-component's sibling styles.css is collected " +
+            "automatically by every command (`dev`, `publish`, `build`) — just leave it next to the " +
+            "sub-component. To pull in CSS that has no sibling source file, @import it from the " +
+            "parent component's styles.css.");
+    }
+    return message;
+}
 /**
- * Scope CSS selectors with a component-specific class prefix
+ * Scope CSS selectors with a component-specific class prefix, then namespace any
+ * document-global CSS identifiers (`@keyframes`, `@font-face` font-family,
+ * `@counter-style`) DEFINED in this component so two components — or the host theme —
+ * declaring the same name can't collide in the page's global namespace.
  */
 export function scopeCSS(css, componentId) {
     const scopeClass = `cc_${componentId.replace(/[^a-zA-Z0-9]/g, "_")}`;
-    return scopeCSSWithClasses(css, [scopeClass]);
+    const scoped = scopeCSSWithClasses(css, [scopeClass]);
+    return renameCollidingGlobals(scoped, `${scopeClass}_`);
 }
 /**
  * Scope CSS selectors with multiple class prefixes (for shared chunks).
@@ -109,63 +173,523 @@ export function scopeCSSMulti(css, componentIds) {
     const scopeClasses = componentIds.map(id => `cc_${id.replace(/[^a-zA-Z0-9]/g, "_")}`);
     return scopeCSSWithClasses(css, scopeClasses);
 }
+// Conditional group at-rules whose blocks nest normal style rules and must be
+// scoped recursively. This is an ALLOWLIST on purpose: at-rules NOT listed here
+// (@keyframes, @font-face, @page, @property, @counter-style, ...) have non-selector
+// bodies — e.g. @keyframes contains `0%`/`from` keyframe selectors that must NOT be
+// prefixed — so their bodies are copied through untouched. Vendor-prefixed conditional
+// rules (@-moz-document) match via the optional prefix group; @-webkit-keyframes does
+// NOT match (the alternation excludes "keyframes"), which is what we want.
+//
+// NOTE: This scoper is duplicated in editor-models/src/helpers/code-component-css-scope.ts
+// (the editor-preview / code-generator path). The CLI ships standalone to npm and cannot
+// import that private package, so the two intentionally diverge. Keep parsing fixes in sync.
+const NESTING_AT_RULES = /^@(?:-\w+-)?(media|supports|container|layer|document|scope|starting-style)\b/i;
 /**
- * Internal: scope CSS selectors with one or more scope class prefixes
+ * Internal: scope CSS selectors with one or more scope class prefixes.
+ *
+ * Character-based walker, NOT line-based: a rule's selector list is everything up
+ * to its opening `{`, so lists written across multiple lines (`.a,\n.b { ... }`)
+ * are scoped as a whole. The previous line-based implementation only scoped the
+ * selector fragment sharing a line with `{`, leaving the other selectors unscoped
+ * (they either lost the cascade to scoped rules or leaked into other components).
+ *
+ * Comments, string literals, and `\` escapes are treated as inert spans (via
+ * `skipInertSpan`) by every structural scanner, so a `{`, `}`, `;`, or `,` that
+ * appears inside a comment / string / escape can never be mistaken for real
+ * structure (which would otherwise drop the scope prefix and leak styles globally).
  */
 function scopeCSSWithClasses(css, scopeClasses) {
-    const lines = css.split("\n");
-    const scopedLines = [];
-    let inMediaQuery = false;
-    let keyframesDepth = 0;
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            scopedLines.push(line);
+    let out = "";
+    for (let i = 0; i < css.length;) {
+        const ch = css[i];
+        // Copy comments verbatim
+        if (ch === "/" && css[i + 1] === "*") {
+            const end = css.indexOf("*/", i + 2);
+            if (end === -1)
+                return out + css.slice(i);
+            out += css.slice(i, end + 2);
+            i = end + 2;
+            continue;
+        }
+        // Copy whitespace and stray closing braces
+        if (/\s/.test(ch) || ch === "}") {
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === "@") {
+            const headerEnd = findAtRuleHeaderEnd(css, i);
+            // Block-less at-rule (@import, @charset, @layer a;, ...) — copy through
+            if (headerEnd >= css.length || css[headerEnd] === ";") {
+                out += css.slice(i, Math.min(headerEnd + 1, css.length));
+                i = headerEnd + 1;
+                continue;
+            }
+            const header = css.slice(i, headerEnd);
+            const blockEnd = findBlockEnd(css, headerEnd + 1);
+            const body = css.slice(headerEnd + 1, blockEnd);
+            const transformed = NESTING_AT_RULES.test(header.trim())
+                ? scopeCSSWithClasses(body, scopeClasses)
+                : body;
+            // Always emit the closing brace: when the source block is unterminated
+            // (blockEnd === css.length) this repairs it, so concatenated component CSS
+            // can't leak one component's block over the next.
+            out += `${header}{${transformed}}`;
+            i = blockEnd + 1;
             continue;
         }
-        if (trimmed.startsWith("@media")) {
-            inMediaQuery = true;
-            scopedLines.push(line);
+        // Normal style rule: selector list runs up to the rule's opening `{`
+        const selEnd = findSelectorListEnd(css, i);
+        if (selEnd >= css.length) {
+            // Trailing content with no block (e.g. a dangling declaration at EOF) — copy through
+            out += css.slice(i);
+            break;
+        }
+        if (css[selEnd] === ";") {
+            // A stray top-level `;` (or a stray declaration fragment ending in `;`) — not a rule.
+            // DROP it. Copying it through is not enough: per the CSS syntax spec a browser folds a
+            // stray `;` into the NEXT rule's prelude when consuming a qualified rule, which makes
+            // that selector invalid and drops the whole following rule. Dropping the stray token
+            // keeps the next rule valid and correctly scoped.
+            i = selEnd + 1;
             continue;
         }
-        if (trimmed.startsWith("@keyframes") || trimmed.startsWith("@-webkit-keyframes")) {
-            keyframesDepth = 1;
-            scopedLines.push(line);
+        if (css[selEnd] === "}") {
+            // Content before a stray closing brace — copy through verbatim and let the main loop
+            // emit the `}`.
+            out += css.slice(i, selEnd);
+            i = selEnd;
             continue;
         }
-        // Inside @keyframes: track brace depth, pass lines through unscoped
-        if (keyframesDepth > 0) {
-            for (const ch of trimmed) {
-                if (ch === "{")
-                    keyframesDepth++;
-                else if (ch === "}")
-                    keyframesDepth--;
+        const selectorList = css.slice(i, selEnd);
+        const blockEnd = findBlockEnd(css, selEnd + 1);
+        const body = css.slice(selEnd + 1, blockEnd);
+        const scopedSelector = splitSelectorList(selectorList)
+            .map(s => s.trim())
+            .filter(Boolean)
+            .flatMap(s => scopeClasses.map(cls => `.${cls} ${s}`))
+            .join(", ");
+        // Always emit the closing brace (see at-rule branch above for rationale).
+        out += `${scopedSelector} {${body}}`;
+        i = blockEnd + 1;
+    }
+    return out;
+}
+/**
+ * If an inert span — a `/* ... *\/` comment, a `"..."` / `'...'` string literal, an
+ * unquoted `url(...)` token, or a `\x` escape — starts at `s[i]`, return the index just
+ * past it; otherwise return -1.
+ *
+ * Every structural scanner below funnels through this so that delimiters (`{ } ; , ( )`)
+ * living inside comments, strings, urls, or escapes are never treated as structure. String
+ * scanning honors `\` escapes and stops at a raw newline, matching CSS "bad-string" error
+ * recovery (an unterminated string ends at the line break) so a missing quote can't
+ * swallow every rule that follows it.
+ */
+function skipInertSpan(s, i) {
+    const c = s[i];
+    if (c === "/" && s[i + 1] === "*") {
+        const end = s.indexOf("*/", i + 2);
+        return end === -1 ? s.length : end + 2;
+    }
+    if (c === '"' || c === "'") {
+        for (let j = i + 1; j < s.length; j++) {
+            const d = s[j];
+            if (d === "\\") {
+                j++; // escape: skip the next char
+                continue;
+            }
+            if (d === c)
+                return j + 1; // closing quote
+            if (d === "\n" || d === "\r" || d === "\f")
+                return j; // bad-string ends at newline
+        }
+        return s.length;
+    }
+    // Unquoted url(...) token: per the CSS tokenizer its content is opaque, so braces,
+    // semicolons, and parens inside it must NOT be read as structure (an unbalanced `}` in
+    // `url(x}y.png)` or `{` in an inline SVG data-uri would otherwise mis-terminate the
+    // enclosing block). A QUOTED url (`url("...")`) is a normal function + string and is left
+    // to the string branch above. `url` must be a standalone ident, not the tail of a longer
+    // identifier like `myurl(`.
+    if ((c === "u" || c === "U") && /^url\(/i.test(s.slice(i, i + 4))) {
+        const prev = i > 0 ? s[i - 1] : "";
+        if (!/[A-Za-z0-9_-]/.test(prev)) {
+            let j = i + 4;
+            while (j < s.length && /\s/.test(s[j]))
+                j++; // optional leading whitespace
+            if (s[j] !== '"' && s[j] !== "'") {
+                for (; j < s.length; j++) {
+                    if (s[j] === "\\") {
+                        j++; // escaped char inside the url (e.g. `url(foo\)bar)`)
+                        continue;
+                    }
+                    if (s[j] === ")")
+                        return j + 1; // end of url token
+                }
+                return s.length; // unterminated url() — consume to EOF (bad-url)
             }
-            scopedLines.push(line);
+        }
+    }
+    if (c === "\\")
+        return i + 2; // escaped char outside a string (e.g. `.a\,b`)
+    return -1;
+}
+/** Find the first top-level `{` or `;` that ends an at-rule's header. Respects `()` / `[]`
+ *  and inert spans (strings/comments/escapes). */
+function findAtRuleHeaderEnd(css, start) {
+    let pDepth = 0;
+    for (let j = start; j < css.length;) {
+        const skip = skipInertSpan(css, j);
+        if (skip !== -1) {
+            j = skip;
+            continue;
+        }
+        const c = css[j];
+        if (c === "(" || c === "[")
+            pDepth++;
+        else if (c === ")" || c === "]")
+            pDepth--;
+        else if (pDepth === 0 && (c === "{" || c === ";"))
+            return j;
+        j++;
+    }
+    return css.length;
+}
+/**
+ * Find the matching `}` for the block whose body starts at `blockStart` (char after `{`).
+ * Inert spans are skipped so braces inside `content: "}"`, comments, or escapes don't
+ * terminate the block early.
+ */
+function findBlockEnd(css, blockStart) {
+    let depth = 1;
+    for (let j = blockStart; j < css.length;) {
+        const skip = skipInertSpan(css, j);
+        if (skip !== -1) {
+            j = skip;
             continue;
         }
-        if (trimmed === "}" && inMediaQuery) {
-            inMediaQuery = false;
-            scopedLines.push(line);
+        const c = css[j];
+        if (c === "{")
+            depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0)
+                return j;
+        }
+        j++;
+    }
+    return css.length;
+}
+/** Find the `{`, `}`, or `;` that terminates a selector list. A `}` or `;` here means the
+ *  run was not a real style rule. Respects `()` / `[]` and inert spans. */
+function findSelectorListEnd(css, start) {
+    let pDepth = 0;
+    for (let j = start; j < css.length;) {
+        const skip = skipInertSpan(css, j);
+        if (skip !== -1) {
+            j = skip;
             continue;
         }
-        if (!trimmed.includes("{") || trimmed.startsWith("@")) {
-            scopedLines.push(line);
+        const c = css[j];
+        if (c === "(" || c === "[")
+            pDepth++;
+        else if (c === ")" || c === "]")
+            pDepth--;
+        else if (pDepth === 0 && (c === "{" || c === "}" || c === ";"))
+            return j;
+        j++;
+    }
+    return css.length;
+}
+/** Split a selector list on top-level commas. Respects `()` / `[]` and inert spans, so a
+ *  comma inside a comment, string, or `\` escape (e.g. `.a\,b`) does not split the list. */
+function splitSelectorList(s) {
+    const result = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < s.length;) {
+        const skip = skipInertSpan(s, i);
+        if (skip !== -1) {
+            i = skip;
             continue;
         }
-        const [selector, rest] = line.split("{");
-        if (selector && rest !== undefined) {
-            const scopedSelector = selector
-                .split(",")
-                .flatMap((s) => scopeClasses.map(cls => `.${cls} ${s.trim()}`))
-                .join(", ");
-            scopedLines.push(`${scopedSelector} {${rest}`);
+        const ch = s[i];
+        if (ch === "(" || ch === "[")
+            depth++;
+        else if (ch === ")" || ch === "]")
+            depth--;
+        else if (ch === "," && depth === 0) {
+            result.push(s.slice(start, i));
+            start = i + 1;
         }
-        else {
-            scopedLines.push(line);
+        i++;
+    }
+    result.push(s.slice(start));
+    return result;
+}
+/* ============================================================================
+ * Global-identifier namespacing.
+ *
+ * `@keyframes`, `@font-face` font-family names, and `@counter-style` names live in a
+ * DOCUMENT-GLOBAL namespace — scoping selectors with `.cc_<id>` does not isolate them, so
+ * two components (or the theme) defining the same name would collide (last definition wins
+ * document-wide). `renameCollidingGlobals` prefixes every such name DEFINED in this CSS,
+ * plus its references within the SAME CSS, with the component's scope prefix. Font names are
+ * also rewritten inside custom-property values (`--font-head: "The Seasons"`), so
+ * `font-family: var(--font-head)` keeps resolving after the prefix.
+ *
+ * Only names defined in THIS css are renamed — a reference to a name defined elsewhere
+ * (global.css, a shared chunk, the theme) is left untouched, so cross-file references keep
+ * resolving. Shared-chunk CSS (scopeCSSMulti) is intentionally NOT renamed, to avoid
+ * breaking a chunk-defined keyframe referenced from a consuming component's own CSS.
+ *
+ * NOTE: ported from packages/editor-models/src/helpers/code-component-css-scope.ts
+ * (renameCollidingGlobals + helpers, the global.css path's `cc_<projectId>_` variant).
+ * Keep parsing/rename fixes in sync between the two.
+ * ============================================================================ */
+// Declarations whose VALUE may reference a global identifier of the given type.
+const KEYFRAME_REF_PROPS = new Set(["animation", "animation-name"]);
+const FONT_FAMILY_REF_PROPS = new Set(["font", "font-family"]);
+const COUNTER_STYLE_REF_PROPS = new Set(["list-style", "list-style-type"]);
+function renameCollidingGlobals(css, prefix) {
+    // Comment/string/url-masked copy: defining-site regex scans run against this so a name
+    // inside a comment or `content: "..."` string can't contribute a rename or be rewritten.
+    const scanCss = maskInertSpans(css);
+    const keyframeNames = new Set();
+    const fontFamilyNames = new Set();
+    const counterStyleNames = new Set();
+    // One pass for both at-rules: `scanCss` is position-aligned with `css`, so the offset check is
+    // only valid against the ORIGINAL string. A second `.replace` on the already-rewritten output
+    // would read `scanCss` at shifted offsets and skip every `@counter-style` that follows a
+    // renamed `@keyframes` — leaving the definition raw while references get prefixed.
+    let out = css.replace(/@(keyframes|counter-style)(\s+)([\w-]+)/g, (m, kind, ws, name, offset) => {
+        if (scanCss.substr(offset, kind.length + 1) !== `@${kind}`)
+            return m;
+        (kind === "keyframes" ? keyframeNames : counterStyleNames).add(name);
+        return `@${kind}${ws}${prefix}${name}`;
+    });
+    out = rewriteFontFaceBlocks(out, fontFamilyNames, prefix);
+    if (keyframeNames.size === 0 && fontFamilyNames.size === 0 && counterStyleNames.size === 0) {
+        return out;
+    }
+    return rewriteDeclarationReferences(out, keyframeNames, fontFamilyNames, counterStyleNames, prefix);
+}
+/** Replace every inert span (comment / string / url() / escape) with equal-length spaces so
+ *  position-based regex scans still align but can't match tokens hidden inside them. */
+function maskInertSpans(css) {
+    let out = "";
+    for (let i = 0; i < css.length;) {
+        const skip = skipInertSpan(css, i);
+        if (skip !== -1) {
+            out += " ".repeat(skip - i);
+            i = skip;
+            continue;
         }
+        out += css[i];
+        i++;
+    }
+    return out;
+}
+function rewriteFontFaceBlocks(css, collect, prefix) {
+    const matches = [];
+    css.replace(/@font-face\s*\{/g, (m, offset) => {
+        matches.push({ index: offset, length: m.length });
+        return m;
+    });
+    if (matches.length === 0)
+        return css;
+    let out = "";
+    let lastIdx = 0;
+    for (const match of matches) {
+        const openBraceIdx = match.index + match.length - 1;
+        if (openBraceIdx < lastIdx)
+            continue;
+        const endIdx = findBlockEnd(css, openBraceIdx + 1);
+        const before = css.slice(lastIdx, openBraceIdx + 1);
+        const body = css.slice(openBraceIdx + 1, endIdx);
+        const rewrittenBody = body.replace(/(font-family\s*:\s*)(?:"([^"]+)"|'([^']+)'|([\w-]+))/i, (_m, pre, dq, sq, bare) => {
+            const name = dq || sq || bare;
+            if (!name)
+                return _m;
+            collect.add(name);
+            const prefixed = `${prefix}${name}`;
+            if (dq)
+                return `${pre}"${prefixed}"`;
+            if (sq)
+                return `${pre}'${prefixed}'`;
+            return `${pre}${prefixed}`;
+        });
+        out += before + rewrittenBody + "}";
+        lastIdx = endIdx + 1;
     }
-    return scopedLines.join("\n");
+    out += css.slice(lastIdx);
+    return out;
+}
+function rewriteDeclarationReferences(css, keyframeNames, fontFamilyNames, counterStyleNames, prefix) {
+    const keyframeRe = buildBareIdentRegex(keyframeNames);
+    const fontFamilyRe = buildFontFamilyValueRegex(fontFamilyNames);
+    const counterStyleRe = buildBareIdentRegex(counterStyleNames);
+    // counter(<name>, <style>?) / counters(<name>, <string>, <style>?) — the counter-style
+    // identifier, when present, is always the LAST optional argument.
+    const counterFnRe = counterStyleNames.size > 0
+        ? new RegExp(`(\\bcounters?\\([^)]*?,\\s*)(${bareUnion(counterStyleNames)})(\\s*\\))`, "gi")
+        : null;
+    return mapRuleBlocks(css, block => {
+        return mapDeclarations(block, (prop, value) => {
+            let v = value;
+            const lower = prop.toLowerCase();
+            // A custom property (`--font-head: "The Seasons", serif`) is an opaque token list the author
+            // feeds to `font-family: var(--font-head)`; the definition it names has been prefixed, so
+            // rewrite the font name in there too. Fonts only: keyframe / counter-style names are generic
+            // words and a custom property may be consumed by any property (see KEYFRAME_REF_PROPS).
+            const isCustomProp = lower.startsWith("--");
+            if (keyframeRe && KEYFRAME_REF_PROPS.has(lower)) {
+                v = v.replace(keyframeRe, m => `${prefix}${m}`);
+            }
+            if (fontFamilyRe && (isCustomProp || FONT_FAMILY_REF_PROPS.has(lower))) {
+                v = v.replace(fontFamilyRe, (m, dq, sq, bare) => {
+                    const name = dq || sq || bare;
+                    if (!name || !fontFamilyNames.has(name))
+                        return m;
+                    if (dq !== undefined)
+                        return `"${prefix}${name}"`;
+                    if (sq !== undefined)
+                        return `'${prefix}${name}'`;
+                    return `${prefix}${name}`;
+                });
+            }
+            if (counterStyleRe && COUNTER_STYLE_REF_PROPS.has(lower)) {
+                v = v.replace(counterStyleRe, m => `${prefix}${m}`);
+            }
+            if (counterFnRe) {
+                v = v.replace(counterFnRe, (_m, pre, name, post) => `${pre}${prefix}${name}${post}`);
+            }
+            return v;
+        });
+    });
+}
+function bareUnion(names) {
+    return Array.from(names).map(escapeRegex).join("|");
+}
+function buildBareIdentRegex(names) {
+    if (names.size === 0)
+        return null;
+    return new RegExp(`(?<![\\w-])(?:${bareUnion(names)})(?![\\w-])`, "g");
+}
+function buildFontFamilyValueRegex(names) {
+    if (names.size === 0)
+        return null;
+    const u = bareUnion(names);
+    return new RegExp(`"(${u})"|'(${u})'|(?<![\\w-])(${u})(?![\\w-])`, "g");
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Walk every top-level rule block `{ ... }` (recursing into nested at-rule contents) and
+ * pass the block body through `transform`. Inert spans are skipped so a `{` inside a string
+ * or `url(a{b)` is not mistaken for a block. At-rule preambles and inter-rule whitespace
+ * are left untouched.
+ */
+function mapRuleBlocks(css, transform) {
+    let out = "";
+    for (let i = 0; i < css.length;) {
+        const skip = skipInertSpan(css, i);
+        if (skip !== -1) {
+            out += css.slice(i, skip);
+            i = skip;
+            continue;
+        }
+        if (css[i] === "{") {
+            const blockEnd = findBlockEnd(css, i + 1);
+            const body = css.slice(i + 1, blockEnd);
+            const processed = hasTopLevelBrace(body) ? mapRuleBlocks(body, transform) : transform(body);
+            out += "{" + processed + "}";
+            i = blockEnd + 1;
+            continue;
+        }
+        out += css[i];
+        i++;
+    }
+    return out;
+}
+/** Inert-span-aware: true iff a real `{` appears outside comments/strings/url()/escapes. */
+function hasTopLevelBrace(s) {
+    for (let i = 0; i < s.length;) {
+        const skip = skipInertSpan(s, i);
+        if (skip !== -1) {
+            i = skip;
+            continue;
+        }
+        if (s[i] === "{")
+            return true;
+        i++;
+    }
+    return false;
+}
+/**
+ * Split a rule block body into `prop: value` declarations on top-level `;`, apply
+ * `transform(prop, value)` to each, and rejoin preserving separators. Inert spans are
+ * skipped so a `;` inside a string or `url(a;b)` doesn't split a declaration.
+ */
+function mapDeclarations(body, transform) {
+    const parts = [];
+    let start = 0;
+    let pDepth = 0;
+    for (let i = 0; i < body.length;) {
+        const skip = skipInertSpan(body, i);
+        if (skip !== -1) {
+            i = skip;
+            continue;
+        }
+        const c = body[i];
+        if (c === "(" || c === "[" || c === "{")
+            pDepth++;
+        else if (c === ")" || c === "]" || c === "}")
+            pDepth--;
+        else if (c === ";" && pDepth === 0) {
+            parts.push(body.slice(start, i));
+            start = i + 1;
+        }
+        i++;
+    }
+    parts.push(body.slice(start));
+    return parts
+        .map((part, idx) => {
+        const isLast = idx === parts.length - 1;
+        const colonIdx = findTopLevelColon(part);
+        if (colonIdx === -1)
+            return part + (isLast ? "" : ";");
+        const valueRaw = part.slice(colonIdx + 1);
+        const leading = valueRaw.match(/^\s*/)?.[0] ?? "";
+        const trailing = valueRaw.match(/\s*$/)?.[0] ?? "";
+        const prop = part.slice(0, colonIdx).trim();
+        const value = valueRaw.slice(leading.length, valueRaw.length - trailing.length);
+        const transformed = transform(prop, value);
+        return part.slice(0, colonIdx) + ":" + leading + transformed + trailing + (isLast ? "" : ";");
+    })
+        .join("");
+}
+function findTopLevelColon(s) {
+    let pDepth = 0;
+    for (let i = 0; i < s.length;) {
+        const skip = skipInertSpan(s, i);
+        if (skip !== -1) {
+            i = skip;
+            continue;
+        }
+        const c = s[i];
+        if (c === "(" || c === "[")
+            pDepth++;
+        else if (c === ")" || c === "]")
+            pDepth--;
+        else if (c === ":" && pDepth === 0)
+            return i;
+        i++;
+    }
+    return -1;
 }
 /**
  * Common esbuild options shared between server and client builds
@@ -188,12 +712,52 @@ function commonBuildOptions() {
         sourcemap: false,
     };
 }
+/**
+ * What `import.meta.env` becomes in a vendored build.
+ *
+ * The SDK reads Vite variables (`VITE_BASE_URL`, `VITE_PUBLIC_ANALYTICS_URL`, `VITE_ENV`). While it
+ * was external, the theme's own Vite build substituted them. Vendoring compiles it with esbuild
+ * instead, and `import.meta` is illegal inside the `new Function` the evaluator uses anyway.
+ *
+ * They are NOT baked in at publish time, even though that would be simpler. `VITE_BASE_URL` names
+ * the ikas API the *theme* talks to; a built-in login that authenticated against a different one
+ * would hand back a token the rest of the page cannot use. It has to be whatever the host says it
+ * is, so it is read from the host at evaluation time — configuration from the host, code from the
+ * build, which is the same line every other decision here follows.
+ *
+ * A host that never sets this gets a thrown TypeError on first evaluation, caught and reported per
+ * component. That is deliberate: the alternative, defaulting to `{}`, would silently produce
+ * `undefined/ms/google/login/authenticate` and fail as a confusing 404 much later.
+ */
+const VENDORED_IMPORT_META_ENV = "globalThis.__ikasBuiltinEnv";
+/**
+ * Build the resolution plugins shared by the server and client passes.
+ *
+ * The storefront plugin is either/or, never both: `forbidDeepStorefrontImportsPlugin` externalizes
+ * the SDK root, `vendorStorefrontPlugin` lets it resolve so it gets bundled. Running both would
+ * mean whichever registered its `onResolve` first decides, which is not a contract worth having.
+ */
+function resolutionPlugins(vendorStorefront) {
+    return vendorStorefront
+        ? [
+            vendorStorefrontPlugin(),
+            forbidExternalPackagesPlugin({ allowFrom: isVendoredDependencyFile }),
+            ikasComponentUtilsPlugin(),
+            storefrontTPlugin(),
+        ]
+        : [
+            forbidDeepStorefrontImportsPlugin(),
+            forbidExternalPackagesPlugin(),
+            ikasComponentUtilsPlugin(),
+            storefrontTPlugin(),
+        ];
+}
 /**
  * Compile all components together with esbuild code splitting.
  * Shared code is automatically extracted into chunk files.
  * When there's no shared code, output is identical to per-component compilation.
  */
-export async function compileAllComponents(components, globalStylesPath) {
+export async function compileAllComponents(components, globalStylesPath, options) {
     if (components.length === 0) {
         return {
             success: true,
@@ -215,19 +779,33 @@ export async function compileAllComponents(components, globalStylesPath) {
         entryPoints[comp.id] = path.resolve(process.cwd(), comp.entryPath);
     }
     try {
-        // Server build with code splitting
-        await esbuild.build({
+        // Server build with code splitting (metafile enabled for dependency tracking)
+        const serverBuildResult = await esbuild.build({
             ...commonBuildOptions(),
             entryPoints,
             format: "esm",
-            platform: "node",
-            target: "node18",
+            // Vendoring flips the SSR build to browser resolution. Two reasons, both load-bearing:
+            //
+            // 1. `platform: "node"` picks the node flavour of a vendored dependency, which reaches for
+            //    node builtins (`uuid` → `crypto`) that no storefront can hand a published artifact.
+            //    The browser flavour uses `globalThis.crypto`, which SSR on Node 18+ has anyway.
+            // 2. esbuild escapes `</script` in string literals on browser and not on node. That single
+            //    byte changes a chunk's content hash, so the two builds emitted different chunk names
+            //    for identical code and every importer inherited the split — 154 of 251 chunks had no
+            //    twin. Same platform, same hashes, one chunk graph.
+            //
+            // The build is still consumed by `preact-render-to-string` in Node; only module resolution
+            // changes, and SERVER_EXTERNALS keeps the SSR renderer external either way.
+            platform: options?.vendorStorefront ? "browser" : "node",
+            target: SHARED_BUILD_TARGET,
             external: SERVER_EXTERNALS,
-            plugins: [ikasComponentUtilsPlugin()],
+            ...(options?.vendorStorefront ? { define: { "import.meta.env": VENDORED_IMPORT_META_ENV } } : {}),
+            plugins: resolutionPlugins(!!options?.vendorStorefront),
             splitting: true,
             outdir: serverDir,
             entryNames: "[name]",
             chunkNames: "chunk-[hash]",
+            metafile: true,
         });
         // Client build with code splitting (metafile enabled for dependency tracking)
         const clientBuildResult = await esbuild.build({
@@ -235,9 +813,10 @@ export async function compileAllComponents(components, globalStylesPath) {
             entryPoints,
             format: "esm",
             platform: "browser",
-            target: "es2020",
+            target: SHARED_BUILD_TARGET,
             external: CLIENT_EXTERNALS,
-            plugins: [ikasComponentUtilsPlugin()],
+            ...(options?.vendorStorefront ? { define: { "import.meta.env": VENDORED_IMPORT_META_ENV } } : {}),
+            plugins: resolutionPlugins(!!options?.vendorStorefront),
             splitting: true,
             outdir: clientDir,
             entryNames: "[name]",
@@ -278,17 +857,29 @@ export async function compileAllComponents(components, globalStylesPath) {
                 chunks.set(key, { serverJs, clientJs });
             }
         }
-        // Build dependency maps from metafile
-        const metafile = clientBuildResult.metafile;
+        // Build dependency maps from BOTH the server and client metafiles.
+        //
+        // Only the client metafile used to be consulted here. But SERVER_EXTERNALS
+        // differs from CLIENT_EXTERNALS (e.g. preact-render-to-string is external on
+        // the server only), so esbuild splits the two builds differently and emits
+        // server-only shared chunks whose names have no client twin. Those chunks are
+        // written to disk and captured in `chunks` above, yet — with a client-only
+        // graph — they never entered any component's chunk closure, so publish pruned
+        // them as orphaned. The result: `compiledServerJs` went missing on the shared
+        // module and the server bundle imported a `./chunk-XXXX.js` that was never
+        // emitted ("Could not resolve ./chunk-XXXX.js"). Merging both graphs keeps
+        // server and client chunk closures symmetric.
+        const clientMetafile = clientBuildResult.metafile;
+        const serverMetafile = serverBuildResult.metafile;
         const entryDirSet = new Map(); // entryId → absolute dir of entry file
         for (const comp of components) {
             entryDirSet.set(comp.id, path.dirname(path.resolve(process.cwd(), comp.entryPath)));
         }
-        // Map each output to its input source files
+        // CSS is a browser-only concern, so entry/chunk input source maps are derived
+        // from the CLIENT metafile only (they feed the CSS collection passes below).
         const entryInputs = new Map(); // entryId → list of input paths
         const chunkInputs = new Map(); // chunkId → list of input paths
-        const chunkConsumers = new Map(); // chunkId → list of entry IDs that import it
-        for (const [outputPath, outputMeta] of Object.entries(metafile.outputs)) {
+        for (const [outputPath, outputMeta] of Object.entries(clientMetafile.outputs)) {
             const baseName = path.basename(outputPath, ".js");
             const inputPaths = Object.keys(outputMeta.inputs || {});
             if (entryIds.has(baseName)) {
@@ -298,40 +889,49 @@ export async function compileAllComponents(components, globalStylesPath) {
                 chunkInputs.set(baseName, inputPaths);
             }
         }
-        // Determine chunk→consumers: which entries import each chunk
-        for (const [outputPath, outputMeta] of Object.entries(metafile.outputs)) {
-            const baseName = path.basename(outputPath, ".js");
-            if (!entryIds.has(baseName))
-                continue;
-            const imports = outputMeta.imports || [];
-            for (const imp of imports) {
-                const impBaseName = path.basename(imp.path, ".js");
-                if (chunkInputs.has(impBaseName)) {
-                    if (!chunkConsumers.has(impBaseName)) {
-                        chunkConsumers.set(impBaseName, []);
-                    }
-                    chunkConsumers.get(impBaseName).push(baseName);
-                }
-            }
-        }
-        // Build chunk→chunk dependency graph and topologically sort chunks
-        // so that chunks are evaluated in dependency-first order
+        // Recognize any emitted chunk — server OR client — by its output basename.
+        // `chunks` was populated above from both the server and client output dirs.
+        const allChunkIds = new Set(chunks.keys());
+        const chunkConsumers = new Map(); // chunkId → list of entry IDs that import it
         const chunkDeps = new Map(); // chunkId → list of chunk IDs it depends on
-        for (const chunkId of chunkInputs.keys()) {
+        for (const chunkId of allChunkIds) {
             chunkDeps.set(chunkId, []);
         }
-        for (const [outputPath, outputMeta] of Object.entries(metafile.outputs)) {
-            const baseName = path.basename(outputPath, ".js");
-            if (!chunkInputs.has(baseName))
-                continue;
-            const imports = outputMeta.imports || [];
-            for (const imp of imports) {
-                const impBaseName = path.basename(imp.path, ".js");
-                if (chunkInputs.has(impBaseName) && impBaseName !== baseName) {
-                    chunkDeps.get(baseName).push(impBaseName);
+        // Fold one metafile's output graph into the shared consumer/dependency maps.
+        // Called for both builds so server-only chunks are tracked alongside client ones.
+        const ingestMetafile = (mf) => {
+            for (const [outputPath, outputMeta] of Object.entries(mf.outputs)) {
+                const baseName = path.basename(outputPath, ".js");
+                const imports = outputMeta.imports || [];
+                if (entryIds.has(baseName)) {
+                    // entry → chunk consumer edges
+                    for (const imp of imports) {
+                        const impBaseName = path.basename(imp.path, ".js");
+                        if (!allChunkIds.has(impBaseName))
+                            continue;
+                        if (!chunkConsumers.has(impBaseName)) {
+                            chunkConsumers.set(impBaseName, []);
+                        }
+                        const consumers = chunkConsumers.get(impBaseName);
+                        if (!consumers.includes(baseName))
+                            consumers.push(baseName);
+                    }
+                }
+                else if (allChunkIds.has(baseName)) {
+                    // chunk → chunk dependency edges
+                    for (const imp of imports) {
+                        const impBaseName = path.basename(imp.path, ".js");
+                        if (allChunkIds.has(impBaseName) && impBaseName !== baseName) {
+                            const deps = chunkDeps.get(baseName);
+                            if (!deps.includes(impBaseName))
+                                deps.push(impBaseName);
+                        }
+                    }
                 }
             }
-        }
+        };
+        ingestMetafile(clientMetafile);
+        ingestMetafile(serverMetafile);
         // Kahn's algorithm for topological sort
         const inDegree = new Map();
         for (const chunkId of chunkDeps.keys()) {
@@ -390,7 +990,29 @@ export async function compileAllComponents(components, globalStylesPath) {
         // Resolve CSS: entry CSS + entry-only dependency CSS + chunk CSS
         const css = new Map();
         const chunkCss = new Map();
+        // CSS files each consumed chunk will emit (same collection the chunk-CSS pass below uses).
+        // The entry pass needs these up front: a parent styles.css that `@import`s a SHARED
+        // sub-component's styles.css (the documented convention) would otherwise inline a copy of
+        // CSS the chunk already carries for every consumer — duplicating each rule per consumer.
+        const chunkExcludeDirs = Array.from(entryDirSet.values());
+        const chunkCssFileSets = new Map();
+        for (const [chunkId, inputPaths] of chunkInputs) {
+            if ((chunkConsumers.get(chunkId) || []).length === 0)
+                continue;
+            const files = collectSourceCssFiles(inputPaths, undefined, chunkExcludeDirs);
+            chunkCssFileSets.set(chunkId, new Set(files.map(f => path.resolve(f))));
+        }
         for (const comp of components) {
+            // CSS files already covered for this entry by the chunks it consumes. Only direct
+            // consumers count: a chunk this entry does not consume is scoped to other components,
+            // so its files must still be inlined here when @imported.
+            const chunkCoveredCssPaths = new Set();
+            for (const [chunkId, consumers] of chunkConsumers) {
+                if (!consumers.includes(comp.id))
+                    continue;
+                for (const f of chunkCssFileSets.get(chunkId) ?? [])
+                    chunkCoveredCssPaths.add(f);
+            }
             // 1. Read entry's own styles.css + resolve @imports.
             // Track every file inlined here so step 2's source-tree collection doesn't append them again
             // (which previously emitted each @imported file twice in compiledCss).
@@ -399,7 +1021,7 @@ export async function compileAllComponents(components, globalStylesPath) {
             let cssContent = "";
             if (fs.existsSync(cssPath)) {
                 const rawCss = fs.readFileSync(cssPath, "utf-8");
-                cssContent = resolveCssImports(rawCss, cssPath, alreadyInlinedPaths);
+                cssContent = resolveCssImports(rawCss, cssPath, alreadyInlinedPaths, chunkCoveredCssPaths);
             }
             // 2. Collect CSS from entry-only dependencies (source files in entry inputs, not in any chunk)
             const allChunkInputPaths = new Set();
@@ -412,20 +1034,23 @@ export async function compileAllComponents(components, globalStylesPath) {
             for (const depCssPath of depCss) {
                 if (alreadyInlinedPaths.has(path.resolve(depCssPath)))
                     continue;
+                // A sibling CSS can surface here even when its directory is chunk-covered (an
+                // entry-only source file living in a shared sub-component's folder) — the chunk
+                // already carries it, so inlining it again would duplicate every rule.
+                if (chunkCoveredCssPaths.has(path.resolve(depCssPath)))
+                    continue;
                 const rawDepCss = fs.readFileSync(depCssPath, "utf-8");
-                cssContent += "\n" + resolveCssImports(rawDepCss, depCssPath, alreadyInlinedPaths);
+                cssContent += "\n" + resolveCssImports(rawDepCss, depCssPath, alreadyInlinedPaths, chunkCoveredCssPaths);
             }
             // 3. Scope combined CSS with entry ID
             css.set(comp.id, scopeCSS(cssContent, comp.id));
         }
-        // Process chunk CSS
-        for (const [chunkId, inputPaths] of chunkInputs) {
+        // Process chunk CSS (file sets were collected above, before the entry pass)
+        for (const chunkId of chunkInputs.keys()) {
             const consumers = chunkConsumers.get(chunkId) || [];
             if (consumers.length === 0)
                 continue;
-            // Collect CSS from all entry dirs to exclude (we only exclude entry file dirs)
-            const excludeDirs = Array.from(entryDirSet.values());
-            const chunkCssFiles = collectSourceCssFiles(inputPaths, undefined, excludeDirs);
+            const chunkCssFiles = Array.from(chunkCssFileSets.get(chunkId) ?? []);
             if (chunkCssFiles.length === 0)
                 continue;
             let combinedCss = "";
@@ -485,12 +1110,20 @@ export async function compileAllComponents(components, globalStylesPath) {
             css: new Map(),
             chunkCss: new Map(),
             entryChunkIds: new Map(),
-            error: error.message || String(error)
+            error: withCssImportHint(error.message || String(error))
         };
     }
     finally {
-        // Clean up temp directory
-        fs.rmSync(tmpBase, { recursive: true, force: true });
+        // Clean up temp directory. Best-effort: on Windows an antivirus/indexer can briefly hold
+        // handles on the freshly written output files, making rmSync throw EBUSY/EPERM — and a
+        // throw here (inside finally) would replace a successful compilation result with an error.
+        // A leaked tmp dir is harmless; retry a few times, then give up silently.
+        try {
+            fs.rmSync(tmpBase, { recursive: true, force: true, maxRetries: 3 });
+        }
+        catch {
+            // ignore — never fail the build over tmp cleanup
+        }
     }
 }
 /**