@jxsuite/schema 1.5.0 → 1.8.1

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/component-meta.ts

@@ -0,0 +1,143 @@
+/**
+ * Component metadata, derived from a parsed component document.
+ *
+ * Discovery — "what components does this project have, and what props do they take" — is a pure
+ * function of the document. It reads `tagName`, `state` and any `<slot>` in the tree; it executes
+ * nothing. That distinction is what lets a backend with a no-project-JS posture discover JSON
+ * components safely, which Jx Cloud could not do while this logic lived inside two Bun servers.
+ *
+ * It lives here because THREE backends need the same answer and two of them had already written it
+ * twice: `packages/server/src/studio-api.ts` (the dev server's `/__studio/components`) and
+ * `packages/desktop/src/project-session.ts`. A third copy in the cloud adapter would have made
+ * "which entries in `state` count as props" a question with three answers.
+ *
+ * @license MIT
+ */
+
+import type { JsonValue } from "../types";
+
+/** One `<slot>` found in a component's tree. */
+export interface ComponentSlotDef {
+  /** The slot's name; `""` for the unnamed slot. */
+  name: string;
+  /** Fallback children rendered when nothing is slotted in. */
+  fallback?: unknown[];
+}
+
+/** One editable prop, derived from a `state` entry. */
+export interface ComponentPropDef {
+  name: string;
+  type?: unknown;
+  default?: JsonValue;
+  format?: unknown;
+}
+
+/** What discovery reports for one component document. */
+export interface ComponentMetaOut {
+  tagName: string;
+  $id: string | null;
+  path: string;
+  props: ComponentPropDef[];
+  slots?: ComponentSlotDef[];
+  hasElements: boolean;
+}
+
+/**
+ * Collect slot definitions from a parsed component tree.
+ *
+ * Whitespace-only names count as unnamed (`""`), and only static `children` arrays are walked — a
+ * slot produced by a `$map` or a `$switch` has no fixed identity to report.
+ *
+ * @param {unknown} node - A node of the component document.
+ * @param {ComponentSlotDef[]} [out] - Accumulator, for the recursive walk.
+ * @returns {ComponentSlotDef[]}
+ */
+export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): ComponentSlotDef[] {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return out;
+  }
+  const el = node as Record<string, unknown>;
+  if (el.tagName === "slot") {
+    const attrs = el.attributes as Record<string, unknown> | undefined;
+    const rawName = attrs?.name;
+    const name = typeof rawName === "string" ? rawName.trim() : "";
+    const { children } = el;
+    out.push({
+      name,
+      ...(Array.isArray(children) && children.length > 0 ? { fallback: children } : {}),
+    });
+  }
+  if (Array.isArray(el.children)) {
+    for (const c of el.children) {
+      collectSlotDefs(c, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether a `state` entry is an editable prop.
+ *
+ * The shorthand form (`"title": "Hello"`) always is. The full form is one only when it is plain
+ * data: a computed value, a handler or a prototype entry is machinery the author does not type
+ * into, and offering it as a prop would put a text box in front of a function.
+ *
+ * @param {unknown} def - The `state` entry.
+ * @returns {boolean}
+ */
+function isPropEntry(def: unknown): boolean {
+  if (def == null) {
+    return false;
+  }
+  if (typeof def !== "object") {
+    return true;
+  }
+  const obj = def as Record<string, unknown>;
+  return !obj.$prototype && !obj.$handler && !obj.$compute;
+}
+
+/**
+ * Metadata for one component document, or null when the document is not a component.
+ *
+ * A component is a document whose `tagName` is a valid custom-element name — it must contain a
+ * hyphen. That single test is what keeps a page or a data file from being reported as a component
+ * when a whole project tree is scanned.
+ *
+ * @param {unknown} doc - The parsed document.
+ * @param {string} path - Project-relative path, reported verbatim.
+ * @returns {ComponentMetaOut | null}
+ */
+export function componentMetaFrom(doc: unknown, path: string): ComponentMetaOut | null {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return null;
+  }
+  const content = doc as Record<string, unknown>;
+  const { tagName } = content;
+  if (typeof tagName !== "string" || !tagName.includes("-")) {
+    return null;
+  }
+  const slots = collectSlotDefs(content);
+  const state = (content.state ?? {}) as Record<string, unknown>;
+  return {
+    $id: typeof content.$id === "string" && content.$id ? content.$id : null,
+    hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
+    path,
+    props: Object.entries(state)
+      .filter(([, def]) => isPropEntry(def))
+      .map(([name, def]) => {
+        if (typeof def !== "object" || def === null) {
+          // Shorthand: the value IS the default, and its runtime type is the only type on offer.
+          return { default: def as JsonValue, name, type: typeof def };
+        }
+        const obj = def as Record<string, unknown>;
+        return {
+          default: obj.default as JsonValue,
+          format: obj.format,
+          name,
+          type: obj.type,
+        };
+      }),
+    ...(slots.length > 0 ? { slots } : {}),
+    tagName,
+  };
+}

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);