@jxsuite/schema 1.4.0 → 1.8.0

package/src/parse.ts

@@ -4,10 +4,20 @@
  * Raw `JSON.parse()` returns `any`, which silently disables checking for everything downstream.
  * These helpers are the single sanctioned crossing point: they parse, structurally verify, and
  * return the domain type — failures carry the source path.
+ *
+ * Being the single crossing point is also what makes it the right place to enforce I-JSON (RFC
+ * 7493). `JSON.parse` accepts documents that mean something other than what they say — a repeated
+ * key whose first value it discards, an integer it rounds — and a Jx document does not stay JSON:
+ * it round-trips through markdown frontmatter and a CRDT, each rebuilding the object from the
+ * parsed value. Whatever was dropped here is dropped for good.
+ *
+ * It is also where identifiers are normalized (UAX #31 §R4), for the same reason: a name that means
+ * one thing on one keyboard and another thing on another is a defect nothing downstream can see.
  */
 
 import type { JxClassDef, JxDocument, ProjectConfig } from "../types";
 import { isJsonObject } from "./guards";
+import { describeIJsonProblem, findIJsonProblems } from "./ijson";
 
 // ─── Error helpers ──────────────────────────────────────────────────────────────
 
@@ -21,6 +31,63 @@ export function toError(e: unknown): Error {
   return e instanceof Error ? e : new Error(String(e));
 }
 
+// ─── Unicode normalization ──────────────────────────────────────────────────────
+
+/**
+ * Text outside ASCII, which is the only text whose normalization form can differ. Testing for it
+ * first keeps this walk close to free on the pure-ASCII documents that are almost all of them.
+ */
+const NON_ASCII = /[^\p{ASCII}]/u;
+
+/**
+ * Recursively put every key and every string value into Normalization Form C.
+ *
+ * **The defect this fixes.** A state name is an identifier: `"état"` declared in `state`,
+ * referenced as `${state.état}` in a template and as `#/state/état` in a `$ref`. Typed on macOS it
+ * arrives decomposed (`e` + U+0301); typed on Windows or pasted from most of the web it arrives
+ * precomposed (U+00E9). Those are two different JavaScript property names, so a document whose
+ * declaration and reference were typed on different machines builds cleanly, emits a valid bundle,
+ * and renders nothing — `state.état` is simply `undefined`. There is no error to see and no symptom
+ * to search for. UAX #31 §R4 exists for exactly this, and NFC is the form the web platform assumes
+ * everywhere else.
+ *
+ * **Why values are normalized too, and why that is not a content change.** Two canonically
+ * equivalent strings are, by the definition in UAX #15, the same text: a conforming renderer must
+ * display them identically, and no process may distinguish them. So normalizing a `textContent` is
+ * a no-op for meaning. It is also unavoidable, because Jx has no syntactic boundary between content
+ * and code — `"Café ${state.été}"` is one string carrying both, and normalizing only "identifier
+ * positions" would mean parsing every template to find them.
+ *
+ * **Why here and not on the source text.** `"état"` is pure ASCII until `JSON.parse` turns the
+ * escape into a combining mark, so normalizing the raw text would miss exactly the documents a
+ * generator wrote.
+ *
+ * @param {unknown} value - Any parsed JSON value
+ * @returns {unknown} The same shape, with all text in NFC
+ */
+function normalizeIdentifiers(value: unknown): unknown {
+  if (typeof value === "string") {
+    return NON_ASCII.test(value) ? value.normalize("NFC") : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeIdentifiers(item));
+  }
+  if (isJsonObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      /*
+       * A later key wins on collision, matching what `JSON.parse` does with a literal duplicate.
+       * It cannot happen through this boundary — I-JSON already rejected duplicate keys, and two
+       * keys differing only by normalization form are not duplicates to `JSON.parse` — so this is
+       * a statement about which is authoritative rather than a branch anything reaches.
+       */
+      out[NON_ASCII.test(key) ? key.normalize("NFC") : key] = normalizeIdentifiers(entry);
+    }
+    return out;
+  }
+  return value;
+}
+
 // ─── Parse helpers ──────────────────────────────────────────────────────────────
 
 function parseObject(text: string, sourcePath: string, what: string): Record<string, unknown> {
@@ -35,7 +102,17 @@ function parseObject(text: string, sourcePath: string, what: string): Record<str
   if (!isJsonObject(parsed)) {
     throw new Error(`Invalid ${what} at ${sourcePath}: expected a JSON object`);
   }
-  return parsed;
+  /*
+   * An error rather than a warning, because both problems are silent data loss and neither has a
+   * reading under which the author got what they wrote. The whole repository — 375 documents —
+   * was already clean when this landed, so this rejects mistakes rather than existing work.
+   */
+  const problems = findIJsonProblems(text);
+  if (problems.length > 0) {
+    const described = problems.map((problem) => describeIJsonProblem(problem)).join("; ");
+    throw new Error(`Invalid ${what} at ${sourcePath}: ${described}`);
+  }
+  return normalizeIdentifiers(parsed) as Record<string, unknown>;
 }
 
 /** Parse a Jx document (.json page/layout/component source). */

package/src/project-schemas.ts

@@ -18,7 +18,11 @@
  * relative refs resolve (the committed files stay machine-path-free).
  */
 
-import { DOCUMENT_PATHS_SCHEMA_ID, PROJECT_FIELDS_SCHEMA_ID } from "../defs/field-schema.schema";
+import {
+  DOCUMENT_PATHS_SCHEMA_ID,
+  PROJECT_FIELDS_SCHEMA_ID,
+  documentPathsCoreMembers,
+} from "../defs/field-schema.schema";
 
 export { DOCUMENT_PATHS_SCHEMA_ID, PROJECT_FIELDS_SCHEMA_ID } from "../defs/field-schema.schema";
 
@@ -83,6 +87,9 @@ export type SchemaJsonLoader = (path: string) => Promise<Record<string, unknown>
  * @param {Record<string, unknown>} entry - The entry document (e.g. a parsed project.schema.json)
  * @param {SchemaJsonLoader} loadJson - Loader for `$ref` target files (host-restricted)
  * @param {string} baseDir - Directory the entry document's relative refs resolve against
+ * @param {string[]} [alsoEmbed] - Relative paths of resources to embed even though no path-`$ref`
+ *   reaches them, because they are referenced only by canonical `$id` (a document fragment whose
+ *   `$defs` feed the paths union). Without this they would stay dangling.
  * @returns {Promise<Record<string, unknown>>} A new, self-contained schema (the input is not
  *   mutated)
  */
@@ -90,6 +97,7 @@ export async function bundleSchema(
   entry: Record<string, unknown>,
   loadJson: SchemaJsonLoader,
   baseDir: string,
+  alsoEmbed: string[] = [],
 ): Promise<Record<string, unknown>> {
   const bundled = structuredClone(entry);
   const embeddedByPath = new Map<string, string>();
@@ -167,9 +175,220 @@ export async function bundleSchema(
   };
 
   await rewrite(bundled, normalizeSchemaPath(baseDir), true);
+  for (const path of alsoEmbed) {
+    await embed(`${normalizeSchemaPath(baseDir)}/${path}`);
+  }
   return bundled;
 }
 
+// ─── Single-resource flattening (specs/extensions.md §5.4) ───────────────────
+
+/**
+ * Keywords whose value is a single subschema (or, for draft-07 tuple `items`, an array of them).
+ * The flattener walks ONLY these keyword positions, never every object key: `examples`, `default`,
+ * `const` and `enum` hold arbitrary instance data, and Jx document examples legitimately contain
+ * `$ref` strings (`#/state/cart`) that must survive untouched.
+ */
+const SINGLE_SUBSCHEMA_KEYWORDS = [
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+] as const;
+
+/** Keywords whose value maps names to subschemas. */
+const MAP_SUBSCHEMA_KEYWORDS = [
+  "$defs",
+  "definitions",
+  "dependencies",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+] as const;
+
+/** Keywords whose value is an array of subschemas. */
+const LIST_SUBSCHEMA_KEYWORDS = ["allOf", "anyOf", "oneOf", "prefixItems"] as const;
+
+/** True for a plain object node (a candidate subschema); booleans and arrays are not. */
+function isSchemaObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Escape a `$defs` key for use as a JSON Pointer segment (RFC 6901). */
+function escapePointerSegment(segment: string): string {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+/**
+ * Walk the known subschema keyword positions of `node`.
+ *
+ * @param {Record<string, unknown>} node - The schema object to walk
+ * @param {string} pointer - JSON Pointer of `node` within the document
+ * @yields {[Record<string, unknown>, string]} Each subschema paired with its own JSON Pointer
+ */
+function* subschemaEntries(
+  node: Record<string, unknown>,
+  pointer: string,
+): Generator<[Record<string, unknown>, string]> {
+  for (const keyword of SINGLE_SUBSCHEMA_KEYWORDS) {
+    const value = node[keyword];
+    if (Array.isArray(value)) {
+      for (const [index, item] of value.entries()) {
+        if (isSchemaObject(item)) {
+          yield [item, `${pointer}/${keyword}/${index}`];
+        }
+      }
+    } else if (isSchemaObject(value)) {
+      yield [value, `${pointer}/${keyword}`];
+    }
+  }
+  for (const keyword of MAP_SUBSCHEMA_KEYWORDS) {
+    const value = node[keyword];
+    if (!isSchemaObject(value)) {
+      continue;
+    }
+    for (const [name, item] of Object.entries(value)) {
+      if (isSchemaObject(item)) {
+        yield [item, `${pointer}/${keyword}/${escapePointerSegment(name)}`];
+      }
+    }
+  }
+  for (const keyword of LIST_SUBSCHEMA_KEYWORDS) {
+    const value = node[keyword];
+    if (!Array.isArray(value)) {
+      continue;
+    }
+    for (const [index, item] of value.entries()) {
+      if (isSchemaObject(item)) {
+        yield [item, `${pointer}/${keyword}/${index}`];
+      }
+    }
+  }
+}
+
+/**
+ * A readable, collision-free `$defs` key for an embedded resource's `$id`: drop the scheme, the
+ * authority, and the conventional `schema/` namespace segment, then join the remainder with dashes
+ * (`https://jxsuite.com/schema/project/core/v2` → `project-core-v2`, `urn:jx:bundled:1` →
+ * `jx-bundled-1`). Collisions get a numeric suffix, so output stays deterministic given the
+ * emitters' stable `$defs` order.
+ *
+ * @param {string} id - The resource's canonical `$id`
+ * @param {Set<string>} used - Keys already taken in the target `$defs` (mutated)
+ * @returns {string}
+ */
+function slugForSchemaId(id: string, used: Set<string>): string {
+  let rest = id.replace(/^[a-zA-Z][a-zA-Z\d+.-]*:/, "");
+  if (rest.startsWith("//")) {
+    const slash = rest.indexOf("/", 2);
+    rest = slash === -1 ? "" : rest.slice(slash + 1);
+  }
+  rest = rest.replace(/^schema\//, "");
+  const base =
+    rest
+      .split(/[^a-zA-Z0-9]+/)
+      .filter(Boolean)
+      .join("-") || "resource";
+  let key = base;
+  for (let n = 2; used.has(key); n += 1) {
+    key = `${base}-${n}`;
+  }
+  used.add(key);
+  return key;
+}
+
+/**
+ * Collapse a bundled compound document into a SINGLE schema resource: embedded resources are
+ * rekeyed from their canonical `$id`s to readable `$defs` slugs, their `$id`s are dropped, and
+ * every `$ref` becomes a root-relative JSON Pointer (`#/$defs/project-core-v2/$defs/StyleObject`).
+ *
+ * Why this is required rather than cosmetic: VS Code's JSON language service (and Monaco, which
+ * embeds it) implements neither half of compound-document resolution. It resolves a `#/pointer` ref
+ * against the DOCUMENT ROOT — never re-based on an enclosing `$id` — so a fragment's own
+ * `#/$defs/StyleObject` reports "can not be resolved"; and it treats any ref with a non-empty part
+ * before `#` as EXTERNAL, fetching `https://jxsuite.com/schema/...` over the network instead of
+ * matching the embedded resource, which fails offline and (when it succeeds) silently substitutes
+ * the shipped defaults for the project's effective unions. Root-pointer-only refs are the one form
+ * every consumer resolves identically — ajv, the language service, and Monaco alike.
+ *
+ * `$id` shadowing (§5.3) still decides the outcome; it is simply resolved AT FLATTEN TIME, since
+ * refs to a shadowed `$id` rewrite to the pointer of the entry document's embed.
+ *
+ * @param {Record<string, unknown>} entry - A bundled compound document (output of
+ *   {@link bundleSchema})
+ * @returns {Record<string, unknown>} A new single-resource schema (the input is not mutated)
+ */
+export function flattenSchema(entry: Record<string, unknown>): Record<string, unknown> {
+  const flat = structuredClone(entry);
+
+  // 1. Rekey URI-keyed `$defs` entries to readable slugs (pointers address them by key).
+  if (isSchemaObject(flat.$defs)) {
+    const used = new Set(Object.keys(flat.$defs).filter((key) => !hasUriScheme(key)));
+    const renamed: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(flat.$defs)) {
+      const id = isSchemaObject(value) && typeof value.$id === "string" ? value.$id : key;
+      renamed[hasUriScheme(key) ? slugForSchemaId(id, used) : key] = value;
+    }
+    flat.$defs = renamed;
+  }
+
+  // 2. Map each embedded resource's `$id` to its pointer here (first wins, as the bundler embeds).
+  const idToPointer = new Map<string, string>();
+  const scan = (node: Record<string, unknown>, pointer: string): void => {
+    const { $id } = node;
+    if (typeof $id === "string" && hasUriScheme($id) && !idToPointer.has($id)) {
+      idToPointer.set($id, pointer);
+    }
+    for (const [child, childPointer] of subschemaEntries(node, pointer)) {
+      scan(child, childPointer);
+    }
+  };
+  scan(flat, "#");
+
+  // 3. Rewrite refs against the enclosing resource, then dissolve the resource boundary.
+  const rewrite = (node: Record<string, unknown>, scope: string): void => {
+    let inner = scope;
+    const { $id } = node;
+    if (typeof $id === "string" && hasUriScheme($id)) {
+      inner = idToPointer.get($id) ?? scope;
+      if (inner !== "#") {
+        // The root keeps its identity; nested resources must not remain ref targets.
+        delete node.$id;
+      }
+    }
+    const ref = node.$ref;
+    if (typeof ref === "string") {
+      const hashIndex = ref.indexOf("#");
+      const target = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
+      const fragment = hashIndex === -1 ? "" : ref.slice(hashIndex + 1);
+      if (target === "") {
+        // A local pointer resolves against the resource it appears in, not the file.
+        if (fragment.startsWith("/")) {
+          node.$ref = `${inner}${fragment}`;
+        }
+      } else {
+        const base = idToPointer.get(target);
+        if (base !== undefined) {
+          node.$ref = fragment ? `${base}${fragment}` : base;
+        }
+      }
+    }
+    for (const [child] of subschemaEntries(node, inner)) {
+      rewrite(child, inner);
+    }
+  };
+  rewrite(flat, "#");
+  return flat;
+}
+
 /** Collect every absolute `$id` already present in a document (embeds like the field union). */
 function collectResourceIds(node: unknown, out: Set<string>): void {
   if (Array.isArray(node)) {
@@ -240,23 +459,150 @@ export interface DocumentSchemaInputs {
   pathsValueRefs: string[];
 }
 
-/** Emit the `document.schema.json` entry document for a project. */
+/**
+ * Emit the `document.schema.json` entry document for a project.
+ *
+ * The core reference goes in a single-member `allOf`, never a root-level `$ref`. They are
+ * equivalent to a compliant validator, but VS Code's JSON language service resolves a `$ref` by
+ * SHALLOW-MERGING the target's keys into the referencing node — from the root, that overwrites the
+ * root's own `$defs` with the core resource's `$defs`, and every later `#/$defs/<embed>/...`
+ * pointer stops resolving. Wrapping in `allOf` keeps the merge target off the root.
+ *
+ * @param {DocumentSchemaInputs} inputs - Core path and the contributed paths-union refs
+ * @returns {Record<string, unknown>}
+ */
 export function emitDocumentSchema(inputs: DocumentSchemaInputs): Record<string, unknown> {
   const { corePath, pathsValueRefs } = inputs;
   return {
     $comment: GENERATED_SCHEMA_COMMENT,
     $defs: {
-      // With no contributed paths shapes the embed stays permissive — core `$paths` forms
-      // (arrays, values, $ref) are validated by the core schema itself.
-      PathsValue:
-        pathsValueRefs.length > 0
-          ? {
-              $id: DOCUMENT_PATHS_SCHEMA_ID,
-              anyOf: pathsValueRefs.map((ref) => ({ $ref: ref })),
-            }
-          : { $id: DOCUMENT_PATHS_SCHEMA_ID },
+      /* The EFFECTIVE paths union: the core source shapes plus every extension-contributed one.
+         Carrying the core members here (rather than leaving them to the core schema) is what makes
+         the override additive — this embed shadows the shipped default by $id, so anything it omits
+         stops validating. Mirrors the field union in emitProjectSchema, which names its core
+         members the same way. */
+      PathsValue: {
+        $id: DOCUMENT_PATHS_SCHEMA_ID,
+        anyOf: [...documentPathsCoreMembers, ...pathsValueRefs.map((ref) => ({ $ref: ref }))],
+      },
     },
-    $ref: corePath,
     $schema: "https://json-schema.org/draft/2020-12/schema",
+    allOf: [{ $ref: corePath }],
   };
 }
+
+// ─── Composition (specs/extensions.md §5.2) ──────────────────────────────────
+
+/** Loader-resolvable refs to one extension's shipped schema fragments, as its manifest names them. */
+export interface ExtensionFragmentRefs {
+  /** Project fragment — plain `properties` for the extension's section keys. */
+  project?: string | undefined;
+  /** Document fragment — its `$defs` become `$paths` source-union members. */
+  document?: string | undefined;
+  /** Fields fragment — its `$defs` become Field-schema union members. */
+  fields?: string | undefined;
+}
+
+export interface ComposeProjectSchemasInputs {
+  /** Ref to the core project fragment (`@jxsuite/schema/schemas/project.core.schema.json`). */
+  coreProjectRef: string;
+  /** Ref to the core document schema (`@jxsuite/schema/schema.json`). */
+  coreDocumentRef: string;
+  /** Enabled extensions in registry order; each contributes the fragments it ships. */
+  extensions: ExtensionFragmentRefs[];
+  /** Loads a ref's JSON. Every ref above and every `$ref` inside resolves through this ALONE. */
+  loadJson: SchemaJsonLoader;
+  /** Directory the refs resolve against ("" for hosts addressing by bare specifier). */
+  baseDir: string;
+}
+
+/**
+ * Compose a project's two committed entry documents from the core schemas and its enabled
+ * extensions' fragments — bundled, then flattened to root JSON pointers (§5.2/§5.4).
+ *
+ * Host-agnostic by construction: every file it needs arrives through `loadJson`, so the same
+ * composition runs over a filesystem (`jx schema`) and over a virtual tree of bundled artifacts
+ * (the cloud session, which has no `node_modules` and no filesystem). That shared path is the point
+ * — a project's schemas must not depend on which host generated them.
+ *
+ * @param {ComposeProjectSchemasInputs} inputs - Core refs, extension fragments, loader, base
+ * @returns {Promise<{ project: Record<string, unknown>; document: Record<string, unknown> }>} The
+ *   self-contained entry documents, ready to write or to hand an editor
+ */
+export async function composeProjectSchemas(inputs: ComposeProjectSchemasInputs): Promise<{
+  project: Record<string, unknown>;
+  document: Record<string, unknown>;
+}> {
+  const { baseDir, coreDocumentRef, coreProjectRef, extensions, loadJson } = inputs;
+
+  const fragments: string[] = [];
+  const pathsValueRefs: string[] = [];
+  const documentFragments: string[] = [];
+  const fieldSchemaRefs: string[] = [];
+  for (const ext of extensions) {
+    if (ext.project) {
+      fragments.push(ext.project);
+    }
+    if (ext.document) {
+      const documentRefs = await fragmentDefsRefs(ext.document, loadJson, baseDir);
+      pathsValueRefs.push(...documentRefs);
+      /* The paths union names this fragment's shapes by canonical $id only, so the bundler needs
+         the path handed to it explicitly or those refs stay dangling. A fragment that contributed
+         nothing (no $id, or no $defs) is left out rather than embedded unreferenced. */
+      if (documentRefs.length > 0) {
+        documentFragments.push(ext.document);
+      }
+    }
+    // The `schemas.fields` manifest convention: a fragment whose $defs members are extension
+    // Field extras, unioned into the per-project field resource (specs/extensions.md §5.3).
+    if (ext.fields) {
+      fieldSchemaRefs.push(...(await fragmentDefsRefs(ext.fields, loadJson, baseDir)));
+      fragments.push(ext.fields);
+    }
+  }
+
+  // Bundle then flatten: the emitted relative refs are an intermediate form only.
+  const projectEntry = emitProjectSchema({ corePath: coreProjectRef, fieldSchemaRefs, fragments });
+  const documentEntry = emitDocumentSchema({ corePath: coreDocumentRef, pathsValueRefs });
+  return {
+    document: flattenSchema(
+      await bundleSchema(documentEntry, loadJson, baseDir, documentFragments),
+    ),
+    project: flattenSchema(await bundleSchema(projectEntry, loadJson, baseDir)),
+  };
+}
+
+/**
+ * Canonical "uri#/pointer" refs into a fragment's `$defs` shapes: one per `$defs` entry, addressed
+ * by the fragment's own `$id` (refs inside the entry document's embeds resolve against canonical
+ * URIs, never file paths). An `$id`-less or `$defs`-less fragment contributes no union members —
+ * that is simply the shape of a fragment declaring only `properties`.
+ *
+ * An UNREADABLE fragment contributes nothing here but still fails the composition, because the
+ * bundler goes on to embed the same ref and throws. That is deliberate: silently dropping it would
+ * emit an entry document that under-validates the project with nothing to show for it. A host that
+ * cannot supply an extension's fragments must leave that extension out of `extensions` entirely —
+ * which is exactly what the cloud session does for packages it does not bundle.
+ *
+ * @param {string} ref - Loader-resolvable ref to the fragment, relative to `baseDir`
+ * @param {SchemaJsonLoader} loadJson - The host's loader
+ * @param {string} baseDir - Directory the ref resolves against
+ * @returns {Promise<string[]>} One ref per `$defs` member, in declaration order
+ */
+async function fragmentDefsRefs(
+  ref: string,
+  loadJson: SchemaJsonLoader,
+  baseDir: string,
+): Promise<string[]> {
+  let fragment: { $id?: unknown; $defs?: Record<string, unknown> };
+  try {
+    fragment = await loadJson(normalizeSchemaPath(`${normalizeSchemaPath(baseDir)}/${ref}`));
+  } catch {
+    return [];
+  }
+  const { $id } = fragment;
+  if (typeof $id !== "string" || !fragment.$defs) {
+    return [];
+  }
+  return Object.keys(fragment.$defs).map((name) => `${$id}#/$defs/${name}`);
+}

package/src/schema.ts

@@ -26,6 +26,7 @@ import { listAll as listElements } from "@webref/elements";
 import css from "@webref/css";
 import idl from "@webref/idl";
 
+import { elementTagNameSchema, tagExpressionSchema } from "../defs/tag-expression.schema";
 import { tagNameSchema } from "../defs/tag-name.schema";
 import {
   boolOrRefSchema,
@@ -102,6 +103,8 @@ import { extensionManifestSchema } from "../defs/extension-manifest.schema";
 import {
   DOCUMENT_PATHS_SCHEMA_ID,
   PROJECT_FIELDS_SCHEMA_ID,
+  documentPathsCoreMembers,
+  documentPathsUnknownSourceMember,
   jxFieldSchemaDef,
   relationshipRefSchema,
 } from "../defs/field-schema.schema";
@@ -285,9 +288,24 @@ export async function generateSchema() {
         ...tagNameSchema,
         examples: [...tagExamples, "my-counter", "todo-app", "user-card"],
       },
+      TagExpression: tagExpressionSchema,
+      ElementTagName: elementTagNameSchema,
       JsonSchemaType: jsonSchemaTypeSchema,
       HeadEntry: headEntrySchema,
       ImageConfig: imageConfigSchema,
+      /* The shipped DEFAULT paths union, embedded under its canonical $id so `$paths`'s ref
+         resolves with this file alone (it is registered standalone as the studio's offline
+         fallback). A per-project entry document embeds the same $id carrying core members PLUS
+         extension shapes; that embed is declared first, so it wins resolution and this one is
+         inert there (extensions.md §5.3). */
+      PathsValue: {
+        $id: DOCUMENT_PATHS_SCHEMA_ID,
+        anyOf: [...documentPathsCoreMembers, documentPathsUnknownSourceMember],
+        description:
+          "Default $paths source union: the core shapes, plus a catch-all for source shapes " +
+          "contributed by extensions this schema cannot see. The project's generated " +
+          "document.schema.json replaces this with the exact set its extensions provide.",
+      },
     },
     $id: "https://jxsuite.com/schema/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -327,9 +345,16 @@ export async function generateSchema() {
       },
       $head: {
         description:
-          "Page-level <head> entries. Array of element definitions for meta tags, " +
+          "Page-level <head> entries. Array of head entries for meta tags, " +
           "link tags, script tags, etc. Merged with layout and site-level $head entries.",
-        items: { $ref: "#/$defs/ElementDef" },
+        /* `HeadEntry`, NOT `ElementDef`. These were typed as elements, which was harmless only
+           while an element's tagName was a plain name — the moment it could be chosen at creation,
+           a head tag could be too, and `head-merger.ts` splices one straight into the built page as
+           `<${tag} …>`. A head tag is static by nature (the runtime's `injectHead` builds a CSS
+           selector out of it before it ever creates anything), and `HeadEntry` already says so.
+           It had been an orphan def until now: its only inbound `$ref` was its own recursive
+           `children`. */
+        items: { $ref: "#/$defs/HeadEntry" },
         type: "array",
       },
       $id: {
@@ -337,6 +362,30 @@ export async function generateSchema() {
         examples: ["Counter", "TodoApp", "UserCard"],
         type: "string",
       },
+      $dir: {
+        description:
+          "Base direction for this page's <html> element, overriding `defaults.dir`. " +
+          "Right-to-left content renders left-to-right without it.",
+        enum: ["ltr", "rtl", "auto"],
+        type: "string",
+      },
+      $lang: {
+        description:
+          "Language tag for this page's <html> element, overriding `defaults.lang` " +
+          "(site-architecture.md §8.4).",
+        examples: ["en", "fr", "ar-EG"],
+        type: "string",
+      },
+      $translationKey: {
+        description:
+          "This page's identity across languages, overriding the one its path implies " +
+          "(site-architecture.md §13.5). Two routes are translations when their keys match; " +
+          "the default key is the path with the locale prefix removed, which is right whenever " +
+          "the paths are parallel and wrong for a localized slug — /fr-ca/a-propos/ shares " +
+          "nothing with /about/ until one of them says so.",
+        examples: ["about", "blog/hello-world"],
+        type: "string",
+      },
       $layout: {
         description:
           "Layout reference for pages. String path to a layout JSON file, " +
@@ -344,6 +393,24 @@ export async function generateSchema() {
         examples: ["./layouts/base.json"],
         oneOf: [{ type: "string" }, { const: false, type: "boolean" }],
       },
+      $shadow: {
+        description:
+          "Render this component into a shadow root instead of the light DOM (spec.md §16.6). " +
+          "Off unless set: a shadow root isolates the component's styles from the page and " +
+          "replaces the <slot> emulation with real slot distribution, so it changes how the " +
+          "component composes. Overrides `defaults.shadow` in both directions — `false` opts " +
+          "one component out of a project that opted in.",
+        oneOf: [
+          { enum: ["open", "closed"], type: "string" },
+          { const: false, type: "boolean" },
+        ],
+      },
+      $sitemap: {
+        description:
+          "Set false to exclude this page from sitemap.xml (site-architecture.md §8.4.1). " +
+          "Every other page with a URL is included.",
+        type: "boolean",
+      },
       $media: {
         additionalProperties: { type: "string" },
         description:
@@ -362,10 +429,17 @@ export async function generateSchema() {
         type: "object",
       },
       $paths: {
+        /* Was `type: "object"`, which accepted any object at all — a misspelled key or a
+           content-type source in a project without the parser enabled passed validation and then
+           silently expanded to zero pages. Referencing the union resource by its canonical $id is
+           what makes the per-project entry document's effective union apply (extensions.md §5.3);
+           `$defs.PathsValue` below carries the shipped default so this file still resolves alone. */
+        $ref: DOCUMENT_PATHS_SCHEMA_ID,
         description:
-          "Dynamic route parameters. Maps parameter names to data sources " +
-          "for generating one page per entry at build time.",
-        type: "object",
+          "Dynamic route source for a page: expands one page per entry at build time. One of the " +
+          "core shapes (explicit `values`, a `$ref` data file, or a bare array of parameter " +
+          "objects) or a source shape contributed by an enabled extension, such as the parser's " +
+          "`contentType`.",
       },
       $schema: {
         description: "URI identifying the Jx dialect version. Enables schema-aware IDE tooling.",
@@ -499,9 +573,11 @@ export function generateDocumentPathsSchema() {
   return {
     $id: DOCUMENT_PATHS_SCHEMA_ID,
     $schema: "https://json-schema.org/draft/2020-12/schema",
+    anyOf: [...documentPathsCoreMembers, documentPathsUnknownSourceMember],
     description:
-      "Default $paths-value union for documents. Per-project entry documents override this " +
-      "resource with the union of extension-contributed paths shapes.",
+      "Default $paths-value union for documents: the core source shapes. Per-project entry " +
+      "documents override this resource with those members PLUS every extension-contributed " +
+      "paths shape.",
     title: "Jx Document Paths Union",
   };
 }
@@ -644,7 +720,8 @@ export async function validateWithSchema(
   doc: Record<string, unknown>,
   schema: Record<string, unknown>,
 ) {
-  let Ajv: AjvCtor, addFormats: AddFormatsFn;
+  let Ajv: AjvCtor;
+  let addFormats: AddFormatsFn;
   try {
     // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
     // (the default `ajv` export is draft-07 and can't compile a 2020-12 schema).