@jxsuite/compiler 3.0.0 → 4.0.0

package/src/site/site-build.ts

@@ -21,7 +21,15 @@ import {
 import { createHash } from "node:crypto";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { isMappedArray, isRef } from "@jxsuite/schema/guards";
-import { isNpmSpecifier, npmAssetPath, sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+import {
+  isNpmSpecifier,
+  npmAssetPath,
+  sidecarAssetPath,
+  siteAbsoluteUrl,
+  siteBasePath,
+  withBase,
+} from "@jxsuite/schema/asset-paths";
+import { rewriteHtmlBase } from "./base-path.ts";
 import {
   CLIENT_EXTERNALS,
   bundleEntry,
@@ -40,6 +48,7 @@ import {
 import {
   buildHeaderRules,
   contentTypeRules,
+  rebaseHeaderRules,
   writeHeaders,
   writeNoJekyll,
 } from "./headers-emitter.ts";
@@ -59,6 +68,7 @@ import type { SiteConnectorSpec, SiteMountSpec } from "../targets/compile-server
 import {
   buildComponentCSS,
   buildInitialScope,
+  buildInstanceScope,
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
@@ -67,12 +77,14 @@ import {
   isComponentFullyStatic,
   isSingleExpression,
   isTemplateString,
+  liftPropsAttributes,
   preRenderComponentHtml,
   pureSchemeOf,
   renderStaticNode,
+  resolveHostStyle,
   resolveRefValue,
-  resolveStaticValue,
 } from "../shared.ts";
+import type { ComponentPrerenderContext } from "../shared.ts";
 import { resolvePrototypes } from "./prototype-resolver.ts";
 import { transformImageNodes } from "./image-transform.ts";
 import { collectCspSources, emptyCspSources } from "./csp.ts";
@@ -519,6 +531,12 @@ export async function buildSite(
   // Sitemap is generated from the route table when a production `url` is configured
   // (absolute <loc> URLs require it) and not explicitly disabled via build.sitemap: false.
   const siteUrl = projectConfig.url;
+  /*
+   * The path the site is deployed under, read back off `url` (RFC 3986 §5 — see `base-path.ts`).
+   * `""` for a site at an origin root, which is every deployment Jx documents, so every use below
+   * is a no-op there rather than a branch.
+   */
+  const basePath = siteBasePath(siteUrl);
   const sitemapEnabled = Boolean(siteUrl) && projectConfig.build.sitemap !== false;
   const sitemapEntries: SitemapEntry[] = [];
 
@@ -714,7 +732,9 @@ export async function buildSite(
       // Determine output path
       const outPath = routeToOutputPath(route.urlPattern, outDir, trailingSlash);
       mkdirSync(dirname(outPath), { recursive: true });
-      writeFileSync(outPath, result.html, "utf8");
+      /* Last, after the scans above: they ask what this page REFERENCES, and the answer is a
+         build-output path, not a deployed URL. Re-rooting first would make every one of them miss. */
+      writeFileSync(outPath, rewriteHtmlBase(result.html, basePath), "utf8");
       fileCount += 1;
 
       // Record a sitemap entry for this concrete page (skip unexpanded dynamic routes and
@@ -735,7 +755,7 @@ export async function buildSite(
             typeof route.sourceMtime === "string" && route.sourceMtime !== ""
               ? route.sourceMtime
               : toRfc3339(statSync(route.sourcePath).mtime),
-          loc: new URL(route.urlPattern, siteUrl).href,
+          loc: siteAbsoluteUrl(route.urlPattern, siteUrl),
           ...(routeAlternates.length > 0 && { alternates: routeAlternates }),
         });
       }
@@ -835,7 +855,13 @@ export async function buildSite(
     const skipWorker = adapter === "cloudflare-pages" && deduped.size === 0 && mounts.length === 0;
     const workerSource = skipWorker
       ? null
-      : compileSiteServer([...deduped.values()], { adapter, connectors, i18n, mounts });
+      : compileSiteServer([...deduped.values()], {
+          adapter,
+          base: basePath,
+          connectors,
+          i18n,
+          mounts,
+        });
 
     if (workerSource) {
       // Bundle the worker self-contained for the adapter's runtime (compiler.md §12): mount
@@ -1014,6 +1040,7 @@ export async function buildSite(
     log("Generating redirects...");
     const compiledUrls = new Set(routes.map((r) => r.urlPattern));
     const redirects = generateRedirects(projectConfig.redirects, outDir, {
+      basePath,
       compiledUrls,
       trailingSlash: projectConfig.build.trailingSlash,
     });
@@ -1091,7 +1118,8 @@ export async function buildSite(
   {
     const sw = normalizeServiceWorker(projectConfig.serviceWorker);
     if (sw !== null) {
-      const output = sw === false ? tombstoneServiceWorker() : buildServiceWorker(sw, outDir);
+      const output =
+        sw === false ? tombstoneServiceWorker() : buildServiceWorker(sw, outDir, basePath);
       for (const warning of output.warnings) {
         console.warn(warning);
       }
@@ -1115,7 +1143,7 @@ export async function buildSite(
     );
     errors.push(...headerErrors);
     // Runs here, after every emitter, so it can see which of these files the build actually wrote.
-    const rules = [...securityRules, ...contentTypeRules(outDir)];
+    const rules = rebaseHeaderRules([...securityRules, ...contentTypeRules(outDir)], basePath);
     if (rules.length > 0) {
       log("Writing response headers...");
       fileCount += writeHeaders(outDir, rules);
@@ -1215,6 +1243,10 @@ async function compilePage(
   /** Registers a page's npm `$elements` set as one bundle and returns its URL. */
   registerElementBundle: (specifiers: string[]) => string,
 ) {
+  /* Derived rather than passed as a seventeenth parameter: it is a pure function of
+     `projectConfig.url`, which is already here, so the two cannot disagree. */
+  const basePath = siteBasePath(projectConfig.url);
+
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
 
@@ -1364,7 +1396,7 @@ async function compilePage(
   const swHead: JxHeadEntry[] =
     swConfig === null || swConfig === false
       ? []
-      : [{ tagName: "script", textContent: registrationScript(swConfig.scope ?? "/") }];
+      : [{ tagName: "script", textContent: registrationScript(swConfig.scope ?? "/", basePath) }];
 
   const resolvedSiteHead = [
     // The manifest link and theme colour are first-party and unconditional once declared, so they
@@ -1528,6 +1560,7 @@ function buildMountSpecs(
   if (activeMounts.length === 0) {
     return { connectors: [], mounts: [] };
   }
+  const base = siteBasePath(projectConfig.url);
 
   const sections: Record<string, unknown> = {};
   for (const contribution of registry.projectContributions()) {
@@ -1546,11 +1579,15 @@ function buildMountSpecs(
           `to generate a deployable worker`,
       );
     }
+    /* Both are request paths in the deployed worker: the route it registers, and the prefix the
+       mount strips to find its own sub-path. They must carry the same base or the handler would
+       answer a URL and then mis-read it. */
+    const mountBase = withBase(base, server.basePath);
     return {
-      basePath: server.basePath,
+      basePath: mountBase,
       className: (entry.classDef.title as string | undefined) ?? entry.name,
       module,
-      options: { basePath: server.basePath, sections },
+      options: { basePath: mountBase, sections },
       order: server.order ?? 100,
     };
   });
@@ -2007,27 +2044,23 @@ function expandComponents(
 
   const def = componentDefs.get(node.tagName as string);
   if (def) {
-    // JSON-authored instances pass props as literal `props.*` attribute keys (markdown directives
-    // Are normalized to $props by the parser's expandDotPaths, but JSON is parsed verbatim).
-    // Lift them into $props so the pre-render sees them, and strip them from attributes so they
-    // Don't leak into the emitted HTML. Values stay raw strings — no coercion, matching the
-    // Markdown path and the runtime's $props semantics. Explicit $props wins on key conflicts.
+    // Literal `props.*` attribute keys become $props (`liftPropsAttributes` says why) and leave the
+    // Attributes, so they do not reach the emitted HTML. Explicit $props wins on key conflicts.
     if (node.attributes) {
-      let lifted: NonNullable<JxElement["$props"]> | null = null;
-      for (const [key, value] of Object.entries(node.attributes)) {
-        if (key.startsWith("props.") && key.length > "props.".length) {
-          lifted ??= {};
-          // JxAttributeValue is JSON-representable (primitives or a $ref object), so the
-          // Narrowing to JsonValue is sound.
-          lifted[key.slice("props.".length)] = value as JsonValue;
-          delete node.attributes[key];
-        }
-      }
+      const { lifted, rest } = liftPropsAttributes(node.attributes);
       if (lifted) {
+        node.attributes = rest;
         node.$props = { ...lifted, ...node.$props };
       }
     }
 
+    /*
+     * Slotted children are rendered with NO component registry: this walk is bottom-up, so any
+     * instance among them was expanded a moment ago and now carries its markup as `innerHTML` and
+     * no `$props`. Expanding it again would render the definition's defaults over the props it
+     * was given. Instances written inside `def` itself are another matter — those are reached
+     * below, through `preRenderComponentHtml`, with `node` as the first frame of the path.
+     */
     const slotContent =
       Array.isArray(node.children) && node.children.length > 0
         ? node.children
@@ -2047,7 +2080,15 @@ function expandComponents(
      * render them twice.
      */
     const shadow = resolveShadowMode(def, defaults);
-    const innerHTML = preRenderComponentHtml(def, node.$props || null, shadow ? null : slotContent);
+    const props = node.$props || null;
+    // This instance is the first frame of the path, so a definition that names itself is reported
+    // At the first nesting rather than after the stack overflows.
+    const context: ComponentPrerenderContext = {
+      componentDefs,
+      defaults,
+      path: [{ key: JSON.stringify(props ?? {}), tag: node.tagName as string }],
+    };
+    const innerHTML = preRenderComponentHtml(def, props, shadow ? null : slotContent, context);
     const isStatic = isComponentFullyStatic(def);
 
     /*
@@ -2063,26 +2104,20 @@ function expandComponents(
       : innerHTML;
     delete node.children;
 
-    // Resolve template-string host styles with props (per-instance values like background-image)
-    if (def.style && node.$props) {
-      const stateDefs: Record<string, JxStateDefinition> = { ...def.state };
-      for (const [key, value] of Object.entries(node.$props)) {
-        stateDefs[key] =
-          key in stateDefs ? (value as JxStateDefinition) : (value as JxStateDefinition);
-      }
-      const scope = buildInitialScope(stateDefs, null);
-      const resolvedStyle: Record<string, unknown> = {};
-      for (const [prop, value] of Object.entries(def.style)) {
-        if (typeof value === "string" && isTemplateString(value)) {
-          const resolved = resolveStaticValue(value, scope);
-          if (resolved != null) {
-            resolvedStyle[prop] = resolved;
-          }
-        }
-      }
-      if (Object.keys(resolvedStyle).length > 0) {
-        node.style = { ...node.style, ...resolvedStyle } as JxStyle;
-      }
+    /*
+     * Resolve template-string host styles against the instance (per-instance values like
+     * background-image). The page's style pass gives the result a class rule; a nested instance
+     * gets the same values inline, from the same resolver (`renderComponentInstance` in shared.ts).
+     *
+     * Resolved whether or not the instance passes props: a template declaration is a reactive one
+     * and `pushStyleRules` drops it from the component stylesheet, so the value resolved here is
+     * the ONLY place it reaches a static page. This used to be guarded on `$props`, which left an
+     * instance that took the definition's defaults with no host style at all — no size, no mask —
+     * while the same instance one level down had them.
+     */
+    const resolvedStyle = resolveHostStyle(def.style, buildInstanceScope(def, props));
+    if (Object.keys(resolvedStyle).length > 0) {
+      node.style = { ...node.style, ...resolvedStyle } as JxStyle;
     }
 
     /*
@@ -2369,7 +2404,7 @@ function generateRedirects(
     string | { destination: string; status?: number } | { destination: string; rewrite: true }
   >,
   outDir: string,
-  opts: { compiledUrls?: Set<string>; trailingSlash?: string } = {},
+  opts: { compiledUrls?: Set<string>; trailingSlash?: string; basePath?: string } = {},
 ) {
   let files = 0;
   const errors: string[] = [];
@@ -2396,7 +2431,11 @@ function generateRedirects(
       continue;
     }
 
-    redirectLines.push(`${source} ${dest} ${status}`);
+    /* Both halves are site URLs, and the host matches the source against a REQUEST path — which
+       arrives under the base. A rule left at the old root would never fire, and one that did would
+       send the visitor out of the deployment. */
+    const rebased = opts.basePath ?? "";
+    redirectLines.push(`${withBase(rebased, source)} ${withBase(rebased, dest)} ${status}`);
 
     // A pattern source cannot be a file on disk, so it lives only in `_redirects`.
     if (source.includes(":") || source.includes("*")) {
@@ -2563,7 +2602,7 @@ function ensureRobotsSitemap(outDir: string, siteUrl: string) {
   if (!content.endsWith("\n")) {
     content += "\n";
   }
-  content += `\nSitemap: ${new URL("/sitemap.xml", siteUrl).href}\n`;
+  content += `\nSitemap: ${siteAbsoluteUrl("/sitemap.xml", siteUrl)}\n`;
   writeFileSync(robotsPath, content, "utf8");
   return existed ? 0 : 1;
 }

package/src/site/validate-command.ts

@@ -22,6 +22,11 @@ import { createRequire } from "node:module";
 import { join, relative, resolve } from "node:path";
 import { generateClassSchema } from "@jxsuite/schema";
 import { validateProjectFile } from "@jxsuite/schema/validate-project";
+import { findA11yDefects } from "@jxsuite/schema/a11y";
+import { findDialogDefects } from "@jxsuite/schema/dialogs";
+import { findPopoverDefects, overlayScopeFor } from "@jxsuite/schema/overlays";
+import type { OverlayScope } from "@jxsuite/schema/overlays";
+import type { JxElement } from "@jxsuite/schema/types";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import { readBundledProjectSchemas } from "./schema-command.ts";
@@ -46,8 +51,36 @@ export interface ProjectTreeIssue {
   errors: unknown[];
 }
 
+/**
+ * One overlay, dialog or accessibility finding in a document — `jx validate`'s rendering of the
+ * lints Studio files as Problems (spec §8.7, §8.8). Advisory by default: a lint is a judgement
+ * about a document that is well-formed, so it never makes the tree INVALID unless `strict` asks it
+ * to.
+ */
+export interface ProjectTreeLintFinding {
+  /** Project-relative file path. */
+  file: string;
+  /** The node's path inside the document. */
+  path: (string | number)[];
+  /** Which lint: `popover`, `dialog` or `accessibility`. */
+  source: "popover" | "dialog" | "accessibility";
+  rule: string;
+  message: string;
+  detail: string;
+  severity: "error" | "warn";
+  /** The WCAG success criterion, for accessibility findings. */
+  criterion?: string;
+}
+
+export interface ValidateProjectTreeOptions {
+  /** Fail the tree on a lint ERROR as well as on a schema error. Warnings never fail it. */
+  strict?: boolean;
+}
+
 export interface ProjectTreeValidationResult {
   valid: boolean;
+  /** Every lint finding, whatever `valid` says. */
+  lint: ProjectTreeLintFinding[];
   /** Number of files checked across all five walks. */
   checked: number;
   issues: ProjectTreeIssue[];
@@ -91,9 +124,11 @@ async function loadAjv(): Promise<{ Ajv: AjvCtor; addFormats: AddFormatsFn }> {
  */
 export async function validateProjectTree(
   projectRoot: string,
+  options: ValidateProjectTreeOptions = {},
 ): Promise<ProjectTreeValidationResult> {
   const root = resolve(projectRoot);
   const issues: ProjectTreeIssue[] = [];
+  const lint: ProjectTreeLintFinding[] = [];
   let checked = 0;
 
   /* 1. Committed entry documents must be self-contained (the editor-resolution guarantee). This
@@ -120,7 +155,7 @@ export async function validateProjectTree(
     }
   }
   if (issues.length > 0) {
-    return { checked, issues, valid: false };
+    return { checked, issues, lint, valid: false };
   }
 
   // 2. project.json against the generated entry schema.
@@ -137,6 +172,21 @@ export async function validateProjectTree(
   const docAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(docAjv);
   const validateDoc = docAjv.compile(documentSchema);
+  /* The project's own element definitions, so the overlay rules judge a custom element as what it
+     renders. A component IS a popover when its definition declares one, and a component FORWARDS
+     invocation when it observes the four invoker attributes — neither fact is visible in the page
+     that uses it, so without this the CLI reports a target mismatch on correct markup that the
+     studio, which passes the same scope, calls clean. */
+  const scope = overlayScopeFor(
+    walkClassFiles(root).flatMap((file) => {
+      try {
+        return [JSON.parse(readFileSync(file, "utf8")) as JxElement];
+      } catch {
+        // A malformed definition is reported by the class-schema pass below, not here.
+        return [];
+      }
+    }),
+  );
   for (const dir of DOCUMENT_DIRS) {
     for (const file of walkJsonFiles(resolve(root, dir))) {
       if (file.endsWith(".class.json")) {
@@ -144,7 +194,10 @@ export async function validateProjectTree(
       }
       checked += 1;
       const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
-      if (!validateDoc(doc)) {
+      if (validateDoc(doc)) {
+        // Only a well-formed document is judged; a schema error is the report for the rest.
+        lint.push(...lintDocument(doc as JxElement, relative(root, file), scope));
+      } else {
         issues.push({ errors: validateDoc.errors ?? [], file: relative(root, file) });
       }
     }
@@ -191,7 +244,51 @@ export async function validateProjectTree(
     }
   }
 
-  return { checked, issues, valid: issues.length === 0 };
+  const fatalLint = options.strict === true && lint.some((finding) => finding.severity === "error");
+  return { checked, issues, lint, valid: issues.length === 0 && !fatalLint };
+}
+
+/** The three lints over one document, as findings that name their file. */
+function lintDocument(doc: JxElement, file: string, scope: OverlayScope): ProjectTreeLintFinding[] {
+  const findings: ProjectTreeLintFinding[] = [];
+  for (const defect of findPopoverDefects(doc, scope)) {
+    findings.push({ ...pick(defect), file, source: "popover" });
+  }
+  for (const defect of findDialogDefects(doc, scope)) {
+    findings.push({ ...pick(defect), file, source: "dialog" });
+  }
+  for (const defect of findA11yDefects(doc)) {
+    findings.push({ ...pick(defect), criterion: defect.criterion, file, source: "accessibility" });
+  }
+  return findings;
+}
+
+/** The fields every defect shape shares. */
+function pick(defect: {
+  rule: string;
+  path: (string | number)[];
+  message: string;
+  detail: string;
+  severity: "error" | "warn";
+}): Pick<ProjectTreeLintFinding, "rule" | "path" | "message" | "detail" | "severity"> {
+  return {
+    detail: defect.detail,
+    message: defect.message,
+    path: defect.path,
+    rule: defect.rule,
+    severity: defect.severity,
+  };
+}
+
+/** One line per lint finding, for the CLI: `file: severity: message [source/rule, WCAG n]`. */
+export function formatProjectTreeLint(result: ProjectTreeValidationResult): string[] {
+  return result.lint.map((finding) => {
+    const cite =
+      finding.criterion === undefined
+        ? `${finding.source}/${finding.rule}`
+        : `${finding.source}/${finding.rule}, WCAG ${finding.criterion}`;
+    return `${finding.file}: ${finding.severity}: ${finding.message} [${cite}]`;
+  });
 }
 
 /**

package/src/site/well-known.ts

@@ -9,6 +9,7 @@
  * @docs framework/site/deployment
  */
 
+import { siteBasePath, withBase } from "@jxsuite/schema/asset-paths";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { canonicalizeLocale } from "@jxsuite/schema/locale";
@@ -48,17 +49,27 @@ export function buildManifest(projectConfig: ProjectConfig): WellKnownOutput {
   }
 
   const name = config.name ?? projectConfig.name ?? "Jx Site";
-  const icons = config.icons ?? [];
+  /*
+   * Every URL in a manifest is fetched or navigated to by the browser, so all three carry the
+   * deployment base (`base-path.ts`). `scope` is the one that fails loudly — a scope the manifest's
+   * own URL is not inside makes the manifest invalid and the site uninstallable — while a
+   * `start_url` at the old root just opens the wrong page from the home screen.
+   */
+  const base = siteBasePath(projectConfig.url);
+  const icons = [];
+  for (const icon of config.icons ?? []) {
+    icons.push(typeof icon.src === "string" ? { ...icon, src: withBase(base, icon.src) } : icon);
+  }
   const manifest: Record<string, unknown> = {
     display: config.display ?? "standalone",
     icons,
     name,
     short_name: config.shortName ?? name,
-    start_url: config.startUrl ?? "/",
+    start_url: withBase(base, config.startUrl ?? "/"),
     ...(config.description === undefined ? {} : { description: config.description }),
     ...(config.themeColor === undefined ? {} : { theme_color: config.themeColor }),
     ...(config.backgroundColor === undefined ? {} : { background_color: config.backgroundColor }),
-    ...(config.scope === undefined ? {} : { scope: config.scope }),
+    ...(config.scope === undefined ? {} : { scope: withBase(base, config.scope) }),
     ...(config.orientation === undefined ? {} : { orientation: config.orientation }),
     ...(config.lang === undefined ? {} : { lang: config.lang }),
     ...(config.dir === undefined ? {} : { dir: config.dir }),

package/src/targets/compile-client.ts

@@ -13,6 +13,9 @@
 
 import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
+  ATTR_HELPER,
+  attrHelperSource,
+  booleanAttrValue,
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
   buildAttrs,
@@ -675,10 +678,24 @@ function emitLitMapTemplate(def: JxMutableNode | undefined, preformatted = false
   // Attributes object
   if (def.attributes && typeof def.attributes === "object") {
     for (const [k, v] of Object.entries(def.attributes)) {
-      attrs +=
-        typeof v === "string" && isTemplateString(v)
-          ? ` ${k}="${mapRefsToLit(v)}"`
-          : ` ${k}="${escapeHtml(String(v))}"`;
+      if (typeof v === "string" && isTemplateString(v)) {
+        attrs += ` ${k}="${mapRefsToLit(v)}"`;
+        continue;
+      }
+      /* A boolean is the attribute's PRESENCE or its text depending on the family its NAME puts it
+         in — `booleanAttrValue` owns that judgement, and the static emitter in `shared.ts` and the
+         runtime's `applyAttributes` both defer to it, so a prerendered page cannot change meaning
+         as it hydrates (spec.md §8.3). Stringifying here emitted `open="false"`, which HTML reads
+         by presence and therefore as an OPEN element: the author wrote "closed" and the page
+         rendered open. */
+      if (typeof v === "boolean") {
+        const text = booleanAttrValue(k, v);
+        if (text !== null) {
+          attrs += text === "" ? ` ${k}` : ` ${k}="${escapeHtml(text)}"`;
+        }
+        continue;
+      }
+      attrs += ` ${k}="${escapeHtml(String(v))}"`;
     }
   }
 
@@ -884,7 +901,9 @@ function emitClientModule(
   }
 
   // State — reactive state
-  lines.push("", "const state = reactive({");
+  /* The boolean-attribute rule, inlined because this module loads with `@vue/reactivity` and
+     nothing else — see `attrHelperSource`. The hydration script below is its only caller. */
+  lines.push("", attrHelperSource(), "", "const state = reactive({");
   for (const [key, val] of stateEntries) {
     /*
      * State keys come from the document, so `{"user.name": 1}` is legal input. Pasting one raw as
@@ -960,7 +979,14 @@ function emitClientModule(
   lines.push(
     "          effect(() => { el.style[parts[1]] = bind[key](); });",
     "        } else if (parts[0] === 'attr' && parts.length > 1) {",
-    "          effect(() => { el.setAttribute(parts[1], bind[key]()); });",
+    // A binding that flips back has to take the attribute WITH it: the element is being re-used, so
+    // Anything left behind is the state the page just said it had left. Same decision as the
+    // Runtime's `applyAttributes`, through the same inlined rule — see `attrHelperSource`.
+    "          effect(() => {",
+    `            const _t = ${ATTR_HELPER}(parts[1], bind[key]());`,
+    "            if (_t === null) { el.removeAttribute(parts[1]); }",
+    "            else { el.setAttribute(parts[1], _t); }",
+    "          });",
     "        } else {",
     "          const prop = parts[0].replace(/-([a-z])/g, (_, c) => c.toUpperCase());",
     "          effect(() => { el[prop] = bind[key](); });",

package/src/targets/compile-element.ts

@@ -7,6 +7,9 @@
 
 import { RESERVED_KEYS, camelToKebab } from "@jxsuite/runtime";
 import {
+  ATTR_HELPER,
+  attrHelperSource,
+  booleanAttrValue,
   PREFORMATTED_TAGS,
   collectStyles,
   compileExpression,
@@ -405,7 +408,11 @@ export function emitElementModule(
 
   lines.push(
     `import { reactive, computed, effect, stop } from '@vue/reactivity';`,
-    `import { render, html } from 'lit-html';`,
+    /* `nothing` is what REMOVES an attribute in a lit template, and it is the only way to express a
+       false presence attribute: writing `open="false"` produces an OPEN <details>. See
+       `attrHelperSource`. */
+    `import { render, html, nothing } from 'lit-html';`,
+    attrHelperSource(),
   );
 
   /*
@@ -1037,10 +1044,26 @@ ${no}
 
   if (def.attributes) {
     for (const [key, val] of Object.entries(def.attributes)) {
+      /* Every branch here answers the same question the runtime's `applyAttributes` answers, and
+         must answer it the same way or a prerendered page changes meaning as it hydrates (spec.md
+         §8.3). A LITERAL boolean is decided now; a BOUND one cannot be, because its resolved type
+         is not known until the effect runs — so it goes through the emitted helper, whose `null`
+         becomes lit's `nothing` and takes the attribute off. */
       if (val && typeof val === "object" && isRef(val)) {
-        parts.push(`${key}="\${${refToExpr(val.$ref)}}"`);
+        parts.push(`${key}="\${${ATTR_HELPER}('${key}', ${refToExpr(val.$ref)}) ?? nothing}"`);
+      } else if (typeof val === "string" && isWholeTemplate(val)) {
+        parts.push(
+          `${key}="\${${ATTR_HELPER}('${key}', ${toLitExpr(val).slice(2, -1)}) ?? nothing}"`,
+        );
       } else if (typeof val === "string" && val.includes("${")) {
+        /* A template with literal text around it — `"page ${n}"` — is a string by construction, so
+           there is no boolean to decide and wrapping it would only add a call. */
         parts.push(`${key}="${toLitExpr(val)}"`);
+      } else if (typeof val === "boolean") {
+        const text = booleanAttrValue(key, val);
+        if (text !== null) {
+          parts.push(text === "" ? key : `${key}="${text}"`);
+        }
       } else {
         parts.push(`${key}="${val}"`);
       }
@@ -1404,6 +1427,20 @@ function toLitExpr(str: string) {
   return str.replaceAll("state.", "s.");
 }
 
+/**
+ * Whether the whole attribute value is ONE `${…}` and nothing else.
+ *
+ * Only such a value can resolve to a boolean — anything with literal text around the expression is
+ * a string by construction — so this is the test for whether the boolean decision has to be
+ * deferred to runtime.
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isWholeTemplate(str: string): boolean {
+  return str.startsWith("${") && str.endsWith("}") && !str.slice(2).includes("${");
+}
+
 /**
  * Convert textContent value to lit-html text content. Bug fix: handles $ref objects, which
  * previously produced [object Object].

package/src/targets/compile-server.ts

@@ -5,6 +5,7 @@
  * file.
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
 import { collectServerEntries } from "../shared.ts";
 import { localeNegotiationMiddleware } from "../site/locale-negotiation.ts";
@@ -110,15 +111,21 @@ export function compileSiteServer(
     mounts?: SiteMountSpec[];
     connectors?: SiteConnectorSpec[];
     i18n?: ResolvedI18n | null;
+    base?: string;
   } = {},
 ) {
-  const {
-    baseUrl = "/_jx/server",
-    adapter = null,
-    mounts = [],
-    connectors = [],
-    i18n = null,
-  } = opts;
+  const { adapter = null, mounts = [], connectors = [], i18n = null, base = "" } = opts;
+  /*
+   * Routes are registered under the deployment base (`site/base-path.ts`), because the worker IS
+   * the origin: the request it sees is the one the visitor's browser sent, and on a site served
+   * from `/m/my-site/` that path carries the prefix. A route left at the bare path would simply
+   * never match — the 404 nobody attributes to a config value.
+   *
+   * The dev server takes the opposite approach and strips the base at the edge (`server.ts`), so
+   * everything behind it routes on the bare path. Each is internally consistent: production serves
+   * exactly one URL space, while `jx dev` deliberately answers both.
+   */
+  const baseUrl = withBase(base, opts.baseUrl ?? "/_jx/server");
   if (entries.length === 0 && mounts.length === 0 && !adapter) {
     return null;
   }