@jxsuite/schema 0.27.0 → 0.28.0

package/class-schema.json

@@ -60,6 +60,12 @@
         "./lib/calculator.js"
       ]
     },
+    "format": {
+      "$ref": "#/$defs/FormatDef"
+    },
+    "$studio": {
+      "$ref": "#/$defs/StudioHints"
+    },
     "$defs": {
       "description": "Class members: parameters, returnTypes, fields, constructor, methods.",
       "type": "object",
@@ -229,14 +235,18 @@
       }
     },
     "ClassMethodDef": {
-      "description": "A class method or accessor definition.",
+      "description": "A class method or accessor definition. Capability roles (parse, serialize, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
       "type": "object",
       "properties": {
         "role": {
           "type": "string",
           "enum": [
             "method",
-            "accessor"
+            "accessor",
+            "parse",
+            "serialize",
+            "discover",
+            "load"
           ]
         },
         "$prototype": {
@@ -261,6 +271,18 @@
         "identifier": {
           "type": "string"
         },
+        "timing": {
+          "description": "Execution environments allowed to call this capability directly. Hosts outside the list round-trip through the dev server.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "compiler",
+              "server",
+              "client"
+            ]
+          }
+        },
         "parameters": {
           "type": "array",
           "items": {
@@ -320,6 +342,146 @@
           "type": "string"
         }
       }
+    },
+    "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.",
+      "type": "object",
+      "required": [
+        "extensions"
+      ],
+      "properties": {
+        "extensions": {
+          "description": "File extensions this format claims, with leading dot (e.g. [\".md\"]).",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\."
+          },
+          "minItems": 1
+        },
+        "mediaType": {
+          "description": "MIME type for the format (icons, labels, HTTP).",
+          "type": "string"
+        },
+        "documentKinds": {
+          "description": "\"page\"/\"component\" allow the extension in pages/components discovery; \"content\" allows it as a content-type source.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "page",
+              "component",
+              "content"
+            ]
+          }
+        },
+        "exportTarget": {
+          "description": "When true, site builds emit a serialized sidecar per page in this format.",
+          "type": "boolean"
+        },
+        "remote": {
+          "description": "When true, the load capability accepts http(s) URLs as sources.",
+          "type": "boolean"
+        }
+      }
+    },
+    "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.",
+      "type": "object",
+      "properties": {
+        "icon": {
+          "type": "string"
+        },
+        "modes": {
+          "description": "Editor modes the studio offers for documents of this format.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "documentMode": {
+          "type": "object",
+          "properties": {
+            "default": {
+              "type": "string",
+              "enum": [
+                "content",
+                "component"
+              ]
+            },
+            "componentWhen": {
+              "description": "Treat the document as a component when this top-level/frontmatter key matches the regex.",
+              "type": "object",
+              "properties": {
+                "frontmatterKey": {
+                  "type": "string"
+                },
+                "matches": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "newFileTemplate": {
+          "description": "Initial source text for newly created files of this format.",
+          "type": "string"
+        },
+        "elements": {
+          "description": "Element allowlist and nesting constraints for structural editing.",
+          "type": "object",
+          "properties": {
+            "block": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "inline": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "void": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "textOnly": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "nesting": {
+              "description": "Per-parent child rules keyed by tag (or \"_root\"): { block, inline, directive } booleans or { only: [tags] }.",
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "block": {
+                    "type": "boolean"
+                  },
+                  "inline": {
+                    "type": "boolean"
+                  },
+                  "directive": {
+                    "type": "boolean"
+                  },
+                  "only": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

package/defs/class-def.schema.ts

@@ -69,14 +69,26 @@ export const classConstructorDefSchema = {
 } as const;
 
 export const classMethodDefSchema = {
-  description: "A class method or accessor definition.",
+  description:
+    "A class method or accessor definition. Capability roles (parse, serialize, discover, load) " +
+    "mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
   type: "object",
   properties: {
-    role: { type: "string", enum: ["method", "accessor"] },
+    role: {
+      type: "string",
+      enum: ["method", "accessor", "parse", "serialize", "discover", "load"],
+    },
     $prototype: { type: "string", const: "Function" },
     access: { type: "string", enum: ["public", "private", "protected"] },
     scope: { type: "string", enum: ["instance", "static"] },
     identifier: { type: "string" },
+    timing: {
+      description:
+        "Execution environments allowed to call this capability directly. " +
+        "Hosts outside the list round-trip through the dev server.",
+      type: "array",
+      items: { type: "string", enum: ["compiler", "server", "client"] },
+    },
     parameters: {
       type: "array",
       items: {
@@ -110,6 +122,100 @@ export const classMethodDefSchema = {
   },
 } as const;
 
+export const formatDefSchema = {
+  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.",
+  type: "object",
+  required: ["extensions"],
+  properties: {
+    extensions: {
+      description: 'File extensions this format claims, with leading dot (e.g. [".md"]).',
+      type: "array",
+      items: { type: "string", pattern: "^\\." },
+      minItems: 1,
+    },
+    mediaType: {
+      description: "MIME type for the format (icons, labels, HTTP).",
+      type: "string",
+    },
+    documentKinds: {
+      description:
+        '"page"/"component" allow the extension in pages/components discovery; ' +
+        '"content" allows it as a content-type source.',
+      type: "array",
+      items: { type: "string", enum: ["page", "component", "content"] },
+    },
+    exportTarget: {
+      description: "When true, site builds emit a serialized sidecar per page in this format.",
+      type: "boolean",
+    },
+    remote: {
+      description: "When true, the load capability accepts http(s) URLs as sources.",
+      type: "boolean",
+    },
+  },
+} as const;
+
+export const studioHintsSchema = {
+  description:
+    "Studio control-surface hints for a format class: editor modes, document-mode rules, " +
+    "templates, and the element/nesting constraints that gate structural editing.",
+  type: "object",
+  properties: {
+    icon: { type: "string" },
+    modes: {
+      description: "Editor modes the studio offers for documents of this format.",
+      type: "array",
+      items: { type: "string" },
+    },
+    documentMode: {
+      type: "object",
+      properties: {
+        default: { type: "string", enum: ["content", "component"] },
+        componentWhen: {
+          description:
+            "Treat the document as a component when this top-level/frontmatter key matches the regex.",
+          type: "object",
+          properties: {
+            frontmatterKey: { type: "string" },
+            matches: { type: "string" },
+          },
+        },
+      },
+    },
+    newFileTemplate: {
+      description: "Initial source text for newly created files of this format.",
+      type: "string",
+    },
+    elements: {
+      description: "Element allowlist and nesting constraints for structural editing.",
+      type: "object",
+      properties: {
+        block: { type: "array", items: { type: "string" } },
+        inline: { type: "array", items: { type: "string" } },
+        void: { type: "array", items: { type: "string" } },
+        textOnly: { type: "array", items: { type: "string" } },
+        nesting: {
+          description:
+            'Per-parent child rules keyed by tag (or "_root"): ' +
+            "{ block, inline, directive } booleans or { only: [tags] }.",
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            properties: {
+              block: { type: "boolean" },
+              inline: { type: "boolean" },
+              directive: { type: "boolean" },
+              only: { type: "array", items: { type: "string" } },
+            },
+          },
+        },
+      },
+    },
+  },
+} as const;
+
 export const classDefSchema = {
   description:
     'A .class.json schema-defined class. $prototype must be "Class". ' +
@@ -126,6 +232,8 @@ export const classDefSchema = {
       type: "string",
     },
     description: { type: "string" },
+    format: { $ref: "#/$defs/FormatDef" },
+    $studio: { $ref: "#/$defs/StudioHints" },
     extends: {
       description: "Base class — string name or $ref to another .class.json.",
       oneOf: [

package/defs/content-type-def.schema.ts

@@ -9,8 +9,11 @@ export const contentTypeDefSchema = {
       examples: ["./content/blog/", "./content/docs/"],
     },
     format: {
+      description:
+        "Import name of a format class declared in the project imports map " +
+        '(e.g. "Markdown", "Csv"). When omitted, the format is derived from the ' +
+        'source file extension via the format registry. "json" is the only built-in.',
       type: "string",
-      enum: ["md", "json", "csv", "yaml"],
     },
     schema: {
       description: "JSON Schema for validating frontmatter of content type entries.",

package/defs/image-config.schema.ts

@@ -16,5 +16,15 @@ export const imageConfigSchema = {
     },
     sizes: { type: "string" },
     lazyLoad: { type: "boolean" },
+    service: { type: "string", enum: ["build", "cloudflare"] },
+    binding: { type: "string" },
+    remoteDomains: {
+      description:
+        "Hostnames whose remote (https) images are optimized through the /_jx/image endpoint " +
+        '(cloudflare service only), e.g. ["drive.usercontent.google.com"]. Remote sources from ' +
+        "other hosts are left untouched.",
+      type: "array",
+      items: { type: "string" },
+    },
   },
 } as const;

package/defs/index.ts

@@ -69,6 +69,8 @@ export {
   classConstructorDefSchema,
   classMethodDefSchema,
   classDefSchema,
+  formatDefSchema,
+  studioHintsSchema,
 } from "./class-def.schema";
 
 // Content & project

package/defs/project-config.schema.ts

@@ -88,7 +88,7 @@ export const projectConfigSchema = {
       additionalProperties: { type: "string" },
       examples: [
         {
-          MarkdownFile: "@jxsuite/parser/MarkdownFile.class.json",
+          Markdown: "@jxsuite/parser/Markdown.class.json",
           MarkdownCollection: "@jxsuite/parser/MarkdownCollection.class.json",
         },
       ],

package/package.json

@@ -7,6 +7,7 @@
   "description": "JSON Schema 2020-12 meta-schema generator for Jx documents",
   "exports": {
     ".": "./src/schema.ts",
+    "./format-registry": "./src/format-registry.ts",
     "./types": "./types.ts",
     "./defs": "./defs/index.ts",
     "./schema.json": "./schema.json",
@@ -36,7 +37,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/project-schema.json

@@ -120,7 +120,7 @@
       },
       "examples": [
         {
-          "MarkdownFile": "@jxsuite/parser/MarkdownFile.class.json",
+          "Markdown": "@jxsuite/parser/Markdown.class.json",
           "MarkdownCollection": "@jxsuite/parser/MarkdownCollection.class.json"
         }
       ]
@@ -311,6 +311,23 @@
         },
         "lazyLoad": {
           "type": "boolean"
+        },
+        "service": {
+          "type": "string",
+          "enum": [
+            "build",
+            "cloudflare"
+          ]
+        },
+        "binding": {
+          "type": "string"
+        },
+        "remoteDomains": {
+          "description": "Hostnames whose remote (https) images are optimized through the /_jx/image endpoint (cloudflare service only), e.g. [\"drive.usercontent.google.com\"]. Remote sources from other hosts are left untouched.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
@@ -327,13 +344,8 @@
           ]
         },
         "format": {
-          "type": "string",
-          "enum": [
-            "md",
-            "json",
-            "csv",
-            "yaml"
-          ]
+          "description": "Import name of a format class declared in the project imports map (e.g. \"Markdown\", \"Csv\"). When omitted, the format is derived from the source file extension via the format registry. \"json\" is the only built-in.",
+          "type": "string"
         },
         "schema": {
           "description": "JSON Schema for validating frontmatter of content type entries.",

package/schema.json

@@ -458,6 +458,12 @@
         "description": {
           "type": "string"
         },
+        "format": {
+          "$ref": "#/$defs/FormatDef"
+        },
+        "$studio": {
+          "$ref": "#/$defs/StudioHints"
+        },
         "extends": {
           "description": "Base class — string name or $ref to another .class.json.",
           "oneOf": [
@@ -650,14 +656,18 @@
       }
     },
     "ClassMethodDef": {
-      "description": "A class method or accessor definition.",
+      "description": "A class method or accessor definition. Capability roles (parse, serialize, discover, load) mark static methods that hosts (compiler, server, studio) invoke for format dispatch.",
       "type": "object",
       "properties": {
         "role": {
           "type": "string",
           "enum": [
             "method",
-            "accessor"
+            "accessor",
+            "parse",
+            "serialize",
+            "discover",
+            "load"
           ]
         },
         "$prototype": {
@@ -682,6 +692,18 @@
         "identifier": {
           "type": "string"
         },
+        "timing": {
+          "description": "Execution environments allowed to call this capability directly. Hosts outside the list round-trip through the dev server.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "compiler",
+              "server",
+              "client"
+            ]
+          }
+        },
         "parameters": {
           "type": "array",
           "items": {
@@ -742,6 +764,146 @@
         }
       }
     },
+    "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.",
+      "type": "object",
+      "required": [
+        "extensions"
+      ],
+      "properties": {
+        "extensions": {
+          "description": "File extensions this format claims, with leading dot (e.g. [\".md\"]).",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\."
+          },
+          "minItems": 1
+        },
+        "mediaType": {
+          "description": "MIME type for the format (icons, labels, HTTP).",
+          "type": "string"
+        },
+        "documentKinds": {
+          "description": "\"page\"/\"component\" allow the extension in pages/components discovery; \"content\" allows it as a content-type source.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "page",
+              "component",
+              "content"
+            ]
+          }
+        },
+        "exportTarget": {
+          "description": "When true, site builds emit a serialized sidecar per page in this format.",
+          "type": "boolean"
+        },
+        "remote": {
+          "description": "When true, the load capability accepts http(s) URLs as sources.",
+          "type": "boolean"
+        }
+      }
+    },
+    "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.",
+      "type": "object",
+      "properties": {
+        "icon": {
+          "type": "string"
+        },
+        "modes": {
+          "description": "Editor modes the studio offers for documents of this format.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "documentMode": {
+          "type": "object",
+          "properties": {
+            "default": {
+              "type": "string",
+              "enum": [
+                "content",
+                "component"
+              ]
+            },
+            "componentWhen": {
+              "description": "Treat the document as a component when this top-level/frontmatter key matches the regex.",
+              "type": "object",
+              "properties": {
+                "frontmatterKey": {
+                  "type": "string"
+                },
+                "matches": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "newFileTemplate": {
+          "description": "Initial source text for newly created files of this format.",
+          "type": "string"
+        },
+        "elements": {
+          "description": "Element allowlist and nesting constraints for structural editing.",
+          "type": "object",
+          "properties": {
+            "block": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "inline": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "void": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "textOnly": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "nesting": {
+              "description": "Per-parent child rules keyed by tag (or \"_root\"): { block, inline, directive } booleans or { only: [tags] }.",
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": {
+                  "block": {
+                    "type": "boolean"
+                  },
+                  "inline": {
+                    "type": "boolean"
+                  },
+                  "directive": {
+                    "type": "boolean"
+                  },
+                  "only": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "ExternalClassDef": {
       "description": "An external class / data source. $prototype is a constructor name (not \"Function\"). When $prototype is not in the built-in registry, $src is required. All state entries are reactive by default.",
       "type": "object",
@@ -21611,6 +21773,23 @@
         },
         "lazyLoad": {
           "type": "boolean"
+        },
+        "service": {
+          "type": "string",
+          "enum": [
+            "build",
+            "cloudflare"
+          ]
+        },
+        "binding": {
+          "type": "string"
+        },
+        "remoteDomains": {
+          "description": "Hostnames whose remote (https) images are optimized through the /_jx/image endpoint (cloudflare service only), e.g. [\"drive.usercontent.google.com\"]. Remote sources from other hosts are left untouched.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       }
     },
@@ -21627,13 +21806,8 @@
           ]
         },
         "format": {
-          "type": "string",
-          "enum": [
-            "md",
-            "json",
-            "csv",
-            "yaml"
-          ]
+          "description": "Import name of a format class declared in the project imports map (e.g. \"Markdown\", \"Csv\"). When omitted, the format is derived from the source file extension via the format registry. \"json\" is the only built-in.",
+          "type": "string"
         },
         "schema": {
           "description": "JSON Schema for validating frontmatter of content type entries.",

package/src/format-registry.ts

@@ -0,0 +1,271 @@
+/**
+ * Format registry — auto-discovery of format-extension classes from a project imports map.
+ *
+ * A class participates in format dispatch iff its .class.json carries a top-level `format` block.
+ * Hosts (compiler, server, studio) build a registry from the project-level imports map and dispatch
+ * file-extension work (parse, serialize, discover, load) through it. `.json` is the single native
+ * built-in and never appears in a registry.
+ *
+ * All I/O is injected via FormatHostIO so the same module serves node (fs + import) and browser
+ * (fetch + dynamic import) hosts.
+ */
+
+export type FormatCapability = "parse" | "serialize" | "discover" | "load";
+
+export const FORMAT_CAPABILITIES: readonly FormatCapability[] = [
+  "parse",
+  "serialize",
+  "discover",
+  "load",
+];
+
+export type FormatTiming = "compiler" | "server" | "client";
+
+export type FormatDocumentKind = "page" | "component" | "content";
+
+export interface FormatBlock {
+  extensions: string[];
+  mediaType?: string;
+  documentKinds?: FormatDocumentKind[];
+  exportTarget?: boolean;
+  remote?: boolean;
+}
+
+export interface StudioHints {
+  icon?: string;
+  modes?: string[];
+  documentMode?: {
+    default?: "content" | "component";
+    componentWhen?: { frontmatterKey?: string; matches?: string };
+  };
+  newFileTemplate?: string;
+  elements?: {
+    block?: string[];
+    inline?: string[];
+    void?: string[];
+    textOnly?: string[];
+    nesting?: Record<
+      string,
+      {
+        block?: boolean;
+        inline?: boolean;
+        directive?: boolean;
+        only?: string[];
+      }
+    >;
+  };
+  [key: string]: unknown;
+}
+
+export interface CapabilityInfo {
+  /** Static method name on the implementation class. */
+  identifier: string;
+  /** Environments allowed to call directly; others round-trip via the dev server. */
+  timing: FormatTiming[];
+}
+
+export interface FormatHostIO {
+  /** Read and parse a JSON file or URL. */
+  loadJson(pathOrUrl: string): Promise<Record<string, unknown>>;
+  /** Import a JS module by path or URL. */
+  importModule(pathOrUrl: string): Promise<Record<string, unknown>>;
+  /** Resolve a relative reference against a base (node: path.resolve; browser: new URL). */
+  resolvePath(base: string, ref: string): string;
+}
+
+interface ClassMethodLike {
+  role?: string;
+  identifier?: string;
+  scope?: string;
+  timing?: string[];
+}
+
+interface ClassDefLike {
+  title?: string;
+  $implementation?: string;
+  format?: FormatBlock;
+  $studio?: StudioHints;
+  $defs?: { methods?: Record<string, ClassMethodLike> };
+  [key: string]: unknown;
+}
+
+const DEFAULT_TIMING: FormatTiming[] = ["compiler", "server"];
+
+export class FormatEntry {
+  readonly name: string;
+  readonly classPath: string;
+  readonly classDef: ClassDefLike;
+  readonly extensions: string[];
+  readonly mediaType: string | null;
+  readonly documentKinds: FormatDocumentKind[];
+  readonly exportTarget: boolean;
+  readonly remote: boolean;
+  readonly studio: StudioHints | null;
+  readonly capabilities: Partial<Record<FormatCapability, CapabilityInfo>>;
+
+  #io: FormatHostIO;
+  #implementation: Promise<Record<string, unknown>> | null = null;
+
+  constructor(name: string, classPath: string, classDef: ClassDefLike, io: FormatHostIO) {
+    this.name = name;
+    this.classPath = classPath;
+    this.classDef = classDef;
+    this.#io = io;
+
+    const format = classDef.format as FormatBlock;
+    this.extensions = (format.extensions ?? []).map((e) => e.toLowerCase());
+    this.mediaType = format.mediaType ?? null;
+    this.documentKinds = format.documentKinds ?? [];
+    this.exportTarget = format.exportTarget === true;
+    this.remote = format.remote === true;
+    this.studio = classDef.$studio ?? null;
+    this.capabilities = extractCapabilities(classDef);
+  }
+
+  /** Import (and cache) the class's $implementation module. */
+  implementation(): Promise<Record<string, unknown>> {
+    if (!this.#implementation) {
+      const impl = this.classDef.$implementation;
+      if (!impl) {
+        return Promise.reject(
+          new Error(`Format class "${this.name}" has no $implementation to import`),
+        );
+      }
+      this.#implementation = this.#io.importModule(this.#io.resolvePath(this.classPath, impl));
+    }
+    return this.#implementation;
+  }
+
+  /** Invoke a capability's static method on the implementation class. */
+  async call(capability: FormatCapability, ...args: unknown[]): Promise<unknown> {
+    const cap = this.capabilities[capability];
+    if (!cap) {
+      throw new Error(`Format class "${this.name}" does not declare a "${capability}" capability`);
+    }
+    const mod = await this.implementation();
+    const title = this.classDef.title ?? this.name;
+    const Cls = (mod[title] ?? (mod.default as Record<string, unknown>)?.[title] ?? mod.default) as
+      | Record<string, unknown>
+      | undefined;
+    const fn = Cls?.[cap.identifier];
+    if (typeof fn !== "function") {
+      throw new Error(
+        `Format class "${this.name}": implementation export "${title}" has no static "${cap.identifier}" method`,
+      );
+    }
+    return await fn.call(Cls, ...args);
+  }
+}
+
+export class FormatRegistry {
+  #entries: FormatEntry[];
+
+  constructor(entries: FormatEntry[]) {
+    this.#entries = entries;
+
+    // Ambiguous (extension, capability) claims are a configuration error.
+    for (const cap of FORMAT_CAPABILITIES) {
+      const seen = new Map<string, FormatEntry>();
+      for (const entry of entries) {
+        if (!entry.capabilities[cap]) continue;
+        for (const ext of entry.extensions) {
+          const prior = seen.get(ext);
+          if (prior) {
+            throw new Error(
+              `Format conflict: "${prior.name}" and "${entry.name}" both claim "${ext}" with the "${cap}" capability`,
+            );
+          }
+          seen.set(ext, entry);
+        }
+      }
+    }
+  }
+
+  get entries(): readonly FormatEntry[] {
+    return this.#entries;
+  }
+
+  /** Look up the format claiming an extension, optionally requiring a capability. */
+  byExtension(ext: string, capability?: FormatCapability): FormatEntry | undefined {
+    const norm = normalizeExt(ext);
+    return this.#entries.find(
+      (e) => e.extensions.includes(norm) && (!capability || e.capabilities[capability]),
+    );
+  }
+
+  byName(name: string): FormatEntry | undefined {
+    return this.#entries.find((e) => e.name === name);
+  }
+
+  withCapability(capability: FormatCapability): FormatEntry[] {
+    return this.#entries.filter((e) => e.capabilities[capability]);
+  }
+
+  /**
+   * All registered extensions, optionally filtered by document kind. Never includes ".json" — JSON
+   * is the native built-in, handled inline by hosts.
+   */
+  documentExtensions(kind?: FormatDocumentKind): string[] {
+    const exts = new Set<string>();
+    for (const entry of this.#entries) {
+      if (kind && !entry.documentKinds.includes(kind)) continue;
+      for (const ext of entry.extensions) exts.add(ext);
+    }
+    exts.delete(".json");
+    return [...exts];
+  }
+
+  has(ext: string): boolean {
+    const norm = normalizeExt(ext);
+    return this.#entries.some((e) => e.extensions.includes(norm));
+  }
+}
+
+/**
+ * Build a registry by scanning an imports map ({name: path}) for format classes.
+ *
+ * Only values ending in ".class.json" are inspected; other imports (layouts, components) are
+ * skipped, as are class files that fail to load or carry no `format` block.
+ */
+export async function buildFormatRegistry(
+  imports: Record<string, string> | undefined,
+  io: FormatHostIO,
+  base?: string,
+): Promise<FormatRegistry> {
+  const entries: FormatEntry[] = [];
+  for (const [name, ref] of Object.entries(imports ?? {})) {
+    if (typeof ref !== "string" || !ref.endsWith(".class.json")) continue;
+    const classPath = base ? io.resolvePath(base, ref) : ref;
+    let classDef: ClassDefLike;
+    try {
+      classDef = (await io.loadJson(classPath)) as ClassDefLike;
+    } catch {
+      continue; // unreadable imports are not format classes
+    }
+    if (!classDef || typeof classDef !== "object") continue;
+    if (!classDef.format || !Array.isArray(classDef.format.extensions)) continue;
+    entries.push(new FormatEntry(name, classPath, classDef, io));
+  }
+  return new FormatRegistry(entries);
+}
+
+function extractCapabilities(
+  classDef: ClassDefLike,
+): Partial<Record<FormatCapability, CapabilityInfo>> {
+  const out: Partial<Record<FormatCapability, CapabilityInfo>> = {};
+  const methods = classDef.$defs?.methods ?? {};
+  for (const [key, method] of Object.entries(methods)) {
+    const role = method.role as FormatCapability | undefined;
+    if (!role || !FORMAT_CAPABILITIES.includes(role)) continue;
+    out[role] = {
+      identifier: method.identifier ?? key,
+      timing: (method.timing as FormatTiming[] | undefined) ?? DEFAULT_TIMING,
+    };
+  }
+  return out;
+}
+
+function normalizeExt(ext: string): string {
+  const lower = ext.toLowerCase();
+  return lower.startsWith(".") ? lower : `.${lower}`;
+}

package/src/schema.ts

@@ -87,6 +87,8 @@ import {
   classConstructorDefSchema,
   classMethodDefSchema,
   classDefSchema,
+  formatDefSchema,
+  studioHintsSchema,
 } from "../defs/class-def.schema";
 import { contentTypeDefSchema } from "../defs/content-type-def.schema";
 import { imageConfigSchema } from "../defs/image-config.schema";
@@ -305,6 +307,8 @@ export async function generateSchema() {
       ClassFieldDef: classFieldDefSchema,
       ClassConstructorDef: classConstructorDefSchema,
       ClassMethodDef: classMethodDefSchema,
+      FormatDef: formatDefSchema,
+      StudioHints: studioHintsSchema,
       ExternalClassDef: externalClassDefSchema,
       ExpressionPointer: expressionPointerSchema,
       ExpressionLiteral: expressionLiteralSchema,
@@ -431,6 +435,8 @@ export function generateClassSchema() {
         type: "string",
         examples: ["./md.js", "./lib/calculator.js"],
       },
+      format: { $ref: "#/$defs/FormatDef" },
+      $studio: { $ref: "#/$defs/StudioHints" },
       $defs: {
         description: "Class members: parameters, returnTypes, fields, constructor, methods.",
         type: "object",
@@ -465,6 +471,8 @@ export function generateClassSchema() {
       ClassFieldDef: classFieldDefSchema,
       ClassConstructorDef: classConstructorDefSchema,
       ClassMethodDef: classMethodDefSchema,
+      FormatDef: formatDefSchema,
+      StudioHints: studioHintsSchema,
     },
   };
 }

package/types.ts

@@ -71,6 +71,9 @@ export interface ImageConfig {
   quality?: { webp?: number; avif?: number; jpeg?: number; png?: number };
   sizes?: string;
   lazyLoad?: boolean;
+  service?: "build" | "cloudflare";
+  binding?: string;
+  remoteDomains?: string[];
 }
 
 export type CemParameter = FromSchema<typeof cemParameterSchema>;