@jxsuite/schema 1.5.0 → 1.8.0

package/schemas/project.core.schema.json

@@ -15,6 +15,10 @@
         "optimize": {
           "type": "boolean"
         },
+        "picture": {
+          "description": "Wrap a multi-format image in a <picture> with one <source> per format (default true). With it off the <img> carries a srcset in the preferred format alone, which browsers that cannot decode that format will still select from.",
+          "type": "boolean"
+        },
         "quality": {
           "properties": {
             "avif": {
@@ -254,6 +258,158 @@
           "description": "Output directory for compiled site.",
           "type": "string"
         },
+        "headers": {
+          "additionalProperties": false,
+          "description": "Emit dist/_headers — the response headers only the build can know. Honored by Cloudflare Pages/Workers assets and Netlify; on the node/bun adapters the file documents what a reverse proxy in front of them must send.",
+          "properties": {
+            "cache": {
+              "default": "auto",
+              "description": "\"auto\" marks the content-addressed image variants immutable (RFC 8246) and revalidates everything else (RFC 9111). \"off\" emits no Cache-Control at all.",
+              "enum": ["auto", "off"],
+              "type": "string"
+            },
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "rules": {
+              "additionalProperties": {
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              "description": "Verbatim rules, merged after the generated block.",
+              "propertyNames": {
+                "pattern": "^/"
+              },
+              "type": "object"
+            },
+            "security": {
+              "additionalProperties": false,
+              "properties": {
+                "contentTypeOptions": {
+                  "default": true,
+                  "type": "boolean"
+                },
+                "csp": {
+                  "default": false,
+                  "description": "CSP Level 3. Off by default: unlike the other security headers this one governs code the build cannot see — a third-party script that loads a second script, a widget that opens a frame — so turning it on is a change to verify in the browser console, not a safe default. `script-src` is derived from the inline scripts and external origins the build emitted; `style-src` keeps 'unsafe-inline', because per-page <style> blocks and per-element style attributes have no site-wide hash.",
+                  "oneOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "const": "report-only"
+                    },
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "directives": {
+                          "additionalProperties": {
+                            "oneOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "const": false
+                              }
+                            ]
+                          },
+                          "description": "Replace (string) or remove (false) a computed directive. A replacement is wholesale, so an addition restates the defaults.",
+                          "type": "object"
+                        },
+                        "mode": {
+                          "default": "enforce",
+                          "enum": ["enforce", "report-only"]
+                        },
+                        "reportUri": {
+                          "format": "uri-reference",
+                          "type": "string"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                },
+                "frameOptions": {
+                  "default": "SAMEORIGIN",
+                  "oneOf": [
+                    {
+                      "enum": ["DENY", "SAMEORIGIN"],
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                },
+                "hsts": {
+                  "default": false,
+                  "description": "RFC 6797. Off by default: a wrong max-age locks the apex domain to HTTPS for that long, and the mistake is invisible until a certificate lapses. `preload` requires `includeSubDomains` and is a build error without it.",
+                  "oneOf": [
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "additionalProperties": false,
+                      "properties": {
+                        "includeSubDomains": {
+                          "default": true,
+                          "type": "boolean"
+                        },
+                        "maxAge": {
+                          "default": 31536000,
+                          "minimum": 0,
+                          "type": "integer"
+                        },
+                        "preload": {
+                          "default": false,
+                          "type": "boolean"
+                        }
+                      },
+                      "type": "object"
+                    }
+                  ]
+                },
+                "permissionsPolicy": {
+                  "default": "camera=(), microphone=(), geolocation=()",
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                },
+                "referrerPolicy": {
+                  "default": "strict-origin-when-cross-origin",
+                  "oneOf": [
+                    {
+                      "enum": [
+                        "no-referrer",
+                        "no-referrer-when-downgrade",
+                        "origin",
+                        "origin-when-cross-origin",
+                        "same-origin",
+                        "strict-origin",
+                        "strict-origin-when-cross-origin",
+                        "unsafe-url"
+                      ],
+                      "type": "string"
+                    },
+                    {
+                      "const": false
+                    }
+                  ]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "type": "object"
+        },
         "sitemap": {
           "default": true,
           "description": "Generate sitemap.xml from the route table (requires `url`). Set false to disable.",
@@ -283,9 +439,14 @@
           "description": "Default charset for the page.",
           "type": "string"
         },
+        "dir": {
+          "description": "Base direction for the <html> element. Omitted when unset — a page's `$dir` overrides it. Right-to-left content renders left-to-right without this.",
+          "enum": ["ltr", "rtl", "auto"],
+          "type": "string"
+        },
         "lang": {
           "default": "en",
-          "description": "Default lang attribute for the <html> element.",
+          "description": "Default lang attribute for the <html> element. A page's `$lang` overrides it.",
           "type": "string"
         },
         "layout": {
@@ -300,6 +461,20 @@
               "type": "null"
             }
           ]
+        },
+        "shadow": {
+          "default": false,
+          "description": "Default shadow-DOM mode for every component (spec.md §16.6). Off unless set: a shadow root isolates component styles from the page and replaces the <slot> emulation with real slot distribution. A component's own `$shadow` overrides this in both directions.",
+          "oneOf": [
+            {
+              "enum": ["open", "closed"],
+              "type": "string"
+            },
+            {
+              "const": false,
+              "type": "boolean"
+            }
+          ]
         }
       },
       "type": "object"
@@ -312,18 +487,191 @@
       },
       "type": "array"
     },
+    "manifest": {
+      "additionalProperties": false,
+      "description": "W3C Web App Manifest, emitted as manifest.webmanifest with a <link rel=\"manifest\"> on every page. Absent means no manifest: it is a claim that a site is meant to be installed, and most are not.",
+      "properties": {
+        "backgroundColor": {
+          "type": "string"
+        },
+        "categories": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "description": {
+          "type": "string"
+        },
+        "dir": {
+          "enum": ["ltr", "rtl", "auto"],
+          "type": "string"
+        },
+        "display": {
+          "default": "standalone",
+          "enum": ["fullscreen", "standalone", "minimal-ui", "browser"],
+          "type": "string"
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "icons": {
+          "description": "Icons at 192px and 512px are what browsers require before offering to install the site; the build warns when either is missing.",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "purpose": {
+                "type": "string"
+              },
+              "sizes": {
+                "examples": ["192x192"],
+                "type": "string"
+              },
+              "src": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              }
+            },
+            "required": ["src"],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "lang": {
+          "type": "string"
+        },
+        "name": {
+          "description": "Defaults to the project name.",
+          "type": "string"
+        },
+        "orientation": {
+          "type": "string"
+        },
+        "scope": {
+          "type": "string"
+        },
+        "shortName": {
+          "type": "string"
+        },
+        "startUrl": {
+          "default": "/",
+          "type": "string"
+        },
+        "themeColor": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "serviceWorker": {
+      "default": false,
+      "description": "W3C Service Worker, emitted as sw.js. Off unless declared — a worker is sticky, so it is the one output that can keep breaking visitors after a deploy tries to fix them. **Turning it off means `false`, not deleting the key**: `false` emits a tombstone at the same URL that unregisters the old worker and clears its caches, and a 404 there is not an instruction to stop. HTML is always network-first; only the content-addressed /images/_optimized/* is served cache-first.",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "offlineFallback": {
+              "description": "Page served for a failed navigation. Added to `precache` if not already there.",
+              "type": "string"
+            },
+            "precache": {
+              "description": "Site-absolute URLs fetched at install time. Each must be a file this build produces; one that is not fails the build, because a single unreachable entry stops the worker installing at all.",
+              "items": {
+                "pattern": "^/",
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "scope": {
+              "default": "/",
+              "type": "string"
+            }
+          },
+          "type": "object"
+        }
+      ]
+    },
+    "securityTxt": {
+      "additionalProperties": false,
+      "description": "RFC 9116 security.txt, emitted at .well-known/security.txt. `expires` is required by §2.5.5 and an absent or past value is a build error — an expired file advertises a reporting channel while telling the reporter not to trust it. A hand-placed public/.well-known/security.txt shadows this, which is how a clearsigned file ships.",
+      "properties": {
+        "acknowledgments": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "canonical": {
+          "type": "string"
+        },
+        "contact": {
+          "description": "At least one mailto:, https: or tel: URI (§2.5.3).",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "encryption": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "expires": {
+          "format": "date-time",
+          "type": "string"
+        },
+        "hiring": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "policy": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "preferredLanguages": {
+          "description": "BCP 47 tags, validated and canonicalized like i18n.locales.",
+          "items": {
+            "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
     "i18n": {
       "description": "Internationalization configuration.",
       "properties": {
         "defaultLocale": {
-          "description": "Default locale code.",
+          "description": "Default locale, as a BCP 47 language tag. The pattern catches shape errors (`en_US`, `en--US`); the build is the authority on well-formedness.",
           "examples": ["en"],
+          "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
           "type": "string"
         },
         "locales": {
-          "description": "Available locale codes.",
+          "description": "Available locales, as BCP 47 language tags.",
           "examples": [["en", "fr", "de"]],
           "items": {
+            "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$",
             "type": "string"
           },
           "type": "array"
@@ -360,14 +708,62 @@
     },
     "redirects": {
       "additionalProperties": {
-        "type": "string"
+        "oneOf": [
+          {
+            "description": "Destination path or URL; implies a 301.",
+            "type": "string"
+          },
+          {
+            "additionalProperties": false,
+            "description": "A redirect with an explicit RFC 9110 §15.4 status.",
+            "properties": {
+              "destination": {
+                "type": "string"
+              },
+              "status": {
+                "default": 301,
+                "description": "RFC 9110 §15.4 redirection status. 307 and 308 preserve the request method; 301 and 302 historically do not.",
+                "enum": [301, 302, 303, 307, 308],
+                "type": "integer"
+              }
+            },
+            "required": ["destination"],
+            "type": "object"
+          },
+          {
+            "additionalProperties": false,
+            "description": "A rewrite (proxy): the destination's content is served AT the source URL, with no redirect. Emitted as status 200 in `_redirects`, which is the host convention — not an HTTP redirection status.",
+            "properties": {
+              "destination": {
+                "type": "string"
+              },
+              "rewrite": {
+                "const": true,
+                "type": "boolean"
+              }
+            },
+            "required": ["destination", "rewrite"],
+            "type": "object"
+          }
+        ]
       },
-      "description": "Static redirect rules. Maps source paths to destination paths.",
+      "description": "Static redirect and rewrite rules. Keys are source paths in URLPattern pathname syntax.",
       "examples": [
         {
+          "/api/*": {
+            "destination": "https://api.example.com/*",
+            "rewrite": true
+          },
+          "/legacy/*": {
+            "destination": "/archive/*",
+            "status": 308
+          },
           "/old-about": "/about"
         }
       ],
+      "propertyNames": {
+        "pattern": "^/"
+      },
       "type": "object"
     },
     "state": {

package/src/asset-paths.ts

@@ -44,6 +44,27 @@ export function sidecarAssetPath(specifier: string): string {
   return `${SIDECAR_ASSET_DIR}${base}.js`;
 }
 
+/**
+ * Map a bare npm specifier naming a **file** — a stylesheet, a font, a prebuilt script — to the URL
+ * the build copies it to.
+ *
+ * Unlike {@link sidecarAssetPath} this keeps the extension, because the file is copied rather than
+ * bundled and both the browser and the host dispatch on it.
+ *
+ * @docs framework/site/seo
+ */
+export function npmAssetPath(specifier: string): string {
+  const ext = /\.(\w+)$/.exec(specifier)?.[1] ?? "";
+  const base = specifier
+    .replace(/\.\w+$/, "")
+    .replaceAll("@", "")
+    .replaceAll(/[/\\]+/g, "-")
+    .replaceAll(/[^\w.-]/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "");
+  return ext === "" ? `${SIDECAR_ASSET_DIR}${base}` : `${SIDECAR_ASSET_DIR}${base}.${ext}`;
+}
+
 // ─── Asset mounts (specs/extensions.md §8.5) ─────────────────────────────────
 
 /**

package/src/extension-registry.ts

@@ -156,6 +156,18 @@ export class ExtensionRegistry {
     return this.#classes.filter((e) => e.capabilities.emit !== undefined);
   }
 
+  /**
+   * Classes declaring a `head` capability (§8.6), in declaration order.
+   *
+   * Separate from `emit` because the two answer different questions at different times: `emit`
+   * derives files from loaded content and runs long after every page was written, while `head`
+   * derives `<head>` entries from CONFIGURATION and must run before the first page is built. A feed
+   * needs both — the file from `emit`, the `<link rel="alternate">` from here.
+   */
+  headProviders(): FormatEntry[] {
+    return this.#classes.filter((e) => e.capabilities.head !== undefined);
+  }
+
   /** Classes declaring an `assets` capability (static asset mounts, §8.5), in declaration order. */
   assetProviders(): FormatEntry[] {
     return this.#classes.filter((e) => e.capabilities.assets !== undefined);

package/src/format-registry.ts

@@ -10,6 +10,8 @@
  * (fetch + dynamic import) hosts.
  */
 
+import { mediaTypeEssence, mediaTypeProblem } from "./media-type";
+
 export type FormatCapability = "parse" | "serialize" | "discover" | "load";
 
 export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
@@ -22,8 +24,9 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
 /**
  * All well-known static capability roles across admission blocks (specs/extensions.md §8): format
  * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), build-time
- * asset emission (`emit`), static asset mounts (`assets`), server-mount (`mount`), and connector
- * (`dialect`, `deploySchema`, `bindings`, `testConnection`) roles.
+ * asset emission (`emit`), `<head>` contribution (`head`), static asset mounts (`assets`),
+ * server-mount (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`)
+ * roles.
  */
 export type ExtensionCapability =
   | FormatCapability
@@ -31,6 +34,7 @@ export type ExtensionCapability =
   | "resolvePaths"
   | "lower"
   | "emit"
+  | "head"
   | "assets"
   | "mount"
   | "dialect"
@@ -44,6 +48,7 @@ export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
   "resolvePaths",
   "lower",
   "emit",
+  "head",
   "assets",
   "mount",
   "dialect",
@@ -160,6 +165,15 @@ export class FormatEntry {
   readonly classDef: ClassDefLike;
   readonly extensions: string[];
   readonly mediaType: string | null;
+  /**
+   * The media type without its parameters — `text/markdown` for `text/markdown; variant=GFM`.
+   *
+   * Anything that keys on a type rather than describing one wants this: a File System Access
+   * `accept` map, an editor language id. Those broke the moment a format declared the `variant`
+   * parameter RFC 7763 defines, which is a good reason for the distinction to exist in the type
+   * rather than in each caller's split.
+   */
+  readonly mediaTypeEssence: string | null;
   readonly documentKinds: FormatDocumentKind[];
   readonly exportTarget: boolean;
   readonly remote: boolean;
@@ -183,6 +197,7 @@ export class FormatEntry {
     const { format } = classDef;
     this.extensions = (format?.extensions ?? []).map((e) => e.toLowerCase());
     this.mediaType = format?.mediaType ?? null;
+    this.mediaTypeEssence = mediaTypeEssence(this.mediaType);
     this.documentKinds = format?.documentKinds ?? [];
     this.exportTarget = format?.exportTarget === true;
     this.remote = format?.remote === true;
@@ -234,6 +249,21 @@ export class FormatRegistry {
   constructor(entries: FormatEntry[]) {
     this.#entries = entries;
 
+    /*
+     * A declared media type reaches an HTTP header, an editor's file association and a Studio
+     * label. Nothing checked it before, so `text/markdown;variant GFM` — one missing `=` — would
+     * have been served to a browser verbatim as a malformed header value (RFC 6838 §4.2).
+     */
+    for (const entry of entries) {
+      if (entry.mediaType === null) {
+        continue;
+      }
+      const problem = mediaTypeProblem(entry.mediaType);
+      if (problem !== null) {
+        throw new Error(`Format "${entry.name}" declares an invalid mediaType: ${problem}`);
+      }
+    }
+
     // Ambiguous (extension, capability) claims are a configuration error.
     for (const cap of FORMAT_CAPABILITIES) {
       const seen = new Map<string, FormatEntry>();

package/src/guards.ts

@@ -19,9 +19,10 @@ import type {
   JxPrototypeDef,
   JxRef,
   JxServerFnDef,
-  JxStatement,
   JxStateObject,
+  JxStatement,
   JxStyle,
+  JxTagExpression,
 } from "../types";
 
 // ─── JSON shape guards ──────────────────────────────────────────────────────────
@@ -241,3 +242,63 @@ export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
   }
   return parameters.map((p) => (typeof p === "string" ? p : p.name));
 }
+
+/** Whether an element's `tagName` is a choice rather than a name. */
+export function isTagExpression(tagName: unknown): tagName is { $expression: JxTagExpression } {
+  return isJsonObject(tagName) && isJsonObject(tagName.$expression);
+}
+
+/**
+ * Every tag an element could be, without evaluating anything.
+ *
+ * ONE implementation, shared by the runtime, the three compiler targets and the studio, because
+ * four surfaces each writing their own enumeration is four chances to disagree about what an
+ * element can be — and disagreeing about that is how the `${…}` tagName shipped a page whose SSR
+ * markup and client render used different elements.
+ *
+ * A plain name yields itself, so every caller can treat the two forms alike.
+ */
+export function tagNameCandidates(tagName: unknown): string[] {
+  if (typeof tagName === "string") {
+    return [tagName];
+  }
+  if (!isTagExpression(tagName)) {
+    return [];
+  }
+  const expression = tagName.$expression;
+  if (expression.operator === "?:") {
+    return [...new Set([expression.value, expression.initial])];
+  }
+  return [...new Set([...Object.values(expression.cases), expression.default])];
+}
+
+/**
+ * The tag to show a human when the element could be several.
+ *
+ * The Outline draws one row per node and needs a label that is stable, short and honest: `a|div`
+ * says "this is one element whose tag is chosen" without pretending to know which. Rendering the
+ * first candidate would have been a quieter lie.
+ */
+export function displayTagName(tagName: unknown): string {
+  return typeof tagName === "string" ? tagName : tagNameCandidates(tagName).join("|");
+}
+
+/**
+ * Whether a `state` key is private (`spec.md` §5.6).
+ *
+ * A `#`-prefixed entry is ordinary state in every respect but one: it is not part of the
+ * component's interface. It never reaches the studio property panel, never appears in an exported
+ * CEM manifest, and is never settable through `$props` — which is the clause that needs a predicate
+ * rather than a convention, because the props paths are spread across two tiers.
+ *
+ * The rule lived inline at three call sites before it lived here, spelled `key.startsWith("#")`
+ * each time. That is survivable for two and a drift risk at four, and the interesting direction of
+ * drift is silent: a path that forgets the check does not fail, it just quietly makes a private
+ * entry writable from outside.
+ *
+ * @param {string} key - A `state` key
+ * @returns {boolean}
+ */
+export function isPrivateStateKey(key: string): boolean {
+  return key.startsWith("#");
+}