@jxsuite/compiler 1.4.0 → 2.0.0

package/src/shared.ts

@@ -18,21 +18,26 @@ import {
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import { runStatements } from "@jxsuite/runtime/statements";
 import {
+  bodyReturnsValue,
   childrenContainArray,
   hasStructuredBody,
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
-  bodyReturnsValue,
   isNamedFormulaDef,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
   isServerFnDef,
+  isTagExpression,
   isTemplateString,
   paramNames,
+  tagNameCandidates,
 } from "@jxsuite/schema/guards";
+import { styleScopePrefix } from "./shadow.ts";
+import type { ShadowMode } from "./shadow.ts";
 import type { ExpressionNode } from "@jxsuite/runtime/expression";
+import { readPath } from "@jxsuite/runtime/pointer";
 import type {
   JsonValue,
   JxElement,
@@ -54,7 +59,13 @@ export {
   schemeSelectors,
   toCSSText,
 } from "@jxsuite/runtime";
-export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export {
+  compileExpression,
+  compileOperandSource,
+  evaluateExpression,
+  evaluateOperand,
+  isMutating,
+} from "@jxsuite/runtime/expression";
 export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
 
 /**
@@ -77,8 +88,133 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
   }
   return `(..._a) => { const _args = { ${entries.join(", ")} }; return ${compiledBody}; }`;
 }
+
+/**
+ * Emit the import-clause binding for one Function-def `$src` entry.
+ *
+ * `$export` names the export inside the module and defaults to the state key (spec.md §5.3 4d).
+ * When the two differ the clause has to alias, because the local name the rest of the generated
+ * module calls is the state key — importing the bare key instead requests an export the module does
+ * not have, and the browser rejects the whole module at link time.
+ *
+ * Aliasing rather than renaming call sites is what makes the awkward cases work: two keys may alias
+ * the same export, a key may collide with another entry's export name, and `$export: "default"` is
+ * only reachable as `default as key`.
+ *
+ * @param {string} key - State key, and the local binding name
+ * @param {unknown} def - The Function definition
+ * @returns {string}
+ */
+export function srcImportBinding(key: string, def: unknown) {
+  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
+  const exportName = typeof declared === "string" && declared !== "" ? declared : key;
+  return exportName === key ? key : `${exportName} as ${key}`;
+}
+
+/**
+ * Emit the auto-fetch `effect()` for a `$prototype: "Request"` state entry.
+ *
+ * Shared by the client and element targets so both honour `manual`, template URLs and
+ * `method`/`headers`/`body` the same way. They diverged once: the element target emitted no fetch
+ * at all, leaving every Request entry permanently `null` with nothing thrown.
+ *
+ * A template `url` is read inside the effect, so the fetch re-runs whenever the interpolated state
+ * changes; an URL that still interpolates to `undefined` is skipped rather than fetched.
+ *
+ * @param {string} key - State key receiving the response
+ * @param {JxPrototypeDef} def - The Request definition
+ * @param {{ statePrefix?: string; indent?: string; collect?: string }} [opts] - `statePrefix` is
+ *   the expression the emitted code assigns through (`state` for the client module scope,
+ *   `this.state` inside a custom element); `indent` prefixes every emitted line; `collect`, when
+ *   given, is an array expression the effect runner is pushed onto so the caller can `stop()` it on
+ *   teardown.
+ * @returns {string}
+ */
+export function emitRequestFetch(
+  key: string,
+  def: JxPrototypeDef,
+  opts: { statePrefix?: string; indent?: string; collect?: string } = {},
+) {
+  const { statePrefix = "state", indent = "", collect } = opts;
+  const { url } = def;
+  const isTemplateUrl = isTemplateString(url);
+  const method = def.method ?? "GET";
+
+  if (def.manual) {
+    return `${indent}// ${key}: manual Request — fetch triggered by user action`;
+  }
+
+  const lines: string[] = [
+    `// ${key}: auto-fetch from ${isTemplateUrl ? "(dynamic URL)" : url}`,
+    collect ? `${collect}.push(effect(() => {` : "effect(() => {",
+  ];
+
+  if (isTemplateUrl) {
+    lines.push(
+      `  const url = \`${withStatePrefix(url as string, statePrefix)}\`;`,
+      '  if (!url || url === "undefined" || url.includes("undefined")) return;',
+    );
+  } else {
+    lines.push(`  const url = ${JSON.stringify(url)};`);
+  }
+
+  const fetchOpts: string[] = [];
+  if (method !== "GET") {
+    fetchOpts.push(`method: ${JSON.stringify(method)}`);
+  }
+  if (def.headers) {
+    fetchOpts.push(`headers: ${JSON.stringify(def.headers)}`);
+  }
+  if (def.body) {
+    const bodyStr =
+      typeof def.body === "object"
+        ? JSON.stringify(JSON.stringify(def.body))
+        : JSON.stringify(def.body);
+    fetchOpts.push(`body: ${bodyStr}`);
+  }
+
+  const optsStr = fetchOpts.length > 0 ? `, { ${fetchOpts.join(", ")} }` : "";
+  lines.push(
+    `  fetch(url${optsStr})`,
+    "    .then(r => r.ok ? r.json() : Promise.reject(r.statusText))",
+    `    .then(d => { ${statePrefix}.${key} = d; })`,
+    `    .catch(e => { ${statePrefix}.${key} = { error: String(e) }; });`,
+    collect ? "}));" : "});",
+  );
+
+  return lines.map((line) => `${indent}${line}`).join("\n");
+}
+
+/**
+ * Rebase the bare `state.` reads in a template string onto `statePrefix`.
+ *
+ * Only the `${…}` interpolation holes are rewritten. A blanket replace would corrupt the literal
+ * text around them — `/api/state.json?q=${state.q}` would request `/api/this.state.json` — and the
+ * `\b` guard keeps an identifier that merely ends in `state` (`substate.z`) intact. Reads already
+ * carrying the prefix are left alone.
+ *
+ * @param {string} str
+ * @param {string} statePrefix
+ * @returns {string}
+ */
+function withStatePrefix(str: string, statePrefix: string) {
+  if (statePrefix === "state") {
+    return str;
+  }
+  return str.replaceAll(
+    /\$\{([^}]*)\}/g,
+    (_match: string, expr: string) =>
+      `\${${expr.replaceAll(/(?<!this\.)\bstate\./g, `${statePrefix}.`)}}`,
+  );
+}
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
+/**
+ * Non-enumerable marker on a build-time scope listing the state keys that hold no build-time value.
+ * Non-enumerable so it stays out of `Object.entries(scope)` and out of template evaluation.
+ */
+const RUNTIME_ONLY_KEYS = Symbol("jx.runtimeOnlyStateKeys");
+
 // CDN defaults
 export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.40";
 export const DEFAULT_LIT_HTML_SRC = "https://esm.sh/lit-html@3.3.0";
@@ -275,6 +411,8 @@ export interface CompileContext {
   scope: Record<string, unknown>;
   scopeDefs: Record<string, unknown>;
   media: Record<string, string>;
+  /** True inside a `<pre>`-like subtree, where emitters must not indent nested children. */
+  preformatted?: boolean;
 }
 
 export function createCompileContext(
@@ -289,6 +427,62 @@ export function createCompileContext(
   return { media, scope, scopeDefs };
 }
 
+/**
+ * `state.x = …`, `state.x += …`, `state.x++` — every form a string handler body can use to write a
+ * state entry. `===`/`!==`/`<=`/`>=` are excluded by the `(?!=)` guard and by the operator set.
+ */
+const STATE_ASSIGNMENT_RE =
+  /\bstate\.([A-Za-z_$][\w$]*)\s*(?:\+\+|--|(?:\*\*|\|\||&&|\?\?|<<|>>>|>>|[-+*/%&|^])?=(?!=))/g;
+
+/** `state.list.push(…)` and friends mutate in place without ever assigning to the entry. */
+const STATE_MUTATING_METHOD_RE =
+  /\bstate\.([A-Za-z_$][\w$]*)\s*\.\s*(?:push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin)\s*\(/g;
+
+/**
+ * Collect every state key a handler writes to, across all the forms a body can take: a string body,
+ * a structured body (spec §20), and an `$expression` node with a mutating operator.
+ *
+ * Used to keep prerender from baking a binding over an entry that changes after hydration. A plain
+ * `{ "type": "string" }` entry holds a perfectly ordinary build-time value, so nothing else
+ * distinguishes it from a constant — but if a handler assigns to it, interpolating it at build time
+ * replaces the template in the emitted output and the element is dead for the life of the page.
+ *
+ * @param {unknown} node
+ * @param {Set<string>} into
+ */
+function collectAssignedStateKeys(node: unknown, into: Set<string>) {
+  if (typeof node === "string") {
+    for (const m of node.matchAll(STATE_ASSIGNMENT_RE)) {
+      into.add(m[1] as string);
+    }
+    for (const m of node.matchAll(STATE_MUTATING_METHOD_RE)) {
+      into.add(m[1] as string);
+    }
+    return;
+  }
+  if (!node || typeof node !== "object") {
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const entry of node) {
+      collectAssignedStateKeys(entry, into);
+    }
+    return;
+  }
+  const rec = node as Record<string, unknown>;
+  // A mutating expression names its destination as `target: { $ref: "#/state/x" }`.
+  const op = rec.operator;
+  if (typeof op === "string" && isMutating(op)) {
+    const target = rec.target as { $ref?: string } | undefined;
+    if (target && typeof target.$ref === "string" && target.$ref.startsWith("#/state/")) {
+      into.add(target.$ref.slice("#/state/".length).split("/")[0] as string);
+    }
+  }
+  for (const value of Object.values(rec)) {
+    collectAssignedStateKeys(value, into);
+  }
+}
+
 /**
  * @param {Record<string, JxStateDefinition>} [defs]
  * @param {Record<string, unknown> | null} [parentScope]
@@ -299,6 +493,38 @@ export function buildInitialScope(
   parentScope: Record<string, unknown> | null = null,
 ) {
   const scope = Object.create(parentScope ?? null) as Record<string, unknown>;
+  // Keys whose real value only exists after hydration, so prerender must not interpolate them —
+  // See `readsRuntimeOnlyState`. Seeded from the parent so nested scopes inherit the marks.
+  const inherited = (parentScope as Record<PropertyKey, unknown> | null)?.[RUNTIME_ONLY_KEYS];
+  const runtimeOnly = new Set<string>(inherited instanceof Set ? (inherited as Set<string>) : []);
+  // Attached up front, and mutated in place by the passes below, so the template pass at the end can
+  // Consult the marks the earlier passes added.
+  Object.defineProperty(scope, RUNTIME_ONLY_KEYS, {
+    configurable: true,
+    enumerable: false,
+    value: runtimeOnly,
+    writable: true,
+  });
+
+  // Pass 0: every entry some handler in this document writes to is mutable, so prerender must not
+  // Bake a binding over it. Narrow on purpose — an entry nothing ever writes stays bakeable, so
+  // Prerendered content is preserved for SEO. A `$src` handler's assignments live in a JS file this
+  // Builder cannot open, so a write that only happens there is still missed (issue #125).
+  const assigned = new Set<string>();
+  for (const def of Object.values(defs)) {
+    if (def && typeof def === "object" && (isFunctionDef(def) || isExpressionDef(def))) {
+      collectAssignedStateKeys(
+        (def as { body?: unknown; $expression?: unknown }).body ??
+          (def as { $expression?: unknown }).$expression,
+        assigned,
+      );
+    }
+  }
+  for (const key of assigned) {
+    if (key in defs) {
+      runtimeOnly.add(key);
+    }
+  }
 
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def !== "object" || def === null || Array.isArray(def)) {
@@ -315,9 +541,17 @@ export function buildInitialScope(
     }
   }
 
+  // Template-string entries are deferred to a third pass: whether one is resolvable depends on the
+  // Runtime-only marks the loop below adds, and key order must not decide the answer.
+  const templateDefs: [string, string][] = [];
+  // Computed (`bodyReturnsValue`) entries are deferred for the same reason. A computed is stored in
+  // The scope as its already-evaluated *result*, so a template reading it sees an ordinary string
+  // And prerender bakes it — destroying the binding rather than merely staling it (issue #124).
+  const computedBodies: [string, string][] = [];
+
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def === "string" && isTemplateString(def)) {
-      defineLazyScopeValue(scope, key, () => evaluateStaticTemplate(def, scope));
+      templateDefs.push([key, def]);
       continue;
     }
     if (!def || typeof def !== "object") {
@@ -359,18 +593,28 @@ export function buildInitialScope(
           void runStatements(body, s ?? scope, event ?? null);
         });
       } else if (typeof def.body === "string") {
-        const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
+        const declared = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
         const { body } = def;
-        const fn = new Function("state", ...names, body) as (
-          state: Record<string, unknown>,
-        ) => unknown;
+        // Declared names bind by name, not by position (spec.md §5.3 4d): a parameter literally
+        // Named `state` receives the scope, anything else receives the event. `state` is prepended
+        // When undeclared so a body may always reference it. Unconditionally prepending it instead —
+        // The older behaviour here — produced a duplicate parameter for the `["state", "event"]`
+        // Form that examples/components/task-manager.json uses, leaving `state` undefined.
+        const params = declared.includes("state") ? declared : ["state", ...declared];
+        const fn = new Function(...params, body) as (...args: unknown[]) => unknown;
+        const invoke = (state: Record<string, unknown>, event?: unknown) =>
+          fn(...params.map((name) => (name === "state" ? state : event)));
         if (bodyReturnsValue(body)) {
-          defineLazyScopeValue(scope, key, () => fn(scope));
+          defineLazyScopeValue(scope, key, () => invoke(scope));
+          computedBodies.push([key, body]);
         } else {
-          setOwnScopeValue(scope, key, fn);
+          setOwnScopeValue(scope, key, invoke);
         }
       } else {
+        // Bodyless `$src` Function — the real implementation is only loaded in the browser, so this
+        // Is a placeholder standing in for its callable shape, never its value.
         setOwnScopeValue(scope, key, () => {});
+        runtimeOnly.add(key);
       }
       continue;
     }
@@ -379,9 +623,34 @@ export function buildInitialScope(
       (def.$prototype === "LocalStorage" || def.$prototype === "SessionStorage")
     ) {
       setOwnScopeValue(scope, key, cloneValue(def.default ?? null));
+      continue;
+    }
+    if (isPrototypeDef(def) && def.$prototype === "Request") {
+      // A client-timing fetch has no build-time value at all — not even a placeholder.
+      runtimeOnly.add(key);
     }
   }
 
+  // A state entry that reads a runtime-only key cannot resolve until hydration either, so it is
+  // Runtime-only in turn. Without this, prerender would bake the failed evaluation (`null`) into
+  // Every template that reads *this* entry, one step removed from the original. Iterated to a
+  // Fixpoint because marking one entry can qualify another, in either direction, and declaration
+  // Order must not decide the answer.
+  let marked = true;
+  while (marked) {
+    marked = false;
+    for (const [key, source] of [...computedBodies, ...templateDefs]) {
+      if (!runtimeOnly.has(key) && readsRuntimeOnlyState(source, scope)) {
+        runtimeOnly.add(key);
+        marked = true;
+      }
+    }
+  }
+
+  for (const [key, template] of templateDefs) {
+    defineLazyScopeValue(scope, key, () => evaluateStaticTemplate(template, scope));
+  }
+
   return scope;
 }
 
@@ -455,14 +724,59 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
     return parts.length > 2 ? getPathValue(base, parts.slice(2).join("/")) : base;
   }
   if (refValue.startsWith("#/state/")) {
-    const sub = refValue.slice("#/state/".length);
-    const slash = sub.indexOf("/");
-    if (slash === -1) {
-      return scope[sub];
+    // One call, not a hand-split leading token: slicing at the first `/` skipped unescaping it, so
+    // `#/state/a~1b/c` looked for a member called `a~1b` rather than `a/b`.
+    return getPathValue(scope, refValue.slice("#/state/".length));
+  }
+  /*
+   * An unrecognized scheme is still a path, matching the runtime resolvers and the lowerer.
+   * Reading it as one key returned null for `a/b` while the emitted client module walked it.
+   */
+  return getPathValue(scope, refValue) ?? null;
+}
+
+/**
+ * Detect whether a template string interpolates a state value that only exists after hydration.
+ *
+ * Evaluating one of those at build time is worse than leaving it alone. The build-time scope holds
+ * a `() => {}` placeholder for a bodyless `$src` Function and nothing at all for a `Request`, so
+ * the template resolves to text like `() => {}`, `undefined` or `""` — and that text _replaces_ the
+ * template in the emitted HTML, so the client-side binding is destroyed rather than merely wrong.
+ * Returning "unresolvable" instead leaves the template in place for the client to populate.
+ *
+ * A read that _calls_ the value is left alone: invoking a build-time callable is exactly how named
+ * formulas (spec.md §19.4c) are meant to be used during prerender.
+ *
+ * @param {string} str
+ * @param {Record<string, unknown>} scope
+ * @returns {boolean}
+ */
+function readsRuntimeOnlyState(str: string, scope: Record<string, unknown>) {
+  if (!scope) {
+    return false;
+  }
+  const runtimeOnly = (scope as Record<PropertyKey, unknown>)[RUNTIME_ONLY_KEYS];
+  for (const match of str.matchAll(/\bstate\.([A-Za-z_$][\w$]*)\s*(\()?/g)) {
+    if (match[2]) {
+      continue;
+    }
+    const key = match[1] as string;
+    if (runtimeOnly instanceof Set && runtimeOnly.has(key)) {
+      return true;
+    }
+    // Reading the key can run a computed's getter, which is free to throw on partial build-time
+    // Data. A throw says nothing about whether the entry is runtime-only, so it is not a mark.
+    let value: unknown;
+    try {
+      value = scope[key];
+    } catch {
+      continue;
+    }
+    if (typeof value === "function") {
+      return true;
     }
-    return getPathValue(scope[sub.slice(0, slash)], sub.slice(slash + 1));
   }
-  return scope[refValue] ?? null;
+  return false;
 }
 
 /**
@@ -471,20 +785,24 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
  * @returns {unknown}
  */
 export function evaluateStaticTemplate(str: string, scope: Record<string, unknown>) {
+  if (readsRuntimeOnlyState(str, scope)) {
+    return null;
+  }
+  /*
+   * `$site` and `$page` are bound as parameters, not just left on `state`.
+   *
+   * `injectContext` puts them on the document's state, so `${state.$site.name}` always worked — but
+   * every example in site-architecture.md §8.2 writes the bare `${$site.name}`, and that threw a
+   * ReferenceError the catch below turned into a silent null. A `$head` title referencing the site
+   * name reached the page as the literal template text.
+   */
+  const args = ["state", "$map", "$site", "$page"] as const;
+  const values = [scope, scope?.$map, scope?.$site, scope?.$page];
   try {
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
-    if (singleExprMatch) {
-      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`) as (
-        state: Record<string, unknown>,
-        $map: unknown,
-      ) => unknown;
-      return fn(scope, scope?.$map);
-    }
-    const fn = new Function("state", "$map", `return \`${str}\``) as (
-      state: Record<string, unknown>,
-      $map: unknown,
-    ) => unknown;
-    return fn(scope, scope?.$map);
+    const body = singleExprMatch ? `return (${singleExprMatch[1]})` : `return \`${str}\``;
+    const fn = new Function(...args, body) as (...a: unknown[]) => unknown;
+    return fn(...values);
   } catch {
     return null;
   }
@@ -496,14 +814,7 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
  * @returns {unknown}
  */
 export function getPathValue(base: unknown, path: string) {
-  if (!path) {
-    return base;
-  }
-  let acc: unknown = base;
-  for (const key of path.split("/")) {
-    acc = acc == null ? undefined : (acc as Record<string, unknown>)[key];
-  }
-  return acc;
+  return readPath(base, path);
 }
 
 /**
@@ -595,15 +906,6 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
     }
   }
 
-  if (def.tagName === "img") {
-    if (!def.attributes?.loading) {
-      out += ` loading="lazy"`;
-    }
-    if (!def.attributes?.decoding) {
-      out += ` decoding="async"`;
-    }
-  }
-
   if (def.$static) {
     out += ` data-jx-static`;
   } else if (def.$prerendered) {
@@ -613,6 +915,26 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
   return out;
 }
 
+/**
+ * Tags rendered with `white-space: pre` by every UA, where inter-element whitespace is content
+ * rather than formatting. Emitters indent nested children for readability; inside these tags — and
+ * anywhere below them, since `white-space` inherits — that indentation would render as literal
+ * blank lines and leading spaces, so children must be concatenated with no separator.
+ */
+export const PREFORMATTED_TAGS = new Set(["pre", "textarea", "listing", "plaintext", "xmp"]);
+
+/**
+ * The separator to place between an element's compiled children: none inside a preformatted
+ * subtree, a newline plus `indent` elsewhere.
+ *
+ * @param {boolean | undefined} preformatted
+ * @param {string} [indent]
+ * @returns {string}
+ */
+export function childSeparator(preformatted: boolean | undefined, indent = "  "): string {
+  return preformatted ? "" : `\n${indent}`;
+}
+
 /**
  * Build the inner HTML (textContent or children) for a node.
  *
@@ -622,6 +944,7 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
  *   scope: Record<string, unknown>;
  *   scopeDefs: Record<string, unknown>;
  *   media: Record<string, string>;
+ *   preformatted?: boolean;
  * }} context
  * @param {(def: unknown, raw: unknown, context: unknown) => string} childCompiler
  * @returns {string}
@@ -633,6 +956,7 @@ export function buildInner(
     scope: Record<string, unknown> | null;
     scopeDefs: Record<string, unknown>;
     media: Record<string, string>;
+    preformatted?: boolean;
   },
   childCompiler: (def: unknown, raw: unknown, context: unknown) => string,
 ) {
@@ -652,7 +976,7 @@ export function buildInner(
         const childRaw = (rawChildren as (JxElement | string)[] | undefined)?.[i] ?? c;
         return childCompiler(c, childRaw, context);
       })
-      .join("\n  ");
+      .join(childSeparator(context.preformatted));
   }
   return "";
 }
@@ -945,11 +1269,16 @@ export function collectStyles(
     counter.n += 1;
   }
 
+  /* A chosen tag needs a selector that matches every candidate, not the first one.
+     `#id` and `.class` are unaffected — they identify the element regardless of what it turns out
+     to be — but a bare tag selector has to become the union, or styling an `<a>|<div>` wrapper
+     would style exactly one of the two branches and silently miss the other. */
+  const tagSelector = tagNameCandidates(def.tagName).join(", ") || "*";
   const selector = def.id
     ? `#${def.id}`
     : def.className
       ? `.${def.className.split(" ")[0]}`
-      : (def.tagName ?? "*");
+      : tagSelector;
 
   if (def.style) {
     const baseDecls = [];
@@ -1150,6 +1479,40 @@ export const SELF_CLOSING = new Set<string>([
   "source",
 ]);
 
+/**
+ * A tag for the PRERENDER, resolved against the same scope the attributes are.
+ *
+ * The static renderer produces bytes, so it must commit to one element. Every candidate is a
+ * literal `TagName`, so committing is safe — and it is resolved here rather than left as text
+ * precisely because the old `${…}` form was left as text and then re-resolved against the page
+ * scope, where a component's own state is undefined.
+ *
+ * @param {unknown} tagName
+ * @param {Record<string, unknown>} scope
+ * @returns {string}
+ */
+export function resolveStaticTagName(
+  tagName: unknown,
+  scope: Record<string, unknown> | null,
+): string {
+  if (typeof tagName === "string") {
+    return tagName;
+  }
+  const candidates = tagNameCandidates(tagName);
+  if (candidates.length === 0) {
+    return "div";
+  }
+  if (!isTagExpression(tagName)) {
+    return candidates[0]!;
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return resolveStaticValue(expression.target, scope) ? expression.value : expression.initial;
+  }
+  const key = resolveStaticValue(expression.target, scope);
+  return expression.cases[String(key)] ?? expression.default;
+}
+
 /**
  * Recursively render a Jx node tree to static HTML for pre-rendering.
  *
@@ -1207,7 +1570,11 @@ export function renderStaticNode(
     return `<${switchTag}${attrs}>${inner}</${switchTag}>`;
   }
 
-  const tag = node.tagName ?? "div";
+  /* Resolved against the SAME scope the attributes are resolved against, so the prerendered markup
+     and the client's first render agree about what element this is. The old `${…}` form could not
+     do this — it re-resolved the emitted string against the page scope, where a component's own
+     state does not exist, so SSR silently emitted the fallback branch's tag. */
+  const tag = resolveStaticTagName(node.tagName, scope);
 
   // Replace <slot> with provided slot content
   if (tag === "slot" && slotContent != null) {
@@ -1356,13 +1723,55 @@ function _isStaticNode(node: JxElement | string | (JxElement | string)[]): boole
  * @param {Record<string, string>} [mediaQueries] - Project media query definitions
  * @returns {string} CSS text, or empty string if no styles
  */
+/** `::slotted()` and `::part()` select through a shadow boundary, not the host that owns it. */
+const SHADOW_STANDALONE = /^(?:::slotted\(|::part\()/;
+
+/**
+ * Turn one nested style key into a selector, given the component's scope prefix.
+ *
+ * Three shapes, and the interesting one is `:host`. A style object should mean the same thing in
+ * both modes, so `:host` and `:host(.foo)` are **translated** rather than passed through: inside a
+ * shadow root they stand alone, and in the light DOM they become the tag name and `<tag>.foo` —
+ * which is what "the host, matching this" means when there is no shadow root. Moving a component
+ * between modes therefore does not silently break its styles.
+ *
+ * @param {string} prop - The style-object key, e.g. `":hover"`, `"& .inner"`, `":host(.wide)"`
+ * @param {string} scope - `":host"` in shadow mode, the tag name otherwise
+ * @returns {string}
+ */
+function resolveSelector(prop: string, scope: string): string {
+  if (prop.startsWith("&")) {
+    return prop.replace("&", scope);
+  }
+  if (prop.startsWith(":host")) {
+    const inner = /^:host\((.*)\)$/.exec(prop)?.[1];
+    if (scope === ":host") {
+      return prop;
+    }
+    return inner === undefined ? scope : `${scope}${inner}`;
+  }
+  // `:host::slotted(x)` matches nothing — the pseudo-element attaches to a slot, not the host.
+  if (scope === ":host" && SHADOW_STANDALONE.test(prop)) {
+    return prop;
+  }
+  return `${scope}${prop}`;
+}
+
 export function buildComponentCSS(
   tagName: string,
   styleDef?: JxStyle | null | undefined,
   doc: JxElement | null = null,
   mediaQueries: Record<string, string> = {},
+  shadow: ShadowMode | null = null,
 ) {
   const rules: string[] = [];
+  /*
+   * The scope prefix. In light DOM it is the tag name, which is what keeps `sty-card .inner` from
+   * reaching another component's `.inner`. Inside a shadow root the selector cannot see the host's
+   * tag name at all, and `:host` is the standard's way to address it — so the same style object
+   * produces different, correct CSS in each mode without the author restating it.
+   */
+  const scope = styleScopePrefix(tagName, shadow);
 
   if (styleDef && typeof styleDef === "object") {
     const decls: string[] = [];
@@ -1385,20 +1794,21 @@ export function buildComponentCSS(
       decls.push(`  ${camelToKebab(prop)}: ${value};`);
     }
     if (decls.length > 0) {
-      rules.push(`${tagName} {\n${decls.join("\n")}\n}`);
+      rules.push(`${scope} {\n${decls.join("\n")}\n}`);
     }
 
     for (const [prop, val] of Object.entries(styleDef)) {
       if (prop.startsWith("@")) {
-        pushConditionalRule(rules, prop, mediaQueries, tagName, val as Record<string, unknown>);
+        pushConditionalRule(rules, prop, mediaQueries, scope, val as Record<string, unknown>);
       } else if (
         prop.startsWith(":") ||
         prop.startsWith(".") ||
         prop.startsWith("&") ||
         prop.startsWith("[")
       ) {
-        const resolved = prop.startsWith("&") ? prop.replace("&", tagName) : `${tagName}${prop}`;
-        rules.push(`${resolved} { ${toCSSText(val as Record<string, unknown>)} }`);
+        rules.push(
+          `${resolveSelector(prop, scope)} { ${toCSSText(val as Record<string, unknown>)} }`,
+        );
       }
     }
   }