@jxsuite/schema 1.1.0 → 1.2.0

package/defs/project-config.schema.ts

@@ -54,9 +54,15 @@ export const projectConfigSchema = {
       additionalProperties: { type: "string" },
       description:
         "Named media breakpoints following CSS @custom-media convention. " +
-        "Available in all component style objects.",
+        "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)",

package/package.json

@@ -9,6 +9,7 @@
   "description": "JSON Schema 2020-12 meta-schema generator for Jx documents",
   "exports": {
     ".": "./src/schema.ts",
+    "./asset-paths": "./src/asset-paths.ts",
     "./extension-registry": "./src/extension-registry.ts",
     "./format-registry": "./src/format-registry.ts",
     "./project-schemas": "./src/project-schemas.ts",
@@ -49,7 +50,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -131,9 +131,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)"

package/schema.json

@@ -22034,7 +22034,7 @@
       "additionalProperties": {
         "type": "string"
       },
-      "description": "Named media breakpoints following CSS @custom-media convention. Keys use the CSS custom property -- prefix.",
+      "description": "Named media breakpoints following CSS @custom-media convention. 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)",

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,7 @@
           "type": "string"
         }
       },
-      "required": [
-        "$ref"
-      ],
+      "required": ["$ref"],
       "type": "object"
     }
   },
@@ -140,9 +126,7 @@
                 "type": "string"
               }
             },
-            "required": [
-              "$ref"
-            ],
+            "required": ["$ref"],
             "type": "object"
           },
           {
@@ -192,9 +176,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 +196,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 +218,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 +244,7 @@
         "trailingSlash": {
           "default": "always",
           "description": "Trailing slash behavior for generated URLs.",
-          "enum": [
-            "always",
-            "never",
-            "ignore"
-          ],
+          "enum": ["always", "never", "ignore"],
           "type": "string"
         }
       },
@@ -307,9 +273,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 +288,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 +299,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 +312,7 @@
         },
         "routing": {
           "description": "Locale routing strategy.",
-          "enum": [
-            "prefix-except-default",
-            "prefix-always"
-          ],
+          "enum": ["prefix-except-default", "prefix-always"],
           "type": "string"
         }
       },
@@ -388,10 +337,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": {
@@ -429,13 +375,10 @@
     },
     "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/schema.ts

@@ -338,7 +338,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)",
@@ -674,6 +677,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");