@jxsuite/schema 1.2.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Shenk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/class-schema.json

@@ -176,7 +176,16 @@
             "parse",
             "serialize",
             "discover",
-            "load"
+            "load",
+            "projectData",
+            "resolvePaths",
+            "lower",
+            "emit",
+            "mount",
+            "dialect",
+            "deploySchema",
+            "bindings",
+            "testConnection"
           ],
           "type": "string"
         },
@@ -237,6 +246,40 @@
       ],
       "type": "object"
     },
+    "ConnectorBlockDef": {
+      "description": "Connection-provider admission block (specs/extensions.md §12). A class carrying this block provides database connections of the given provider/kind.",
+      "properties": {
+        "kind": {
+          "description": "SQL dialect family the provider speaks.",
+          "enum": [
+            "sqlite",
+            "postgres"
+          ],
+          "type": "string"
+        },
+        "local": {
+          "description": "Local-development substitute provider (e.g. sqlite for D1).",
+          "type": "string"
+        },
+        "module": {
+          "description": "Module specifier exporting the provider implementation.",
+          "type": "string"
+        },
+        "provider": {
+          "description": "Provider identifier (e.g. d1, supabase, sqlite).",
+          "type": "string"
+        },
+        "serve": {
+          "description": "Module specifier exporting the serve-time worker binding.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "provider",
+        "kind"
+      ],
+      "type": "object"
+    },
     "FormatDef": {
       "description": "Format participation marker. A class carrying this block is auto-discovered from the project imports map and used for file-extension dispatch by the compiler, server, and studio.",
       "properties": {
@@ -279,6 +322,56 @@
       ],
       "type": "object"
     },
+    "ProjectBlockDef": {
+      "additionalProperties": false,
+      "description": "Project-section admission block (specs/extensions.md §9). A class carrying this block owns the project.json section named by `key`; hosts dispatch that section's data through the class's projectData/resolvePaths capabilities.",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "key": {
+          "description": "The project.json top-level section this class owns (exclusive per project).",
+          "type": "string"
+        },
+        "referenceable": {
+          "description": "Whether section entries can be referenced from documents (e.g. content types).",
+          "type": "boolean"
+        },
+        "title": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "key"
+      ],
+      "type": "object"
+    },
+    "ServerBlockDef": {
+      "additionalProperties": false,
+      "description": "Server-mount admission block (specs/extensions.md §11). A class carrying this block mounts routes under its /_jx/ basePath in the site worker and dev server.",
+      "properties": {
+        "basePath": {
+          "description": "Route subtree this class mounts — must be under /_jx/ (exclusive per project).",
+          "examples": [
+            "/_jx/data",
+            "/_jx/auth"
+          ],
+          "type": "string"
+        },
+        "module": {
+          "description": "Module specifier exporting the mount handler.",
+          "type": "string"
+        },
+        "order": {
+          "description": "Mount order (ascending; default 100).",
+          "type": "number"
+        }
+      },
+      "required": [
+        "basePath"
+      ],
+      "type": "object"
+    },
     "StudioHints": {
       "description": "Studio control-surface hints for a format class: editor modes, document-mode rules, templates, and the element/nesting constraints that gate structural editing.",
       "properties": {
@@ -442,6 +535,9 @@
     "$studio": {
       "$ref": "#/$defs/StudioHints"
     },
+    "connector": {
+      "$ref": "#/$defs/ConnectorBlockDef"
+    },
     "description": {
       "type": "string"
     },
@@ -468,6 +564,12 @@
     "format": {
       "$ref": "#/$defs/FormatDef"
     },
+    "project": {
+      "$ref": "#/$defs/ProjectBlockDef"
+    },
+    "server": {
+      "$ref": "#/$defs/ServerBlockDef"
+    },
     "title": {
       "description": "PascalCase class name, used as the export name.",
       "examples": [

package/defs/children-value.schema.ts

@@ -18,7 +18,8 @@ export const childrenValueSchema = {
   description:
     "Array of child definitions — elements, text, or Array namespaces (dynamic lists) mixed " +
     "freely. A bare Array namespace (the whole children slot is one dynamic list) is also " +
-    "accepted for backward compatibility.",
+    "accepted for backward compatibility, as is a ${…} template string that resolves at build " +
+    "time to an array of child definitions.",
   oneOf: [
     {
       items: {
@@ -32,5 +33,13 @@ export const childrenValueSchema = {
       type: "array",
     },
     { $ref: "#/$defs/ArrayNamespace" },
+    {
+      description:
+        "Computed children — a ${…} template that resolves at build time to an array of child " +
+        'definitions (e.g. "${state.entry.$children}" for parsed content). A bare plain-text ' +
+        "string is NOT a valid children value; text children must be array items.",
+      pattern: "\\$\\{",
+      type: "string",
+    },
   ],
 } as const;

package/defs/class-def.schema.ts

@@ -1,3 +1,27 @@
+/**
+ * Method capability roles: "method"/"accessor" plus every static capability role hosts dispatch on
+ * (format-registry EXTENSION_CAPABILITIES — specs/extensions.md §8). Kept as a literal tuple so
+ * FromSchema inference stays precise; the drift-guard test in tests/class-schema-drift.test.ts
+ * asserts parity with EXTENSION_CAPABILITIES.
+ */
+export const CLASS_METHOD_ROLES = [
+  "method",
+  "accessor",
+  "parse",
+  "serialize",
+  "discover",
+  "load",
+  "projectData",
+  "resolvePaths",
+  "lower",
+  "emit",
+  "mount",
+  "dialect",
+  "deploySchema",
+  "bindings",
+  "testConnection",
+] as const;
+
 export const classParameterDefSchema = {
   description: "A typed parameter definition for a class.",
   properties: {
@@ -100,7 +124,7 @@ export const classMethodDefSchema = {
     },
     returnType: {},
     role: {
-      enum: ["method", "accessor", "parse", "serialize", "discover", "load"],
+      enum: CLASS_METHOD_ROLES,
       type: "string",
     },
     scope: { enum: ["instance", "static"], type: "string" },
@@ -157,6 +181,85 @@ export const formatDefSchema = {
   type: "object",
 } as const;
 
+export const projectBlockDefSchema = {
+  additionalProperties: false,
+  description:
+    "Project-section admission block (specs/extensions.md §9). A class carrying this block owns " +
+    "the project.json section named by `key`; hosts dispatch that section's data through the " +
+    "class's projectData/resolvePaths capabilities.",
+  properties: {
+    description: { type: "string" },
+    key: {
+      description: "The project.json top-level section this class owns (exclusive per project).",
+      type: "string",
+    },
+    referenceable: {
+      description: "Whether section entries can be referenced from documents (e.g. content types).",
+      type: "boolean",
+    },
+    title: { type: "string" },
+  },
+  required: ["key"],
+  type: "object",
+} as const;
+
+export const serverBlockDefSchema = {
+  additionalProperties: false,
+  description:
+    "Server-mount admission block (specs/extensions.md §11). A class carrying this block mounts " +
+    "routes under its /_jx/ basePath in the site worker and dev server.",
+  properties: {
+    basePath: {
+      description: "Route subtree this class mounts — must be under /_jx/ (exclusive per project).",
+      examples: ["/_jx/data", "/_jx/auth"],
+      type: "string",
+    },
+    module: {
+      description: "Module specifier exporting the mount handler.",
+      type: "string",
+    },
+    order: {
+      description: "Mount order (ascending; default 100).",
+      type: "number",
+    },
+  },
+  required: ["basePath"],
+  type: "object",
+} as const;
+
+export const connectorBlockDefSchema = {
+  // Open by design: the block mirrors format-registry's ConnectorBlock ([key: string]: unknown) —
+  // Providers carry extra keys (e.g. D1's `module`), so additionalProperties stays true.
+  description:
+    "Connection-provider admission block (specs/extensions.md §12). A class carrying this block " +
+    "provides database connections of the given provider/kind.",
+  properties: {
+    kind: {
+      description: "SQL dialect family the provider speaks.",
+      enum: ["sqlite", "postgres"],
+      type: "string",
+    },
+    local: {
+      description: "Local-development substitute provider (e.g. sqlite for D1).",
+      type: "string",
+    },
+    module: {
+      description: "Module specifier exporting the provider implementation.",
+      type: "string",
+    },
+    provider: {
+      description: "Provider identifier (e.g. d1, supabase, sqlite).",
+      type: "string",
+    },
+    serve: {
+      description: "Module specifier exporting the serve-time worker binding.",
+      type: "string",
+    },
+  },
+  required: ["provider", "kind"],
+  type: "object",
+} as const;
+
 export const studioHintsSchema = {
   description:
     "Studio control-surface hints for a format class: editor modes, document-mode rules, " +
@@ -258,6 +361,7 @@ export const classDefSchema = {
     $prototype: { const: "Class", type: "string" },
     $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.",
@@ -267,6 +371,8 @@ export const classDefSchema = {
       ],
     },
     format: { $ref: "#/$defs/FormatDef" },
+    project: { $ref: "#/$defs/ProjectBlockDef" },
+    server: { $ref: "#/$defs/ServerBlockDef" },
     title: {
       description: "PascalCase class name, used as the export name.",
       type: "string",

package/defs/element-def.schema.ts

@@ -12,8 +12,10 @@ export const attributesObjectSchema = {
 } as const;
 
 export const propsObjectSchema = {
+  // AnyOf, not oneOf: a RefObject value legitimately matches both the plain-object branch and
+  // The RefObject branch, and exclusive matching would reject every $ref-bound prop.
   additionalProperties: {
-    oneOf: [
+    anyOf: [
       { type: "string" },
       { type: "number" },
       { type: "boolean" },
@@ -39,7 +41,9 @@ export const elementPropertyValueSchema = {
 export const switchDefSchema = {
   additionalProperties: false,
   description: "Reactive $ref that drives which case to render.",
-  properties: { $ref: { $ref: "#/$defs/InternalRef" } },
+  // The discriminant is a reactive state path (e.g. "#/state/currentRoute") resolved by
+  // ResolveRef at render time — not a #/$defs/ type pointer.
+  properties: { $ref: { $ref: "#/$defs/StateRef" } },
   required: ["$ref"],
   type: "object",
 } as const;
@@ -70,6 +74,15 @@ export const elementDefSchema = {
     $switch: { $ref: "#/$defs/SwitchDef" },
     alt: { $ref: "#/$defs/StringOrRef" },
     attributes: { $ref: "#/$defs/AttributesObject" },
+    cases: {
+      additionalProperties: {
+        oneOf: [{ $ref: "#/$defs/ElementDef" }, { $ref: "#/$defs/ExternalComponentRef" }],
+      },
+      description:
+        "Switch cases for this element. Maps case values to element definitions or external " +
+        "component refs, rendered according to the reactive $switch discriminant.",
+      type: "object",
+    },
     checked: { $ref: "#/$defs/BoolOrRef" },
     children: { $ref: "#/$defs/ChildrenValue" },
     className: { $ref: "#/$defs/StringOrRef" },

package/defs/external-class-def.schema.ts

@@ -92,7 +92,20 @@ export const externalClassDefSchema = {
     },
     sameSite: { enum: ["strict", "lax", "none"], type: "string" },
     secure: { type: "boolean" },
-    sort: { $ref: "#/$defs/RefObject" },
+    sort: {
+      anyOf: [
+        { $ref: "#/$defs/RefObject" },
+        { description: "A single sort rule, e.g. { field, order }.", type: "object" },
+        {
+          description: 'Ordered sort rules, e.g. [{ field: "date", order: "desc" }].',
+          items: { type: "object" },
+          type: "array",
+        },
+      ],
+      description:
+        "Sort configuration: a reactive $ref binding, a single { field, order } rule, or an " +
+        "ordered array of rules.",
+    },
     src: {
       description: "Configuration property passed to external class constructor.",
       type: "string",

package/defs/function-def.schema.ts

@@ -15,6 +15,14 @@ export const functionDefSchema = {
       examples: ["./counter.js", "npm:@myorg/validators"],
       type: "string",
     },
+    arguments: {
+      description:
+        "Legacy alias for parameters: bare string parameter names (state may be listed " +
+        "explicitly as the first name). Superseded by parameters.",
+      examples: [["state", "event"]],
+      items: { type: "string" },
+      type: "array",
+    },
     body: {
       description:
         "Inline function body: an opaque JS source string (first implicit parameter is state), or a structured statement array (spec §20) — explicit structured function declaration, analyzable by tooling and editable visually. The escalation ladder within the shape is structured statements → JS string.",

package/defs/index.ts

@@ -69,12 +69,16 @@ export {
 
 // Class definitions
 export {
+  CLASS_METHOD_ROLES,
   classParameterDefSchema,
   classFieldDefSchema,
   classConstructorDefSchema,
   classMethodDefSchema,
   classDefSchema,
+  connectorBlockDefSchema,
   formatDefSchema,
+  projectBlockDefSchema,
+  serverBlockDefSchema,
   studioHintsSchema,
 } from "./class-def.schema";
 

package/defs/project-config.schema.ts

@@ -233,11 +233,12 @@ export const projectConfigSchema = {
     },
     style: {
       additionalProperties: {
-        oneOf: [{ type: "string" }, { type: "number" }, { type: "object" }],
+        oneOf: [{ type: "string" }, { type: "number" }, { $ref: "#/$defs/StyleObject" }],
       },
       description:
         "Global CSS styles applied to the <body> element. " +
-        "Uses the same camelCase CSSOM convention as component styles.",
+        "Uses the same camelCase CSSOM convention and recursive selector/at-rule " +
+        "nesting as component styles.",
       type: "object",
     },
     url: {

package/defs/style-object.schema.ts

@@ -1,19 +1,13 @@
 export const styleObjectSchema = {
   additionalProperties: {
-    oneOf: [
-      { type: "string" },
-      { type: "number" },
-      {
-        additionalProperties: { oneOf: [{ type: "string" }, { type: "number" }] },
-        description: "Nested CSS selector or media breakpoint rules.",
-        type: "object",
-      },
-    ],
+    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 are treated as responsive rules.",
+    "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",
 } as const;

package/package.json

@@ -50,7 +50,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -58,6 +58,24 @@
         }
       },
       "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"
     }
   },
   "$id": "https://jxsuite.com/schema/project/v1",
@@ -360,11 +378,11 @@
             "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": {