@jxsuite/schema 1.1.0 → 1.3.0

package/schemas/document.paths.schema.json

@@ -3,4 +3,4 @@
   "$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.",
   "title": "Jx Document Paths Union"
-}
+}

package/schemas/project.core.schema.json

@@ -41,10 +41,7 @@
         },
         "service": {
           "description": "How images are optimized: \"build\" runs Sharp at build time; \"cloudflare\" emits /cdn-cgi/image transform URLs served by Cloudflare Image Transformations (requires the feature to be enabled on the serving zone).",
-          "enum": [
-            "build",
-            "cloudflare"
-          ],
+          "enum": ["build", "cloudflare"],
           "type": "string"
         },
         "sizes": {
@@ -88,20 +85,11 @@
           "type": "array"
         },
         "type": {
-          "enum": [
-            "string",
-            "number",
-            "integer",
-            "boolean",
-            "array",
-            "object"
-          ],
+          "enum": ["string", "number", "integer", "boolean", "array", "object"],
           "type": "string"
         }
       },
-      "required": [
-        "type"
-      ],
+      "required": ["type"],
       "type": "object"
     },
     "RelationshipRef": {
@@ -115,9 +103,25 @@
           "type": "string"
         }
       },
-      "required": [
-        "$ref"
-      ],
+      "required": ["$ref"],
+      "type": "object"
+    },
+    "StyleObject": {
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "$ref": "#/$defs/StyleObject"
+          }
+        ]
+      },
+      "description": "CSS style definition. camelCase property names follow CSSOM convention. Keys starting with :, ., &, or [ are treated as nested CSS selectors. Keys matching $media breakpoint names (or other @-prefixed at-rules) group nested rules. Nesting is recursive: selector and at-rule groups may nest to arbitrary depth (e.g. breakpoint → selector → pseudo-class), mirroring the compiler's recursive emission.",
+      "properties": {},
       "type": "object"
     }
   },
@@ -140,9 +144,7 @@
                 "type": "string"
               }
             },
-            "required": [
-              "$ref"
-            ],
+            "required": ["$ref"],
             "type": "object"
           },
           {
@@ -192,9 +194,10 @@
       "additionalProperties": {
         "type": "string"
       },
-      "description": "Named media breakpoints following CSS @custom-media convention. Available in all component style objects.",
+      "description": "Named media breakpoints following CSS @custom-media convention. Available in all component style objects. Declaring a pure color-scheme query (e.g. \"--dark\": \"(prefers-color-scheme: dark)\") additionally opts the site into the forced-scheme contract: @--dark style blocks are dual-emitted so a data-color-scheme attribute on <html> overrides the OS preference, color-scheme is declared on :root, and a pre-paint script restores the visitor's persisted choice (spec §9.5).",
       "examples": [
         {
+          "--dark": "(prefers-color-scheme: dark)",
           "--lg": "(min-width: 1024px)",
           "--md": "(min-width: 768px)",
           "--sm": "(min-width: 640px)"
@@ -211,13 +214,7 @@
       "properties": {
         "adapter": {
           "description": "Platform adapter for deployment-specific output.",
-          "enum": [
-            "static",
-            "cloudflare-pages",
-            "cloudflare-workers",
-            "node",
-            "bun"
-          ],
+          "enum": ["static", "cloudflare-pages", "cloudflare-workers", "node", "bun"],
           "type": "string"
         },
         "deploy": {
@@ -239,26 +236,17 @@
             },
             "provider": {
               "description": "Hosting provider the project is connected to.",
-              "enum": [
-                "cloudflare-pages"
-              ],
+              "enum": ["cloudflare-pages"],
               "type": "string"
             }
           },
-          "required": [
-            "provider",
-            "accountId",
-            "projectName"
-          ],
+          "required": ["provider", "accountId", "projectName"],
           "type": "object"
         },
         "format": {
           "default": "directory",
           "description": "Reserved; currently unused. Accepted for forward compatibility with single-file output (desktop single-file mode) — the build emits per-route directories regardless.",
-          "enum": [
-            "directory",
-            "single"
-          ],
+          "enum": ["directory", "single"],
           "type": "string"
         },
         "outDir": {
@@ -274,11 +262,7 @@
         "trailingSlash": {
           "default": "always",
           "description": "Trailing slash behavior for generated URLs.",
-          "enum": [
-            "always",
-            "never",
-            "ignore"
-          ],
+          "enum": ["always", "never", "ignore"],
           "type": "string"
         }
       },
@@ -307,9 +291,7 @@
         "layout": {
           "default": null,
           "description": "Default layout file path applied to all pages. Set to null to render pages without a layout.",
-          "examples": [
-            "./layouts/base.json"
-          ],
+          "examples": ["./layouts/base.json"],
           "oneOf": [
             {
               "type": "string"
@@ -324,11 +306,7 @@
     },
     "extensions": {
       "description": "Extension packages: bare package names (resolved project-first through the package exports map) or relative paths. Each must export jx-extension.json.",
-      "examples": [
-        [
-          "@jxsuite/parser"
-        ]
-      ],
+      "examples": [["@jxsuite/parser"]],
       "items": {
         "type": "string"
       },
@@ -339,20 +317,12 @@
       "properties": {
         "defaultLocale": {
           "description": "Default locale code.",
-          "examples": [
-            "en"
-          ],
+          "examples": ["en"],
           "type": "string"
         },
         "locales": {
           "description": "Available locale codes.",
-          "examples": [
-            [
-              "en",
-              "fr",
-              "de"
-            ]
-          ],
+          "examples": [["en", "fr", "de"]],
           "items": {
             "type": "string"
           },
@@ -360,10 +330,7 @@
         },
         "routing": {
           "description": "Locale routing strategy.",
-          "enum": [
-            "prefix-except-default",
-            "prefix-always"
-          ],
+          "enum": ["prefix-except-default", "prefix-always"],
           "type": "string"
         }
       },
@@ -388,10 +355,7 @@
     "name": {
       "default": "Jx Site",
       "description": "Human-readable project name.",
-      "examples": [
-        "My Portfolio",
-        "Jx Example Site"
-      ],
+      "examples": ["My Portfolio", "Jx Example Site"],
       "type": "string"
     },
     "redirects": {
@@ -420,22 +384,19 @@
             "type": "number"
           },
           {
-            "type": "object"
+            "$ref": "#/$defs/StyleObject"
           }
         ]
       },
-      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention as component styles.",
+      "description": "Global CSS styles applied to the <body> element. Uses the same camelCase CSSOM convention and recursive selector/at-rule nesting as component styles.",
       "type": "object"
     },
     "url": {
       "description": "Production URL of the deployed site.",
-      "examples": [
-        "https://example.com",
-        "https://jxsuite.com"
-      ],
+      "examples": ["https://example.com", "https://jxsuite.com"],
       "type": "string"
     }
   },
   "title": "Jx Project Core",
   "type": "object"
-}
+}

package/schemas/project.fields.schema.json

@@ -11,4 +11,4 @@
   ],
   "description": "Default field-schema union for section entry schemas: the core field shape plus relationship references. Per-project entry documents override this resource with the effective union. See specs/extensions.md §5.3.",
   "title": "Jx Project Field Union"
-}
+}

package/src/asset-paths.ts

@@ -0,0 +1,42 @@
+/**
+ * Deterministic mapping from Function-def `$src` module specifiers to bundled asset URLs. Shared
+ * between the compiler's sidecar bundler (which writes the bundle) and extension `lower()`
+ * implementations (which emit the URL into client code) so neither needs to depend on the other.
+ *
+ * The mapping is intentionally hash-free: the same specifier always yields the same URL, letting
+ * lowered defs reference bundles the compiler produces later in the build. Distinct specifiers that
+ * collide on a slug are rejected by the bundler at build time.
+ */
+
+/** Prefix for npm package specifiers in `$src` (spec §12): `npm:<pkg>[/subpath]`. */
+export const NPM_SPECIFIER_PREFIX = "npm:";
+
+/** URL directory (under the site root) where bundled sidecars are written. */
+export const SIDECAR_ASSET_DIR = "/assets/";
+
+/** True when a `$src` specifier names an npm package rather than a project file. */
+export function isNpmSpecifier(specifier: string): boolean {
+  return specifier.startsWith(NPM_SPECIFIER_PREFIX);
+}
+
+/**
+ * Map a Function-def `$src` specifier to its bundled asset URL.
+ *
+ * `npm:@jxsuite/search/client` → `/assets/jxsuite-search-client.js` `./lib/search-helpers.ts` →
+ * `/assets/lib-search-helpers.js`
+ */
+export function sidecarAssetPath(specifier: string): string {
+  let base = specifier;
+  if (isNpmSpecifier(base)) {
+    base = base.slice(NPM_SPECIFIER_PREFIX.length);
+  }
+  base = base
+    .replace(/^\.\//, "")
+    .replace(/\.(js|ts|mjs|mts)$/, "")
+    .replaceAll("@", "")
+    .replaceAll(/[/\\]+/g, "-")
+    .replaceAll(/[^\w.-]/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "");
+  return `${SIDECAR_ASSET_DIR}${base}.js`;
+}

package/src/extension-registry.ts

@@ -151,6 +151,11 @@ export class ExtensionRegistry {
     return this.#classes.find((e) => e.capabilities.resolvePaths?.discriminator === key);
   }
 
+  /** Classes declaring an `emit` capability (build-time asset emission), in declaration order. */
+  emitters(): FormatEntry[] {
+    return this.#classes.filter((e) => e.capabilities.emit !== undefined);
+  }
+
   /** Server-mount classes, sorted by `server.order` (ascending; default 100), then name. */
   serverMounts(): FormatEntry[] {
     return this.#classes

package/src/format-registry.ts

@@ -21,14 +21,16 @@ export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
 
 /**
  * All well-known static capability roles across admission blocks (specs/extensions.md §8): format
- * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), server-mount
- * (`mount`), and connector (`dialect`, `deploySchema`, `bindings`, `testConnection`) roles.
+ * roles plus project-section (`projectData`, `resolvePaths`), compile-away (`lower`), build-time
+ * asset emission (`emit`), server-mount (`mount`), and connector (`dialect`, `deploySchema`,
+ * `bindings`, `testConnection`) roles.
  */
 export type ExtensionCapability =
   | FormatCapability
   | "projectData"
   | "resolvePaths"
   | "lower"
+  | "emit"
   | "mount"
   | "dialect"
   | "deploySchema"
@@ -40,6 +42,7 @@ export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
   "projectData",
   "resolvePaths",
   "lower",
+  "emit",
   "mount",
   "dialect",
   "deploySchema",

package/src/guards.ts

@@ -174,6 +174,16 @@ export function isTemplateString(value?: unknown): value is string {
   return typeof value === "string" && value.includes("${");
 }
 
+/**
+ * Whether a function `body` returns a value — the heuristic that classifies a `$prototype:
+ * "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.
+ */
+export function bodyReturnsValue(body: string): boolean {
+  return /\breturn\b/.test(body);
+}
+
 // ─── Style guards & accessors ───────────────────────────────────────────────────
 
 /** A nested style object (selector/media block), as opposed to a scalar CSS value. */

package/src/schema.ts

@@ -92,7 +92,10 @@ import {
   classFieldDefSchema,
   classMethodDefSchema,
   classParameterDefSchema,
+  connectorBlockDefSchema,
   formatDefSchema,
+  projectBlockDefSchema,
+  serverBlockDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
 import { extensionManifestSchema } from "../defs/extension-manifest.schema";
@@ -182,7 +185,11 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
   for (const name of eventHandlers) {
     properties[name] = {
       description: `Event handler for the "${name.slice(2)}" event.`,
-      oneOf: [{ $ref: "#/$defs/RefObject" }, { $ref: "#/$defs/ExpressionEntry" }],
+      oneOf: [
+        { $ref: "#/$defs/RefObject" },
+        { $ref: "#/$defs/ExpressionEntry" },
+        { $ref: "#/$defs/FunctionDef" },
+      ],
     };
   }
   return properties;
@@ -216,6 +223,9 @@ export async function generateSchema() {
       ClassConstructorDef: classConstructorDefSchema,
       ClassMethodDef: classMethodDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       StudioHints: studioHintsSchema,
       ExternalClassDef: externalClassDefSchema,
       ExpressionPointer: expressionPointerSchema,
@@ -338,7 +348,10 @@ export async function generateSchema() {
         additionalProperties: { type: "string" },
         description:
           "Named media breakpoints following CSS @custom-media convention. " +
-          "Keys use the CSS custom property -- prefix.",
+          "Keys use the CSS custom property -- prefix. Pure color-scheme queries " +
+          '(e.g. "--dark": "(prefers-color-scheme: dark)") are dual-emitted so a ' +
+          "data-color-scheme attribute on the root element forces the scheme " +
+          "regardless of the OS preference (spec §9.5).",
         examples: [
           {
             "--dark": "(prefers-color-scheme: dark)",
@@ -412,6 +425,7 @@ export function generateProjectSchema() {
   return {
     $defs: {
       ImageConfig: imageConfigSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -443,6 +457,7 @@ export function generateProjectCoreSchema() {
       ImageConfig: imageConfigSchema,
       JxFieldSchema: jxFieldSchemaDef,
       RelationshipRef: relationshipRefSchema,
+      StyleObject: styleObjectSchema,
     },
     $id: "https://jxsuite.com/schema/project/core/v2",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -511,7 +526,10 @@ export function generateClassSchema() {
       ClassFieldDef: classFieldDefSchema,
       ClassMethodDef: classMethodDefSchema,
       ClassParameterDef: classParameterDefSchema,
+      ConnectorBlockDef: connectorBlockDefSchema,
       FormatDef: formatDefSchema,
+      ProjectBlockDef: projectBlockDefSchema,
+      ServerBlockDef: serverBlockDefSchema,
       StudioHints: studioHintsSchema,
     },
     $id: "https://jxsuite.com/schema/class/v1",
@@ -562,6 +580,7 @@ export function generateClassSchema() {
       },
       $schema: { type: "string" },
       $studio: { $ref: "#/$defs/StudioHints" },
+      connector: { $ref: "#/$defs/ConnectorBlockDef" },
       description: { type: "string" },
       extends: {
         description: "Base class — string name or $ref to another .class.json.",
@@ -576,6 +595,8 @@ export function generateClassSchema() {
         ],
       },
       format: { $ref: "#/$defs/FormatDef" },
+      project: { $ref: "#/$defs/ProjectBlockDef" },
+      server: { $ref: "#/$defs/ServerBlockDef" },
       title: {
         description: "PascalCase class name, used as the export name.",
         examples: ["MarkdownFile", "DataSource", "Calculator"],
@@ -610,7 +631,19 @@ type AjvCtor = new (opts: {
 }) => AjvInstance;
 type AddFormatsFn = (ajv: AjvInstance) => void;
 
-export async function validateDocument(doc: Record<string, unknown>) {
+/**
+ * Validate a document against an arbitrary JSON Schema 2020-12 document (e.g. a bundled per-project
+ * document.schema.json from `jx schema`). The schema must be self-contained — external refs are not
+ * resolved here.
+ *
+ * @param {Record<string, unknown>} doc - The document to validate
+ * @param {Record<string, unknown>} schema - A self-contained 2020-12 schema
+ * @returns {Promise<{ errors: unknown[] | null; valid: boolean }>}
+ */
+export async function validateWithSchema(
+  doc: Record<string, unknown>,
+  schema: Record<string, unknown>,
+) {
   let Ajv: AjvCtor, addFormats: AddFormatsFn;
   try {
     // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
@@ -625,13 +658,21 @@ export async function validateDocument(doc: Record<string, unknown>) {
   const ajv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(ajv);
 
-  const schema = await generateSchema();
   const validate = ajv.compile(schema);
   const valid = validate(doc);
 
   return { errors: validate.errors ?? null, valid };
 }
 
+export async function validateDocument(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, (await generateSchema()) as Record<string, unknown>);
+}
+
+/** Validate a .class.json class definition against the generated class schema. */
+export async function validateClass(doc: Record<string, unknown>) {
+  return validateWithSchema(doc, generateClassSchema() as Record<string, unknown>);
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 async function runSchemaCli() {
@@ -674,6 +715,30 @@ async function runSchemaCli() {
     writeFileSync(resolve(schemaDir, "schemas", "project.fields.schema.json"), fieldsStr, "utf8");
     writeFileSync(resolve(schemaDir, "schemas", "document.paths.schema.json"), pathsStr, "utf8");
     writeFileSync(resolve(schemaDir, "extension-manifest.schema.json"), manifestStr, "utf8");
+    // The schemas/ fragments are oxfmt-managed (unlike packages/schema/*.json, which .oxfmtrc
+    // Ignores), so emit them formatted — otherwise every `bun run generate:schema` reintroduces
+    // Raw-stringify formatting and dirties the tree. This is a dev-hygiene step only: the JSON
+    // Above is already written and valid, and oxfmt just prettifies it (e.g. collapsing short enum
+    // Arrays onto one line). Inside a sandboxed/offline build (e.g. `nix build`) oxfmt exits
+    // Non-zero with no diagnostic output, so treat a failure as non-fatal and keep the valid JSON
+    // Rather than aborting the build over cosmetic formatting.
+    const fmt = Bun.spawnSync(
+      [
+        "bunx",
+        "oxfmt",
+        resolve(schemaDir, "schemas", "project.core.schema.json"),
+        resolve(schemaDir, "schemas", "project.fields.schema.json"),
+        resolve(schemaDir, "schemas", "document.paths.schema.json"),
+      ],
+      { cwd: schemaDir },
+    );
+    if (fmt.exitCode !== 0) {
+      const detail =
+        fmt.stderr.toString() ||
+        fmt.stdout.toString() ||
+        `exit ${fmt.exitCode ?? "null"}${fmt.signalCode ? `, signal ${fmt.signalCode}` : ""}`;
+      console.error(`Warning: skipped oxfmt reformat of generated schemas (${detail})`);
+    }
     console.error("Generated:");
     console.error("  schema.json (component)");
     console.error("  project-schema.json");

package/src/validate-project.ts

@@ -133,6 +133,19 @@ async function loadProjectSchemaRef(uri: string, root: string): Promise<Record<s
       const selfRequire = createRequire(import.meta.url);
       resolved = selfRequire.resolve(specifier);
     } catch (error) {
+      // Exports-map subpath resolution is brittle against version-skewed shadowing installs (a
+      // Stale local copy terminates Node's walk-up with ERR_PACKAGE_PATH_NOT_EXPORTED). Our own
+      // Schema files are pure data and the running validator's copy is guaranteed to match, so
+      // Read them straight off this package's disk as the last resort.
+      const ownPrefix = "@jxsuite/schema/";
+      if (specifier.startsWith(ownPrefix)) {
+        const ownFile = fileURLToPath(
+          new URL(`../${specifier.slice(ownPrefix.length)}`, import.meta.url),
+        );
+        if (existsSync(ownFile)) {
+          return JSON.parse(readFileSync(ownFile, "utf8")) as Record<string, unknown>;
+        }
+      }
       throw new Error(
         `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
           `project or the host`,