@jxsuite/compiler 1.5.0 → 2.0.0

package/src/site/site-loader.ts

@@ -48,6 +48,7 @@ const DEFAULTS = {
     formats: ["webp", "avif"],
     lazyLoad: true,
     optimize: true,
+    picture: true,
     quality: { avif: 65, jpeg: 80, png: 80, webp: 80 },
     service: "build",
     sizes: "(max-width: 768px) 100vw, 50vw",

package/src/site/validate-command.ts

@@ -133,7 +133,7 @@ export async function validateProjectTree(
   const { addFormats, Ajv } = await loadAjv();
 
   // 3. Documents against the bundled document schema (the same schema the studio consumes).
-  const { document: documentSchema } = await readBundledProjectSchemas(root);
+  const { document: documentSchema } = await readBundledProjectSchemas(root, { write: false });
   const docAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(docAjv);
   const validateDoc = docAjv.compile(documentSchema);

package/src/site/well-known.ts

@@ -0,0 +1,221 @@
+/**
+ * Two files a site is expected to publish and nothing generates: `manifest.webmanifest` and
+ * `.well-known/security.txt`.
+ *
+ * Both are pure functions of `project.json` plus what the build already knows about the site, which
+ * is the reason they belong here rather than in `public/` — an author copying either between
+ * projects also copies the values that were right for the other one.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { canonicalizeLocale } from "@jxsuite/schema/locale";
+import type { ManifestConfig, ProjectConfig, SecurityTxtConfig } from "@jxsuite/schema/types";
+
+/** The two sizes a browser wants before it will offer to install a site. */
+const INSTALL_ICON_SIZES = [192, 512];
+
+export interface GeneratedFile {
+  /** Path relative to `outDir`. */
+  path: string;
+  content: string;
+}
+
+export interface WellKnownOutput {
+  files: GeneratedFile[];
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Build `manifest.webmanifest` from the `manifest` section, falling back to what the project
+ * already says about itself.
+ *
+ * `name` and `start_url` are not asked for twice: a project has a `name`, and `start_url` is the
+ * site root unless the author says otherwise. Everything else is theirs.
+ *
+ * @param {ProjectConfig} projectConfig
+ * @returns {WellKnownOutput}
+ */
+export function buildManifest(projectConfig: ProjectConfig): WellKnownOutput {
+  const config: ManifestConfig | undefined = projectConfig.manifest;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (config === undefined || config.enabled === false) {
+    return { errors, files: [], warnings };
+  }
+
+  const name = config.name ?? projectConfig.name ?? "Jx Site";
+  const icons = config.icons ?? [];
+  const manifest: Record<string, unknown> = {
+    display: config.display ?? "standalone",
+    icons,
+    name,
+    short_name: config.shortName ?? name,
+    start_url: 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.orientation === undefined ? {} : { orientation: config.orientation }),
+    ...(config.lang === undefined ? {} : { lang: config.lang }),
+    ...(config.dir === undefined ? {} : { dir: config.dir }),
+    ...(config.categories === undefined ? {} : { categories: config.categories }),
+  };
+
+  /*
+   * A warning, not an error. The manifest is valid and useful without these — it still supplies
+   * the name and theme colour a browser shows — but a site cannot be *installed* without an icon
+   * at each size, and that is the whole reason most people add one.
+   */
+  const declared = new Set(
+    icons.flatMap((icon) =>
+      (icon.sizes ?? "").split(/\s+/).map((size) => Math.trunc(Number(size.split("x")[0]))),
+    ),
+  );
+  const missing = INSTALL_ICON_SIZES.filter((size) => !declared.has(size));
+  if (missing.length > 0) {
+    warnings.push(
+      `manifest: no ${missing.join("px and no ")}px icon declared — browsers will not offer to ` +
+        "install the site without one at each size.",
+    );
+  }
+
+  return {
+    errors,
+    files: [{ content: `${JSON.stringify(manifest, null, 2)}\n`, path: "manifest.webmanifest" }],
+    warnings,
+  };
+}
+
+/** The `<head>` entries a generated manifest needs to be found and to look right when installed. */
+export function manifestHeadEntries(
+  projectConfig: ProjectConfig,
+): { tagName: string; attributes: Record<string, string> }[] {
+  const config = projectConfig.manifest;
+  if (config === undefined || config.enabled === false) {
+    return [];
+  }
+  const entries: { tagName: string; attributes: Record<string, string> }[] = [
+    { attributes: { href: "/manifest.webmanifest", rel: "manifest" }, tagName: "link" },
+  ];
+  if (config.themeColor !== undefined) {
+    entries.push({
+      attributes: { content: config.themeColor, name: "theme-color" },
+      tagName: "meta",
+    });
+  }
+  return entries;
+}
+
+/**
+ * Build `.well-known/security.txt` (RFC 9116).
+ *
+ * `.well-known` only. §3 makes that the canonical location, and a second copy at the root is a
+ * second thing to forget to update.
+ *
+ * @param {ProjectConfig} projectConfig
+ * @param {Date} now - Evaluated against `Expires`; injected so the check is testable
+ * @returns {WellKnownOutput}
+ */
+export function buildSecurityTxt(projectConfig: ProjectConfig, now: Date): WellKnownOutput {
+  const config: SecurityTxtConfig | undefined = projectConfig.securityTxt;
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  if (config === undefined || config.enabled === false) {
+    return { errors, files: [], warnings };
+  }
+
+  const contact = config.contact ?? [];
+  if (contact.length === 0) {
+    errors.push("securityTxt: at least one `contact` is required (RFC 9116 §2.5.3).");
+  }
+
+  /*
+   * `Expires` is required by §2.5.5, and it is the field everyone forgets. A past date is worse
+   * than a missing file: it advertises a reporting channel while telling the reporter the
+   * information is stale, so both cases fail the build rather than emitting something misleading.
+   */
+  if (config.expires === undefined) {
+    errors.push(
+      "securityTxt: `expires` is required (RFC 9116 §2.5.5) — a security.txt with no expiry " +
+        "never goes stale visibly, which is how they end up pointing at people who left.",
+    );
+  } else {
+    const expires = new Date(config.expires);
+    if (Number.isNaN(expires.getTime())) {
+      errors.push(`securityTxt: \`expires\` is not a valid date: "${config.expires}".`);
+    } else if (expires.getTime() <= now.getTime()) {
+      errors.push(
+        `securityTxt: \`expires\` is in the past (${expires.toISOString()}) — an expired ` +
+          "security.txt tells a reporter not to trust what it says.",
+      );
+    }
+  }
+
+  const languages: string[] = [];
+  for (const tag of config.preferredLanguages ?? []) {
+    const canonical = canonicalizeLocale(tag);
+    if (canonical === null) {
+      errors.push(`securityTxt.preferredLanguages: "${tag}" is not a well-formed language tag.`);
+    } else {
+      languages.push(canonical);
+    }
+  }
+
+  if (errors.length > 0) {
+    return { errors, files: [], warnings };
+  }
+
+  const lines: string[] = [
+    "# Generated by @jxsuite/compiler — configure via securityTxt in project.json.",
+    ...contact.map((value) => `Contact: ${value}`),
+    `Expires: ${new Date(config.expires as string).toISOString().replace(/\.\d{3}Z$/, "Z")}`,
+    ...(config.encryption ?? []).map((value) => `Encryption: ${value}`),
+    ...(config.acknowledgments ?? []).map((value) => `Acknowledgments: ${value}`),
+    ...(languages.length > 0 ? [`Preferred-Languages: ${languages.join(", ")}`] : []),
+    ...(config.canonical === undefined ? [] : [`Canonical: ${config.canonical}`]),
+    ...(config.policy ?? []).map((value) => `Policy: ${value}`),
+    ...(config.hiring ?? []).map((value) => `Hiring: ${value}`),
+  ];
+
+  return {
+    errors,
+    files: [{ content: `${lines.join("\n")}\n`, path: ".well-known/security.txt" }],
+    warnings,
+  };
+}
+
+/**
+ * Write generated files under `outDir`, skipping any the author already supplied.
+ *
+ * The skip is the point: `public/.well-known/security.txt` is copied before this runs, and a
+ * hand-placed file there is how an author ships a **clearsigned** one — which needs a private key
+ * at build time and is therefore not something the build can do. Deferring costs zero code.
+ *
+ * @param {readonly GeneratedFile[]} files
+ * @param {string} outDir
+ * @param {(path: string) => boolean} exists
+ * @returns {{ written: number; skipped: string[] }}
+ */
+export function writeWellKnown(
+  files: readonly GeneratedFile[],
+  outDir: string,
+  exists: (path: string) => boolean,
+): { written: number; skipped: string[] } {
+  let written = 0;
+  const skipped: string[] = [];
+  for (const file of files) {
+    const target = join(outDir, file.path);
+    if (exists(target)) {
+      skipped.push(file.path);
+      continue;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, file.content, "utf8");
+    written += 1;
+  }
+  return { skipped, written };
+}

package/src/targets/compile-client.ts

@@ -43,9 +43,18 @@ import {
   isMappedArray,
   isNamedFormulaDef,
   isPrototypeDef,
+  isTagExpression,
   paramNames,
+  tagNameCandidates,
 } from "@jxsuite/schema/guards";
 import type { CompileContext, ExpressionNode } from "../shared.ts";
+import {
+  escapeToken,
+  objectKey,
+  refAccessor,
+  refBindingKey,
+  refSegments,
+} from "@jxsuite/runtime/pointer";
 import type {
   JsonObject,
   JsonValue,
@@ -338,6 +347,19 @@ function buildClientNode(
     raw?.$media ?? context.media,
   );
 
+  /* REFUSED, LOUDLY. A chosen tag has no implementation in this target: the element's identity is
+     fixed in the prerendered markup, so there is nothing here to re-choose at hydration the way the
+     `$switch` binding below re-chooses a subtree. Emitting a silently wrong element would be an
+     instance of the class the tagName pattern was added to end, so a dynamic page that needs a
+     chosen tag is told to put the element in a component (which compiles through `compile-element`,
+     where the construct is implemented) rather than shipping markup with the wrong tag. */
+  if (isTagExpression(def.tagName)) {
+    throw new Error(
+      "A tag chosen at creation is not supported on a dynamic page yet (candidates: " +
+        `${tagNameCandidates(def.tagName).join(", ")}). Move the element into a component, or ` +
+        "give it a literal tagName.",
+    );
+  }
   const tag = def.tagName ?? "div";
   // `white-space` inherits, so once inside a <pre> the whole subtree stays whitespace-significant.
   nextContext.preformatted = context.preformatted === true || PREFORMATTED_TAGS.has(tag);
@@ -484,6 +506,33 @@ function buildClientNode(
   // Inner content
   let inner = "";
   const source = raw ?? def;
+  if (source.$switch) {
+    // ─── $switch → lit-html render binding ───
+    // Without this branch the node fell through to the generic element path, which emitted a
+    // Container and then looked for `children` to recurse into — `cases` is not `children`, so the
+    // Subtree was never visited and the page shipped with the content missing, no error (#127).
+    // The container is emitted empty for the same reason the mapped-array branch below is: lit's
+    // `render` appends into the container rather than replacing its existing children, so any
+    // Prerendered branch would survive alongside the rendered one.
+    counter.needsLit = true;
+    const swKey = `_sw${counter.sw}`;
+    counter.sw += 1;
+    const discriminant = isRefObject(source.$switch)
+      ? `state.${refToBindingKey((source.$switch as { $ref: string }).$ref)}`
+      : `\`${String(source.$switch)}\``;
+    const cases = (source.cases ?? {}) as Record<string, JxMutableNode>;
+    const caseEntries = Object.entries(cases)
+      // An external `$ref` case cannot be fetched at compile time, exactly as in the static target.
+      .filter(([, caseDef]) => caseDef && !isRefObject(caseDef))
+      .map(
+        ([key, caseDef]) =>
+          `${JSON.stringify(key)}: html\`${emitChildLit(caseDef, nextContext.preformatted)}\``,
+      );
+    bindings.set(swKey, `() => ({${caseEntries.join(", ")}})[String(${discriminant})] ?? html\`\``);
+    bindAttrs.push(`:render="${swKey}"`);
+    const bindAttrStrSwitch = ` ${bindAttrs.join(" ")}`;
+    return `<${tag}${staticAttrs} data-bind${bindAttrStrSwitch}></${tag}>`;
+  }
   if (source.textContent !== undefined && !needsBind) {
     const value = resolveStaticValue(source.textContent, nextContext.scope);
     inner = value == null ? "" : escapeHtml(String(value));
@@ -588,6 +637,15 @@ function emitLitMapTemplate(def: JxMutableNode | undefined, preformatted = false
   if (!def) {
     return "";
   }
+  // Same refusal as `buildClientNode` above, for the repeater's item template — this target has no
+  // Branch construct, and a silently wrong element is what the tagName pattern exists to prevent.
+  if (isTagExpression(def.tagName)) {
+    throw new Error(
+      "A tag chosen at creation is not supported inside a dynamic page's repeater yet " +
+        `(candidates: ${tagNameCandidates(def.tagName).join(", ")}). Move the item into a ` +
+        "component, or give it a literal tagName.",
+    );
+  }
   const tag = def.tagName ?? "div";
   // `white-space` inherits, so once inside a <pre> the whole subtree stays whitespace-significant.
   const inPre = preformatted || PREFORMATTED_TAGS.has(tag);
@@ -828,7 +886,11 @@ function emitClientModule(
   // State — reactive state
   lines.push("", "const state = reactive({");
   for (const [key, val] of stateEntries) {
-    lines.push(`  ${key}: ${JSON.stringify(val)},`);
+    /*
+     * State keys come from the document, so `{"user.name": 1}` is legal input. Pasting one raw as
+     * an identifier emitted `user.name: 1,` — a SyntaxError the build reported as a success.
+     */
+    lines.push(`  ${objectKey(key)}: ${JSON.stringify(val)},`);
   }
   lines.push("});", "");
 
@@ -843,7 +905,7 @@ function emitClientModule(
   // Computed signals on state
   if (computedEntries.length > 0) {
     for (const [key, expr] of computedEntries) {
-      lines.push(`state.${key} = computed(${expr});`);
+      lines.push(`${refAccessor("state", escapeToken(key))} = computed(${expr});`);
     }
     lines.push("");
   }
@@ -852,7 +914,7 @@ function emitClientModule(
   if (bindEntries.length > 0) {
     lines.push("const bind = {");
     for (const [key, expr] of bindEntries) {
-      lines.push(`  ${key}: ${expr},`);
+      lines.push(`  ${objectKey(key)}: ${expr},`);
     }
     lines.push("};");
   } else {
@@ -867,7 +929,7 @@ function emitClientModule(
       const argNames = def.args ?? ["state"];
       const callArgs = argNames.map((a: string) => (a === "state" ? "state" : "e")).join(", ");
       lines.push(
-        `  ${key}: (e) => { const fn = (${argNames.join(", ")}) => { ${def.body} }; fn(${
+        `  ${objectKey(key)}: (e) => { const fn = (${argNames.join(", ")}) => { ${def.body} }; fn(${
           callArgs
         }); },`,
       );
@@ -983,19 +1045,27 @@ function emitCookieInit(key: string, cookieName: string, defaultVal: unknown) {
  */
 function mapRefToClientExpr(ref: string) {
   if (ref.startsWith("$map/")) {
-    return ref.slice("$map/".length).replaceAll("/", ".");
+    // The loop variable is an emitted identifier, so its first segment is the base, not a member.
+    const [head, ...rest] = refSegments(ref.slice("$map/".length));
+    return refAccessor(head ?? "", rest.map((seg) => escapeToken(seg)).join("/"));
   }
   if (ref.startsWith("#/state/")) {
-    return `state.${ref.slice("#/state/".length).replaceAll("/", ".")}`;
+    return refAccessor("state", ref.slice("#/state/".length));
   }
-  return `state.${ref.replaceAll("/", ".")}`;
+  return refAccessor("state", ref);
 }
 
+/**
+ * The `bind`/`on` map key for a ref. It is emitted both as an object-literal key and as a
+ * `data-bind` attribute value, so it has to survive being a JavaScript identifier and an HTML
+ * attribute at once. Stripping the `#/state/` prefix first keeps every pure-slash ref on the key it
+ * already had — `#/state/user/name` is still `user_name` — so this fix changes no shipped output.
+ *
+ * @param {string} ref
+ * @returns {string}
+ */
 function refToBindingKey(ref: string) {
-  if (ref.startsWith("#/state/")) {
-    return ref.slice("#/state/".length).replaceAll("/", "_");
-  }
-  return ref.replaceAll("/", "_");
+  return refBindingKey(ref.startsWith("#/state/") ? ref.slice("#/state/".length) : ref);
 }
 
 /**
@@ -1007,11 +1077,8 @@ function addRefBinding(bindings: Map<string, string>, key: string, ref: string)
   if (bindings.has(key)) {
     return;
   }
-  if (ref.startsWith("#/state/")) {
-    const path = ref.slice("#/state/".length);
-    const parts = path.split("/");
-    bindings.set(key, `() => state.${parts.join(".")}`);
-  } else {
-    bindings.set(key, `() => state.${ref}`);
-  }
+  bindings.set(
+    key,
+    `() => ${refAccessor("state", ref.startsWith("#/state/") ? ref.slice("#/state/".length) : ref)}`,
+  );
 }