@jxsuite/schema 1.8.1 → 2.0.0

package/README.md

@@ -44,12 +44,12 @@ const valid = await validateDocument(doc); // validate a Jx document
 
 ## Component schema coverage
 
-- **`tagName`** — all standard HTML element names from `@webref/elements`
-- **Element properties** — all DOM IDL properties from `@webref/idl`
-- **`style`** — all CSSOM camelCase properties from `@webref/css`
-- **Event handlers** — all `EventHandler` names (`onclick`, `oninput`, …)
-- **`state` shapes** — naked value, typed value, computed, function, external class
-- **Built-in `$prototype` values** — `Request`, `LocalStorage`, `SessionStorage`, `Cookie`, `IndexedDB`, `Array`, `Set`, `Map`, `Blob`, `ReadableStream`, `URLSearchParams`, `FormData`
+- **`tagName`**: all standard HTML element names from `@webref/elements`
+- **Element properties**: all DOM IDL properties from `@webref/idl`
+- **`style`**: all CSSOM camelCase properties from `@webref/css`
+- **Event handlers**: all `EventHandler` names (`onclick`, `oninput`, …)
+- **`state` shapes**: naked value, typed value, computed, function, external class
+- **Built-in `$prototype` values**: `Request`, `LocalStorage`, `SessionStorage`, `Cookie`, `IndexedDB`, `Array`, `Set`, `Map`, `Blob`, `ReadableStream`, `URLSearchParams`, `FormData`
 
 ## VSCode / editor integration
 

package/defs/function-def.schema.ts

@@ -9,6 +9,13 @@ export const functionDefSchema = {
       description: "Named export in $src module. Defaults to the state key name.",
       type: "string",
     },
+    $lazy: {
+      description:
+        "Load $src on first call instead of importing it up front. The function then returns a " +
+        "promise, so it may only be called from a handler or lifecycle hook — never bound as a " +
+        "computed value. Use it for code most visitors never reach.",
+      type: "boolean",
+    },
     $prototype: { const: "Function", type: "string" },
     $src: {
       description: "External module specifier. Mutually exclusive with body.",

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.2",
-    "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.2",
+    "@webref/css": "^8.7.3",
+    "@webref/elements": "^2.8.0",
+    "@webref/idl": "^3.83.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -52,10 +52,10 @@
     "schema": "bun run src/schema.ts",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "type": "module",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -211,6 +211,10 @@
           "description": "Named export in $src module. Defaults to the state key name.",
           "type": "string"
         },
+        "$lazy": {
+          "description": "Load $src on first call instead of importing it up front. The function then returns a promise, so it may only be called from a handler or lifecycle hook — never bound as a computed value. Use it for code most visitors never reach.",
+          "type": "boolean"
+        },
         "$prototype": {
           "const": "Function",
           "type": "string"
@@ -2565,6 +2569,20 @@
             }
           ]
         },
+        "onconfigurationchange": {
+          "description": "Event handler for the \"configurationchange\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "onconnect": {
           "description": "Event handler for the \"connect\" event.",
           "oneOf": [
@@ -5421,6 +5439,20 @@
             }
           ]
         },
+        "onstream": {
+          "description": "Event handler for the \"stream\" event.",
+          "oneOf": [
+            {
+              "$ref": "#/$defs/RefObject"
+            },
+            {
+              "$ref": "#/$defs/ExpressionEntry"
+            },
+            {
+              "$ref": "#/$defs/FunctionDef"
+            }
+          ]
+        },
         "onsubmit": {
           "description": "Event handler for the \"submit\" event.",
           "oneOf": [
@@ -22776,6 +22808,7 @@
         "body",
         "br",
         "button",
+        "camera",
         "canvas",
         "caption",
         "circle",
@@ -22872,6 +22905,7 @@
         "meter",
         "mfrac",
         "mi",
+        "microphone",
         "mmultiscripts",
         "mn",
         "mo",
@@ -22960,6 +22994,7 @@
         "u",
         "ul",
         "use",
+        "usermedia",
         "var",
         "video",
         "view",

package/src/asset-paths.ts

@@ -196,3 +196,345 @@ export function collectAssetUrls(text: string, mounts: readonly AssetMount[]): s
   }
   return [...found].filter(Boolean);
 }
+
+// ─── Project paths ↔ site URLs (specs/site-architecture.md §9.3) ─────────────
+
+/**
+ * The project directory whose contents publish at the site root.
+ *
+ * A convention rather than a setting: `public/logo.png` is `/logo.png` on the built site, which is
+ * why an authored `/logo.png` names a file the project tree calls something else.
+ */
+export const PUBLIC_DIR = "public";
+
+/** Node keys whose value is a media reference. Mirrors `ASSET_KEYS` in the content loader. */
+export const ASSET_KEYS = ["src", "poster"] as const;
+
+/**
+ * One step in a host's resolution order for a site-absolute URL.
+ *
+ * - `"mounts"` — an extension asset mount publishes a directory at a URL prefix (extensions.md §8.5).
+ * - `"root"` — the URL path is a project-relative path as written.
+ * - `"public"` — the URL path is relative to {@link PUBLIC_DIR}.
+ */
+export type AssetLane = "mounts" | "root" | "public";
+
+/**
+ * What a BUILD resolves — mounts, then `public/`, and nothing else.
+ *
+ * This is the published contract (site-architecture.md §9.3): a file at `<root>/hero.jpg` is not
+ * addressable at `/hero.jpg` on a deployed site, because nothing copies it there.
+ */
+export const BUILD_LANES: readonly AssetLane[] = ["mounts", "public"];
+
+/**
+ * What the editing servers resolve — mounts, then the project root, then `public/`.
+ *
+ * It is deliberately NOT {@link BUILD_LANES}, and the difference is a real one rather than an
+ * implementation detail: `serveProjectFile` in `@jxsuite/server` tries the project root BEFORE
+ * `public/`, so `<root>/hero.jpg` loads at `/hero.jpg` in a preview and 404s in production. A test
+ * asserts the two constants differ, so nobody can quietly assume they agree.
+ */
+export const DEV_SERVER_LANES: readonly AssetLane[] = ["mounts", "root", "public"];
+
+/**
+ * Split a reference into the path part and the `?query#hash` suffix.
+ *
+ * The suffix must survive every rewrite untouched: `./hero.png?v=2` is one file plus a
+ * cache-buster, and a rewrite that drops the buster changes what the browser requests.
+ *
+ * @param {string} value - An authored reference
+ * @returns {{ path: string; suffix: string }} The bare path and everything from the first `?`/`#`
+ */
+export function splitRefSuffix(value: string): { path: string; suffix: string } {
+  const cut = value.search(/[#?]/);
+  return cut === -1
+    ? { path: value, suffix: "" }
+    : { path: value.slice(0, cut), suffix: value.slice(cut) };
+}
+
+/**
+ * True when `value` is already a URL, a template, a fragment, or empty — never a project file.
+ *
+ * Mirrors `isNonRelativeRef` in the content loader. A root-relative `/hero.jpg` counts as
+ * non-relative here because it is a SITE URL, not a path relative to the document.
+ *
+ * @param {string} value - An authored reference
+ * @returns {boolean}
+ */
+export function isNonRelativeRef(value: string): boolean {
+  return (
+    value === "" ||
+    value.startsWith("/") ||
+    value.startsWith("#") ||
+    value.includes("${") ||
+    /^[a-z][\w+.-]*:/i.test(value)
+  );
+}
+
+/**
+ * Normalize a project-relative path: forward slashes, no `./` prefix, no leading or trailing slash.
+ *
+ * @param {string} path - A project-relative path in any spelling
+ * @returns {string} The canonical spelling
+ */
+export function normalizeProjectPath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+/** The directory portion of a project-relative path (`""` for a root-level file). */
+export function dirOfPath(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  const slash = normalized.lastIndexOf("/");
+  return slash === -1 ? "" : normalized.slice(0, slash);
+}
+
+/**
+ * Resolve `ref` against `dir` in a pure, POSIX-ish way — no `node:path`, and no leading-slash
+ * assumption, because project paths are relative to a root the browser does not have.
+ *
+ * @param {string} dir - Project-relative directory (`""` for the root)
+ * @param {string} ref - A relative reference
+ * @returns {string | null} The project-relative result, or null when it climbs above the root
+ */
+export function joinProjectPath(dir: string, ref: string): string | null {
+  const base = dir === "" || dir === "." ? [] : normalizeProjectPath(dir).split("/");
+  const out = base.filter((segment) => segment !== "" && segment !== ".");
+  for (const segment of ref.replaceAll("\\", "/").split("/")) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (out.length === 0) {
+        return null; // Escapes the project root.
+      }
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join("/");
+}
+
+/**
+ * The site URL a project file publishes at under `lanes`, or null when nothing publishes it.
+ *
+ * The lanes are tried in order, so the answer is the URL the host would resolve FIRST — which is
+ * what makes {@link projectPathsForSiteUrl} its inverse. Under {@link DEV_SERVER_LANES} that means
+ * `public/logo.png` answers `/public/logo.png` (the root lane, which the server tries first) rather
+ * than `/logo.png`; both work there, and only one round-trips.
+ *
+ * @param {string} path - Project-relative path
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string | null} A site-absolute URL, or null
+ */
+export function siteUrlForPath(
+  path: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string | null {
+  const normalized = normalizeProjectPath(path);
+  if (normalized === "") {
+    return null;
+  }
+  for (const lane of lanes) {
+    if (lane === "mounts") {
+      const url = assetUrlFor(mounts, normalized);
+      if (url) {
+        return url;
+      }
+      continue;
+    }
+    if (lane === "root") {
+      return `/${encodeProjectPath(normalized)}`;
+    }
+    if (normalized === PUBLIC_DIR || normalized.startsWith(`${PUBLIC_DIR}/`)) {
+      return `/${encodeProjectPath(normalized.slice(PUBLIC_DIR.length + 1))}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Every project path a site-absolute URL could name under `lanes`, in the order the host tries
+ * them.
+ *
+ * A list rather than one answer because the lanes genuinely overlap: `/hero.jpg` is `hero.jpg` to
+ * the root lane and `public/hero.jpg` to the public lane, and only a filesystem can say which
+ * exists. Callers with no filesystem — the Studio canvas — take the first.
+ *
+ * @param {string} url - A site-absolute URL (query and hash are ignored)
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string[]} Candidate project-relative paths, most-preferred first
+ */
+export function projectPathsForSiteUrl(
+  url: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string[] {
+  const { path } = splitRefSuffix(url);
+  if (!path.startsWith("/")) {
+    return [];
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    return [];
+  }
+  // A still-encoded dot or slash after one decode is a traversal attempt, not a filename.
+  if (/%2e|%2f/i.test(decoded)) {
+    return [];
+  }
+  const rest = decoded.replace(/^\/+/, "");
+  if (rest === "" || rest.split("/").some((segment) => segment === "." || segment === "..")) {
+    return [];
+  }
+  const out: string[] = [];
+  for (const lane of lanes) {
+    if (lane === "mounts") {
+      const mounted = resolveAssetUrl(mounts, path);
+      // Only a mount INSIDE the project is addressable by path; `../../docs` is not.
+      if (mounted !== null && !mounted.startsWith("/") && !/^[A-Za-z]:/.test(mounted)) {
+        out.push(normalizeProjectPath(mounted));
+      }
+      continue;
+    }
+    out.push(lane === "root" ? rest : `${PUBLIC_DIR}/${rest}`);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * The project file an authored reference names, seen from the document that wrote it.
+ *
+ * The two shapes an author writes resolve differently and neither goes through a site URL:
+ *
+ * - A content-relative `./images/hero.png` resolves against the document's own directory, which IS a
+ *   project path already — `content/posts/images/hero.png`. The mount detour that the built site
+ *   performs is not needed to name the file, only to publish it.
+ * - A root-relative `/hero.jpg` is a site URL, so it resolves through {@link projectPathsForSiteUrl}
+ *   and takes the host's first lane.
+ *
+ * Everything else — an absolute URL, a `data:` URI, a `${…}` template, a bare fragment — names no
+ * project file and returns null, which callers read as "leave it exactly as written".
+ *
+ * @param {string} value - The authored reference
+ * @param {string} documentDir - Project-relative directory of the document that wrote it
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string | null} A project-relative path, or null
+ */
+export function projectPathForRef(
+  value: string,
+  documentDir: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string | null {
+  const { path } = splitRefSuffix(value);
+  if (path === "") {
+    return null;
+  }
+  if (isNonRelativeRef(value)) {
+    return path.startsWith("/") ? (projectPathsForSiteUrl(path, mounts, lanes)[0] ?? null) : null;
+  }
+  // A reference ending in a slash names a DIRECTORY, and no directory is a media file.
+  if (path.endsWith("/")) {
+    return null;
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    return null;
+  }
+  const joined = joinProjectPath(documentDir, decoded);
+  if (joined === null || joined === "" || joined === normalizeProjectPath(documentDir)) {
+    return null;
+  }
+  return joined;
+}
+
+/**
+ * Percent-encode each path segment so the result survives an HTML attribute.
+ *
+ * Segment by segment, so the separators stay separators: `encodeURIComponent` on the whole path
+ * would turn every `/` into `%2F` and produce one very long filename.
+ *
+ * @param {string} path - A project-relative path
+ * @returns {string} The same path, each segment encoded
+ */
+export function encodeProjectPath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+// ─── srcset ──────────────────────────────────────────────────────────────────
+
+/** One `srcset` candidate: a URL and the descriptor that selects it (`""` when there is none). */
+export interface SrcsetCandidate {
+  url: string;
+  descriptor: string;
+}
+
+/**
+ * Parse a `srcset` attribute into its candidates.
+ *
+ * Splitting on `","` is wrong and quietly so: a `data:` URL contains commas, and so does any URL
+ * with a query list. This follows HTML's own algorithm instead — collect non-whitespace as the URL,
+ * and if it ends in commas, the descriptor is empty and the next candidate starts immediately.
+ *
+ * @param {string} value - The attribute value
+ * @returns {SrcsetCandidate[]} Candidates in source order
+ */
+export function parseSrcset(value: string): SrcsetCandidate[] {
+  const out: SrcsetCandidate[] = [];
+  let i = 0;
+  while (i < value.length) {
+    while (i < value.length && (/\s/.test(value[i]!) || value[i] === ",")) {
+      i += 1;
+    }
+    if (i >= value.length) {
+      break;
+    }
+    const start = i;
+    while (i < value.length && !/\s/.test(value[i]!)) {
+      i += 1;
+    }
+    let url = value.slice(start, i);
+    if (url.endsWith(",")) {
+      out.push({ descriptor: "", url: url.replace(/,+$/, "") });
+      continue;
+    }
+    while (i < value.length && /\s/.test(value[i]!)) {
+      i += 1;
+    }
+    const descStart = i;
+    while (i < value.length && value[i] !== ",") {
+      i += 1;
+    }
+    const descriptor = value.slice(descStart, i).trim();
+    i += 1; // Consume the separating comma.
+    url = url.replace(/,+$/, "");
+    if (url !== "") {
+      out.push({ descriptor, url });
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize candidates back into a `srcset` attribute value.
+ *
+ * @param {readonly SrcsetCandidate[]} candidates
+ * @returns {string} The attribute value
+ */
+export function formatSrcset(candidates: readonly SrcsetCandidate[]): string {
+  return candidates
+    .map(({ url, descriptor }) => (descriptor ? `${url} ${descriptor}` : url))
+    .join(", ");
+}

package/src/locale.ts

@@ -427,3 +427,27 @@ export function primaryLanguage(tag: unknown): string | null {
   const canonical = canonicalizeLocale(tag);
   return canonical === null ? null : (canonical.split("-")[0] ?? null);
 }
+
+/**
+ * The locale a URL belongs to.
+ *
+ * Matching is on the **first path segment**, compared canonically, so `/fr-CA/about/` resolves for
+ * a project that declared `fr-ca`. A path under no declared locale is the default locale — under
+ * `prefix-except-default` that is the point, and under `prefix-always` it is a page the author put
+ * outside the locale tree, which is theirs to place.
+ *
+ * @param {string} urlPattern - Site-absolute route pattern, e.g. `/fr/about/`
+ * @param {ResolvedI18n | null} i18n
+ * @returns {string | null} A canonical tag, or null when the project has no i18n
+ */
+export function localeOfRoute(urlPattern: string, i18n: ResolvedI18n | null): string | null {
+  if (i18n === null) {
+    return null;
+  }
+  const first = urlPattern.split("/").find(Boolean);
+  if (first === undefined) {
+    return i18n.defaultLocale;
+  }
+  const canonical = canonicalizeLocale(first);
+  return canonical !== null && i18n.locales.includes(canonical) ? canonical : i18n.defaultLocale;
+}

package/types.ts

@@ -171,6 +171,13 @@ export interface JxFunctionDef {
   $src?: string;
   /** Named export within `$src`; defaults to the state key. */
   $export?: string;
+  /**
+   * Load `$src` on first call rather than importing it with the module.
+   *
+   * The function returns a promise once lazy, so it may only be called — never bound as a computed
+   * value. Meant for code most visitors never reach.
+   */
+  $lazy?: boolean;
   /** Legacy alias for `parameters` (bare names only). */
   arguments?: string[];
   timing?: "compiler" | "server" | "client";
@@ -648,6 +655,13 @@ export interface ProjectConfig {
     deploy?: DeployConfig;
     sitemap?: boolean;
     headers?: HeadersConfig;
+    /**
+     * Minify emitted browser JavaScript. Defaults to true.
+     *
+     * Set false to ship readable bundles — debugging a deployed page, or diffing `dist/` where the
+     * two bundler backends agree on semantics but not on minified bytes.
+     */
+    minify?: boolean;
     [key: string]: unknown;
   };
   images?: ImageConfig;