@jxsuite/schema 1.4.0 → 1.5.0

package/defs/field-schema.schema.ts

@@ -56,3 +56,78 @@ export const relationshipRefSchema = {
   required: ["$ref"],
   type: "object",
 } as const;
+
+/**
+ * The CORE `$paths` source shapes — the members the shipped default paths union carries, and the
+ * ones every per-project entry document unions extension shapes on top of.
+ *
+ * These mirror `resolvePathEntries` in the compiler's pages-discovery exactly (specs/
+ * site-architecture.md §4.3): an explicit value list, a JSON data-file reference, and the legacy
+ * bare array of parameter objects. Anything else is dispatched by discriminator key to an
+ * extension's `resolvePaths` capability, so extension shapes reach the union through the entry
+ * document rather than from here.
+ *
+ * Each shape is CLOSED (`additionalProperties: false`). `$paths` is a build-time instruction with a
+ * fully specified grammar and no forward-compatible extension points of its own — a stray or
+ * misspelled key means the route silently expands to nothing, which is exactly the failure worth
+ * catching in the editor.
+ */
+export const documentPathsCoreMembers = [
+  {
+    additionalProperties: false,
+    description:
+      'Explicit value list: generates one page per value, bound to `param` (default "value").',
+    properties: {
+      param: { description: 'Route parameter to fill (default "value").', type: "string" },
+      values: { description: "The values to expand.", type: "array" },
+    },
+    required: ["values"],
+    type: "object",
+  },
+  {
+    additionalProperties: false,
+    description:
+      "JSON data-file source: loads a project-relative file that must contain an array, and " +
+      "generates one page per item.",
+    properties: {
+      $ref: {
+        description: "Project-relative path to a .json file containing an array.",
+        type: "string",
+      },
+      field: {
+        description: 'Item field providing the parameter value (default "id").',
+        type: "string",
+      },
+      param: { description: 'Route parameter to fill (default "id").', type: "string" },
+    },
+    required: ["$ref"],
+    type: "object",
+  },
+  {
+    description:
+      "Legacy explicit form: an array of ready-made parameter objects, used as-is with no " +
+      "expansion. Prefer one of the source shapes above.",
+    items: { additionalProperties: { type: "string" }, type: "object" },
+    type: "array",
+  },
+] as const;
+
+/**
+ * The extra member the SHIPPED DEFAULT union carries and a per-project entry document does not.
+ *
+ * A default cannot know which extensions a project enables, so without this any extension source
+ * shape — `{ contentType: "blog" }` with the parser on — would be a FALSE ERROR wherever the
+ * default is what is in play: the studio's offline fallback before per-project schemas arrive, and
+ * clients that fetch the canonical URL. Spec §5.4 promises that path degrades to
+ * _under-suggestion_, never false errors, so the default accepts any non-empty object and the entry
+ * document — which does know the enabled extensions, and is what `jx validate` and every editor
+ * actually resolve — is the strict one.
+ */
+export const documentPathsUnknownSourceMember = {
+  description:
+    "A source shape contributed by an extension this schema cannot see. The project's generated " +
+    "document.schema.json validates these exactly; enable the owning extension and regenerate " +
+    "with `jx schema` to get precise checking here.",
+  minProperties: 1,
+  type: "object",
+} as const;

package/package.json

@@ -1,8 +1,8 @@
 {
   "dependencies": {
-    "@webref/css": "^8.7.0",
+    "@webref/css": "^8.7.1",
     "@webref/elements": "^2.7.1",
-    "@webref/idl": "^3.82.0",
+    "@webref/idl": "^3.82.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1"
   },
@@ -50,7 +50,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/schema.json

@@ -7719,6 +7719,26 @@
             }
           ]
         },
+        "animation-delay-end": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "animation-delay-start": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
         "animation-direction": {
           "oneOf": [
             {
@@ -7869,6 +7889,26 @@
             }
           ]
         },
+        "animationDelayEnd": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "animationDelayStart": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
         "animationDirection": {
           "oneOf": [
             {
@@ -22996,6 +23036,67 @@
         }
       },
       "type": "object"
+    },
+    "PathsValue": {
+      "$id": "https://jxsuite.com/schema/document/paths/v2",
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "description": "Explicit value list: generates one page per value, bound to `param` (default \"value\").",
+          "properties": {
+            "param": {
+              "description": "Route parameter to fill (default \"value\").",
+              "type": "string"
+            },
+            "values": {
+              "description": "The values to expand.",
+              "type": "array"
+            }
+          },
+          "required": [
+            "values"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "JSON data-file source: loads a project-relative file that must contain an array, and generates one page per item.",
+          "properties": {
+            "$ref": {
+              "description": "Project-relative path to a .json file containing an array.",
+              "type": "string"
+            },
+            "field": {
+              "description": "Item field providing the parameter value (default \"id\").",
+              "type": "string"
+            },
+            "param": {
+              "description": "Route parameter to fill (default \"id\").",
+              "type": "string"
+            }
+          },
+          "required": [
+            "$ref"
+          ],
+          "type": "object"
+        },
+        {
+          "description": "Legacy explicit form: an array of ready-made parameter objects, used as-is with no expansion. Prefer one of the source shapes above.",
+          "items": {
+            "additionalProperties": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "description": "A source shape contributed by an extension this schema cannot see. The project's generated document.schema.json validates these exactly; enable the owning extension and regenerate with `jx schema` to get precise checking here.",
+          "minProperties": 1,
+          "type": "object"
+        }
+      ],
+      "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",
@@ -23079,8 +23180,8 @@
       "type": "object"
     },
     "$paths": {
-      "description": "Dynamic route parameters. Maps parameter names to data sources for generating one page per entry at build time.",
-      "type": "object"
+      "$ref": "https://jxsuite.com/schema/document/paths/v2",
+      "description": "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.",

package/schemas/document.paths.schema.json

@@ -1,6 +1,59 @@
 {
   "$id": "https://jxsuite.com/schema/document/paths/v2",
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "description": "Default $paths-value union for documents. Per-project entry documents override this resource with the union of extension-contributed paths shapes.",
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "description": "Explicit value list: generates one page per value, bound to `param` (default \"value\").",
+      "properties": {
+        "param": {
+          "description": "Route parameter to fill (default \"value\").",
+          "type": "string"
+        },
+        "values": {
+          "description": "The values to expand.",
+          "type": "array"
+        }
+      },
+      "required": ["values"],
+      "type": "object"
+    },
+    {
+      "additionalProperties": false,
+      "description": "JSON data-file source: loads a project-relative file that must contain an array, and generates one page per item.",
+      "properties": {
+        "$ref": {
+          "description": "Project-relative path to a .json file containing an array.",
+          "type": "string"
+        },
+        "field": {
+          "description": "Item field providing the parameter value (default \"id\").",
+          "type": "string"
+        },
+        "param": {
+          "description": "Route parameter to fill (default \"id\").",
+          "type": "string"
+        }
+      },
+      "required": ["$ref"],
+      "type": "object"
+    },
+    {
+      "description": "Legacy explicit form: an array of ready-made parameter objects, used as-is with no expansion. Prefer one of the source shapes above.",
+      "items": {
+        "additionalProperties": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "description": "A source shape contributed by an extension this schema cannot see. The project's generated document.schema.json validates these exactly; enable the owning extension and regenerate with `jx schema` to get precise checking here.",
+      "minProperties": 1,
+      "type": "object"
+    }
+  ],
+  "description": "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"
 }

package/src/guards.ts

@@ -179,9 +179,14 @@ export function isTemplateString(value?: unknown): value is string {
  * "Function"` as a computed value vs an event handler. Uses a word boundary so identifiers like
  * `returned` do not match. Shared by the runtime interpreter and the compiler so both agree on the
  * classification.
+ *
+ * A bare `return;` does not count. It is an early-exit guard, which is handler code — reading it as
+ * a value return turned any handler with a guard clause into a `computed()`, so the binding that
+ * invoked it found a value where it expected a function. The value has to follow on the same line,
+ * because a newline after `return` is an ASI bare return.
  */
 export function bodyReturnsValue(body: string): boolean {
-  return /\breturn\b/.test(body);
+  return /\breturn\b[^\S\n]*(?![;}\s]|$)/.test(body);
 }
 
 // ─── Style guards & accessors ───────────────────────────────────────────────────

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

@@ -102,6 +102,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";
@@ -288,6 +290,19 @@ export async function generateSchema() {
       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",
@@ -362,10 +377,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 +521,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",
   };
 }