{"version":1,"engine":"minisearch","fields":["title","heading","text"],"boost":{"title":4,"heading":2},"documents":[{"id":"docs:extending","collection":"docs","slug":"extending","url":"/docs/extending/","title":"Extending","description":"Extend Jx with custom formats, classes, project sections, and server mounts — or embed Studio on your own backend.","heading":"","text":"Extending Jx is built to be extended. First-party extensions (the Markdown parser, the data connector, auth) use only the public extension hooks — anything they can do, your extension can do. Studio itself is an embeddable app: any backend that speaks its protocol can host it. This section covers both directions, plus how to work on Jx itself. Extensions An extension is an npm package that contributes formats, classes, capability methods, project settings sections, server mounts, and data connectors to a Jx project. Start with the anatomy of an extension , then go deep on the individual contribution points: schema composition , classes , formats , capabilities , project sections , server mounts , connectors , and the security model . Two tutorials build one end-to-end — a TOML format and a guestbook with server routes and a connector — and the first-party extensions are the reference implementations to crib from. Embedding Studio Studio is backend-agnostic: all of its file, git, and project operations go through a platform-adapter layer, and every adapter ultimately speaks one wire contract, the Studio Backend Protocol. The embedding overview maps the landscape and helps you pick an integration path; writing a platform adapter covers the in-page StudioPlatform interface; the backend protocol defines the contract any backend can serve, with every endpoint listed in the protocol route reference ; and dev server internals walks through the reference implementation. Contributing To work on Jx itself, working in the monorepo covers the repository layout, test and coverage policy, and the tooling conventions; contributing to these docs is the style guide every page in /docs follows."},{"id":"docs:extending#extending","collection":"docs","slug":"extending","url":"/docs/extending/#extending","title":"Extending","description":"Extend Jx with custom formats, classes, project sections, and server mounts — or embed Studio on your own backend.","heading":"Extending","text":"Jx is built to be extended. First-party extensions (the Markdown parser, the data connector, auth) use only the public extension hooks — anything they can do, your extension can do. Studio itself is an embeddable app: any backend that speaks its protocol can host it. This section covers both directions, plus how to work on Jx itself."},{"id":"docs:extending#extensions","collection":"docs","slug":"extending","url":"/docs/extending/#extensions","title":"Extending","description":"Extend Jx with custom formats, classes, project sections, and server mounts — or embed Studio on your own backend.","heading":"Extensions","text":"An extension is an npm package that contributes formats, classes, capability methods, project settings sections, server mounts, and data connectors to a Jx project. Start with the anatomy of an extension , then go deep on the individual contribution points: schema composition , classes , formats , capabilities , project sections , server mounts , connectors , and the security model . Two tutorials build one end-to-end — a TOML format and a guestbook with server routes and a connector — and the first-party extensions are the reference implementations to crib from."},{"id":"docs:extending#embedding-studio","collection":"docs","slug":"extending","url":"/docs/extending/#embedding-studio","title":"Extending","description":"Extend Jx with custom formats, classes, project sections, and server mounts — or embed Studio on your own backend.","heading":"Embedding Studio","text":"Studio is backend-agnostic: all of its file, git, and project operations go through a platform-adapter layer, and every adapter ultimately speaks one wire contract, the Studio Backend Protocol. The embedding overview maps the landscape and helps you pick an integration path; writing a platform adapter covers the in-page StudioPlatform interface; the backend protocol defines the contract any backend can serve, with every endpoint listed in the protocol route reference ; and dev server internals walks through the reference implementation."},{"id":"docs:extending#contributing","collection":"docs","slug":"extending","url":"/docs/extending/#contributing","title":"Extending","description":"Extend Jx with custom formats, classes, project sections, and server mounts — or embed Studio on your own backend.","heading":"Contributing","text":"To work on Jx itself, working in the monorepo covers the repository layout, test and coverage policy, and the tooling conventions; contributing to these docs is the style guide every page in /docs follows."},{"id":"docs:framework","collection":"docs","slug":"framework","url":"/docs/framework/","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"","text":"Framework This is the conceptual foundation beneath Jx Studio . You never have to read it to build with Studio — but if you want to know exactly what the format is, start here. Jx is a schema and runtime for building reactive web applications using plain JSON. A Jx application is a tree of JSON objects whose structure mirrors the DOM API, whose reactivity is powered by @vue/reactivity , and whose behavior is declared in state entries. Core Premise Structure and state are data. The shape of each state entry determines its type and behavior — no additional flags required in the common case. A Jx component is a single .json file that can be fully self-describing: { \"$id\" : \"Counter\" , \"state\" : { \"count\" : 0 , \"increment\" : { \"$prototype\" : \"Function\" , \"body\" : \"state.count++\" } }, \"tagName\" : \"my-counter\" , \"children\" : [ { \"tagName\" : \"span\" , \"textContent\" : \"${state.count}\" }, { \"tagName\" : \"button\" , \"textContent\" : \"+\" , \"onclick\" : { \"$ref\" : \"#/state/increment\" } } ] } Design Principles DOM-First Design — Property names mirror standard DOM element properties. tagName , className , textContent , hidden , tabIndex all map directly to their DOM equivalents. Rule of Least Power — Declarative JSON over imperative JavaScript wherever possible. $ref bindings over template expressions. Template expressions over handler functions. Handler functions only when logic cannot be expressed otherwise. JSON as the Authoritative Format — Documents are valid JSON. Fully serializable. No this ambiguity. Natively understood by visual builders, IDEs, validators, and bundlers. Explicit Over Implicit — Signal scope does not leak across component boundaries. Every dependency must be explicitly declared as a $prop . Standards Alignment — Where a web platform standard exists, Jx follows it: JSON Schema 2020-12, JSON Pointer (RFC 6901), Web Components v1, CSSOM camelCase. Document Format Every Jx document has these top-level fields: Field Required Description $schema Recommended URI identifying the Jx dialect version $id Recommended Component identifier $defs Optional Pure JSON Schema type definitions (tooling only) state Optional Reactive state: signals, computed values, functions tagName Required HTML tag name for the root element children Optional Array of child element definitions and/or text nodes Reserved Keywords Keyword Purpose $schema Dialect identifier $id Component identifier $defs JSON Schema type definitions $ref Reference pointer (JSON Pointer, RFC 6901) $props Explicit prop passing at component boundary $prototype Constructor name — Web API, \"Function\" , or class $src External module specifier $switch Dynamic component switching $map Iteration context namespace $media Named media breakpoint declarations $elements Custom element dependency declarations timing Execution timing: \"compiler\" , \"server\" , \"client\" For the complete specification, see the full spec document ."},{"id":"docs:framework#framework","collection":"docs","slug":"framework","url":"/docs/framework/#framework","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"Framework","text":"This is the conceptual foundation beneath Jx Studio . You never have to read it to build with Studio — but if you want to know exactly what the format is, start here. Jx is a schema and runtime for building reactive web applications using plain JSON. A Jx application is a tree of JSON objects whose structure mirrors the DOM API, whose reactivity is powered by @vue/reactivity , and whose behavior is declared in state entries."},{"id":"docs:framework#core-premise","collection":"docs","slug":"framework","url":"/docs/framework/#core-premise","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"Core Premise","text":"Structure and state are data. The shape of each state entry determines its type and behavior — no additional flags required in the common case. A Jx component is a single .json file that can be fully self-describing: { \"$id\" : \"Counter\" , \"state\" : { \"count\" : 0 , \"increment\" : { \"$prototype\" : \"Function\" , \"body\" : \"state.count++\" } }, \"tagName\" : \"my-counter\" , \"children\" : [ { \"tagName\" : \"span\" , \"textContent\" : \"${state.count}\" }, { \"tagName\" : \"button\" , \"textContent\" : \"+\" , \"onclick\" : { \"$ref\" : \"#/state/increment\" } } ] }"},{"id":"docs:framework#design-principles","collection":"docs","slug":"framework","url":"/docs/framework/#design-principles","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"Design Principles","text":"DOM-First Design — Property names mirror standard DOM element properties. tagName , className , textContent , hidden , tabIndex all map directly to their DOM equivalents. Rule of Least Power — Declarative JSON over imperative JavaScript wherever possible. $ref bindings over template expressions. Template expressions over handler functions. Handler functions only when logic cannot be expressed otherwise. JSON as the Authoritative Format — Documents are valid JSON. Fully serializable. No this ambiguity. Natively understood by visual builders, IDEs, validators, and bundlers. Explicit Over Implicit — Signal scope does not leak across component boundaries. Every dependency must be explicitly declared as a $prop . Standards Alignment — Where a web platform standard exists, Jx follows it: JSON Schema 2020-12, JSON Pointer (RFC 6901), Web Components v1, CSSOM camelCase."},{"id":"docs:framework#document-format","collection":"docs","slug":"framework","url":"/docs/framework/#document-format","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"Document Format","text":"Every Jx document has these top-level fields: Field Required Description $schema Recommended URI identifying the Jx dialect version $id Recommended Component identifier $defs Optional Pure JSON Schema type definitions (tooling only) state Optional Reactive state: signals, computed values, functions tagName Required HTML tag name for the root element children Optional Array of child element definitions and/or text nodes"},{"id":"docs:framework#reserved-keywords","collection":"docs","slug":"framework","url":"/docs/framework/#reserved-keywords","title":"Framework","description":"The Jx specification: a declarative DOM format using plain JSON with reactive state, web components, and standards alignment.","heading":"Reserved Keywords","text":"Keyword Purpose $schema Dialect identifier $id Component identifier $defs JSON Schema type definitions $ref Reference pointer (JSON Pointer, RFC 6901) $props Explicit prop passing at component boundary $prototype Constructor name — Web API, \"Function\" , or class $src External module specifier $switch Dynamic component switching $map Iteration context namespace $media Named media breakpoint declarations $elements Custom element dependency declarations timing Execution timing: \"compiler\" , \"server\" , \"client\" For the complete specification, see the full spec document ."},{"id":"docs:start","collection":"docs","slug":"start","url":"/docs/start/","title":"Start here","description":"What Jx Suite is, how to install Jx Studio, and where to go first — whether you build visually or want the format underneath.","heading":"","text":"Start here Jx Suite is a visual site builder ( Jx Studio ), a JSON-native component format ( the Jx framework ), and a compiler that prerenders every page — working on plain files you own and publish with git. Sites that need more than pages get a server tier too: databases, signed-in users, and server functions compile into a small worker alongside the prebuilt output. Pick your path: Build visually. Install Jx Studio and follow Your first project to go from starter template to published site. Understand the format. The Framework section documents the JSON documents Studio writes for you — components, state, reactivity, styling, and how a site compiles. Extend it. The Extending section covers writing extensions, embedding Studio, and the backend protocol."},{"id":"docs:start#start-here","collection":"docs","slug":"start","url":"/docs/start/#start-here","title":"Start here","description":"What Jx Suite is, how to install Jx Studio, and where to go first — whether you build visually or want the format underneath.","heading":"Start here","text":"Jx Suite is a visual site builder ( Jx Studio ), a JSON-native component format ( the Jx framework ), and a compiler that prerenders every page — working on plain files you own and publish with git. Sites that need more than pages get a server tier too: databases, signed-in users, and server functions compile into a small worker alongside the prebuilt output. Pick your path: Build visually. Install Jx Studio and follow Your first project to go from starter template to published site. Understand the format. The Framework section documents the JSON documents Studio writes for you — components, state, reactivity, styling, and how a site compiles. Extend it. The Extending section covers writing extensions, embedding Studio, and the backend protocol."},{"id":"docs:studio","collection":"docs","slug":"studio","url":"/docs/studio/","title":"Studio","description":"Jx Studio is the visual builder for Jx projects — edit content inline, design on a live canvas, wire logic, and publish with git.","heading":"","text":"Studio Jx Studio is the visual builder for Jx projects. It runs on your machine — as a desktop app or in your browser against a local dev server — and edits the plain files in your project folder. Everything Studio does is organized around a few surfaces: Browse your project — pages, components, content, and media with live previews. Edit mode — inline writing on the real page, with slash commands and frontmatter forms. Design mode — a live canvas per breakpoint with a full style inspector. Logic — state, formulas, events, and data without leaving the visual editor. Databases — connect SQLite, D1, or Supabase, define tables, decide who can read and write them, and browse the rows in a grid. Publish — commit, branch, and push; your host builds and serves the site. Studio writes plain JSON and Markdown files. Everything you build here is readable, diffable, and documented in the Framework section."},{"id":"docs:studio#studio","collection":"docs","slug":"studio","url":"/docs/studio/#studio","title":"Studio","description":"Jx Studio is the visual builder for Jx projects — edit content inline, design on a live canvas, wire logic, and publish with git.","heading":"Studio","text":"Jx Studio is the visual builder for Jx projects. It runs on your machine — as a desktop app or in your browser against a local dev server — and edits the plain files in your project folder. Everything Studio does is organized around a few surfaces: Browse your project — pages, components, content, and media with live previews. Edit mode — inline writing on the real page, with slash commands and frontmatter forms. Design mode — a live canvas per breakpoint with a full style inspector. Logic — state, formulas, events, and data without leaving the visual editor. Databases — connect SQLite, D1, or Supabase, define tables, decide who can read and write them, and browse the rows in a grid. Publish — commit, branch, and push; your host builds and serves the site. Studio writes plain JSON and Markdown files. Everything you build here is readable, diffable, and documented in the Framework section."},{"id":"docs:extending/embedding","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"","text":"Embedding overview Jx Studio is one web app that runs against whatever backend hosts it. The @jxsuite/studio package contains all UI logic and imports no platform-specific modules — the same codebase ships as the desktop app, as the dev-mode editor in Chrome, and as a cloud editor in a plain browser. Everything environment-specific — file I/O, project loading, git, component discovery — is injected at startup. If you're building a backend or host for Studio, this page maps the layers and helps you pick where to plug in. The two layers Studio's backend abstraction has two layers, and you implement exactly one of them: The platform adapter (PAL) — an in-page JavaScript object implementing the StudioPlatform interface, registered via registerPlatform() before Studio boots. Every Studio operation calls the current adapter; nothing in Studio fetches a backend URL directly. The backend protocol — the wire contract behind the adapters, defined once in @jxsuite/protocol : a canonical route table plus the request/response types. The sub-path, method, and body shapes are the contract; the transport and path prefix are free. Every adapter ultimately speaks the protocol. The stock adapters differ only in transport: one speaks literal HTTP, one speaks native RPC, one speaks HTTP behind a session gateway. Who implements what today Host Platform adapter Transport Dev server ( @jxsuite/server ) packages/studio/src/platforms/devserver.ts — registered by default The literal /__studio/* HTTP routes — the protocol's reference implementation Desktop (ElectroBun / Chromium app-mode) packages/desktop/src/platform.ts Typed RPC / WebSocket JSON-RPC into the same handlers, behind a loopback-only, token-gated project server Cloud platforms packages/studio/src/platforms/cloud.ts HTTP behind a session gateway ( /api/v1/p/:owner/:repo/:branch/studio/* ), same sub-paths and shapes Choosing your integration path Serve the HTTP protocol when your backend can expose HTTP endpoints. Implement the protocol's core routes at /__studio/* (or an equivalent prefix) and reuse the stock dev-server adapter unchanged — Studio registers it automatically when no other platform is present. Your backend can be written in any language; a conformance check is just iterating the route table and asserting every core route answers. This is the least code and the path most hosted backends take. Start at the backend protocol . Implement StudioPlatform in-page when the transport isn't plain HTTP — a native RPC bridge like the desktop app's, a session gateway with its own path scheme and auth like the cloud adapter's — or when you need to own the client-side pieces the protocol can't cover. Project opening is the clearest example: it's inherently a client concern (a native file dialog on desktop, showDirectoryPicker() in Chrome, a project list on cloud), so it lives in the adapter, not on the wire. Start at writing a platform adapter . Either way, the semantics come from @jxsuite/protocol — an in-page adapter should behave exactly as the corresponding routes describe, because Studio can't tell the difference. Partial backends are fine You don't have to implement everything. Optional protocol routes back optional StudioPlatform members; Studio checks for their presence and degrades exactly as each route's degradation entry describes — the starter picker empties, the Projects catalogue hides, realtime co-editing falls back to solo file-level saves, and so on. The protocol route reference lists every route with its optionality and degradation. Related Writing a platform adapter — the StudioPlatform interface, registration, and the two real adapters The backend protocol — contract semantics, versioning, errors, and required behaviors Dev server internals — how the reference implementation is put together Protocol route reference — the generated route table"},{"id":"docs:extending/embedding#embedding-overview","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#embedding-overview","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"Embedding overview","text":"Jx Studio is one web app that runs against whatever backend hosts it. The @jxsuite/studio package contains all UI logic and imports no platform-specific modules — the same codebase ships as the desktop app, as the dev-mode editor in Chrome, and as a cloud editor in a plain browser. Everything environment-specific — file I/O, project loading, git, component discovery — is injected at startup. If you're building a backend or host for Studio, this page maps the layers and helps you pick where to plug in."},{"id":"docs:extending/embedding#the-two-layers","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#the-two-layers","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"The two layers","text":"Studio's backend abstraction has two layers, and you implement exactly one of them: The platform adapter (PAL) — an in-page JavaScript object implementing the StudioPlatform interface, registered via registerPlatform() before Studio boots. Every Studio operation calls the current adapter; nothing in Studio fetches a backend URL directly. The backend protocol — the wire contract behind the adapters, defined once in @jxsuite/protocol : a canonical route table plus the request/response types. The sub-path, method, and body shapes are the contract; the transport and path prefix are free. Every adapter ultimately speaks the protocol. The stock adapters differ only in transport: one speaks literal HTTP, one speaks native RPC, one speaks HTTP behind a session gateway."},{"id":"docs:extending/embedding#who-implements-what-today","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#who-implements-what-today","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"Who implements what today","text":"Host Platform adapter Transport Dev server ( @jxsuite/server ) packages/studio/src/platforms/devserver.ts — registered by default The literal /__studio/* HTTP routes — the protocol's reference implementation Desktop (ElectroBun / Chromium app-mode) packages/desktop/src/platform.ts Typed RPC / WebSocket JSON-RPC into the same handlers, behind a loopback-only, token-gated project server Cloud platforms packages/studio/src/platforms/cloud.ts HTTP behind a session gateway ( /api/v1/p/:owner/:repo/:branch/studio/* ), same sub-paths and shapes"},{"id":"docs:extending/embedding#choosing-your-integration-path","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#choosing-your-integration-path","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"Choosing your integration path","text":"Serve the HTTP protocol when your backend can expose HTTP endpoints. Implement the protocol's core routes at /__studio/* (or an equivalent prefix) and reuse the stock dev-server adapter unchanged — Studio registers it automatically when no other platform is present. Your backend can be written in any language; a conformance check is just iterating the route table and asserting every core route answers. This is the least code and the path most hosted backends take. Start at the backend protocol . Implement StudioPlatform in-page when the transport isn't plain HTTP — a native RPC bridge like the desktop app's, a session gateway with its own path scheme and auth like the cloud adapter's — or when you need to own the client-side pieces the protocol can't cover. Project opening is the clearest example: it's inherently a client concern (a native file dialog on desktop, showDirectoryPicker() in Chrome, a project list on cloud), so it lives in the adapter, not on the wire. Start at writing a platform adapter . Either way, the semantics come from @jxsuite/protocol — an in-page adapter should behave exactly as the corresponding routes describe, because Studio can't tell the difference."},{"id":"docs:extending/embedding#partial-backends-are-fine","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#partial-backends-are-fine","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"Partial backends are fine","text":"You don't have to implement everything. Optional protocol routes back optional StudioPlatform members; Studio checks for their presence and degrades exactly as each route's degradation entry describes — the starter picker empties, the Projects catalogue hides, realtime co-editing falls back to solo file-level saves, and so on. The protocol route reference lists every route with its optionality and degradation."},{"id":"docs:extending/embedding#related","collection":"docs","slug":"extending/embedding","url":"/docs/extending/embedding/#related","title":"Embedding overview","description":"How Jx Studio runs on any backend: the platform-adapter layer, the wire protocol behind it, and how to choose an integration path for your host.","heading":"Related","text":"Writing a platform adapter — the StudioPlatform interface, registration, and the two real adapters The backend protocol — contract semantics, versioning, errors, and required behaviors Dev server internals — how the reference implementation is put together Protocol route reference — the generated route table"},{"id":"docs:framework/agents","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"","text":"Working with agents A Jx project is a folder of JSON documents, and that one fact changes what it means to hand a website to a language model. The model edits the same pages/index.json a person edits in Studio — not a generated intermediate, not a pile of framework code standing in for the page. There is one artifact, and everybody works on it: you, Studio, and the agent. This page explains why that shape suits a model, where agents plug in, and the loop that turns a plausible answer into a checked one. Why documents are tractable where code is not Prompt-to-code tools produce programs. A program is \"correct\" only in the sense that it runs, and finding out whether it runs means executing it, in an environment, with a browser attached. A Jx document is a different kind of output: The shape is bounded. Every Jx file validates against one of three published JSON Schemas — one for documents, one for project.json , one for .class.json . A key either exists in the schema or it does not, and an invented \"styles\" where the schema says \"style\" is caught by a validator rather than by a blank page. Edits are structural, not textual. A page is a tree of addressable nodes, so \"add a button to the header\" is an insertion at a path, not a search-and-replace over source text. That is how Studio's assistant edits the canvas live, and why an external agent can change one property without touching the rest of the file. Every change is a reviewable diff. JSON diffs on property boundaries, so a small change in git diff is a small change in the page. Machine-written work needs review more than hand-written work does, and this is the format that makes review cheap. None of this makes a model correct. It makes a model checkable — and that is the property you can build a workflow on. Three ways an agent meets a Jx project Studio's built-in assistant A chat sidebar inside the editor that works on your project rather than talking about it: it creates pages and components, edits the document on the canvas while you watch, and answers questions by reading your files. It runs against an AI provider you connect, and everything it writes as a Jx document is validated before it lands. See AI assistant . An external coding agent Claude Code, Cursor, or your own script, working on the project folder like any other repository. Nothing is Jx-specific about the setup — the agent reads and writes files — but a briefing pays for itself, because the schema encodes rules the model would otherwise guess at (style is an object, IDL properties sit on the element, layouts use slot ). See Authoring rules for agents . Validation in CI jx validate exits non-zero on any violation, so the command an agent runs after each edit is the command your pipeline can run on the pull request. Agent work and hand-written work pass through one gate, and the gate does not care which is which. The generate-validate-fix loop 1. Generate the project's schemas — jx schema . Run it once per project, and again after any change to project.json 's extensions array. It composes the core schemas with the fragments each enabled extension ships and writes two entry documents into the project root, project.schema.json and document.schema.json . Both are self-contained single-resource schemas : every referenced resource is embedded under $defs and every $ref is a root-relative JSON Pointer, so they resolve with no node_modules and no network. One resolution behavior for every consumer — your editor, Studio's Monaco, and jx validate alike. See Schema composition . 2. Let the agent write files. project.json binds itself with \"$schema\": \"./project.schema.json\" , so an editor with JSON language support autocompletes and underlines as the agent types. Documents under pages/ , layouts/ , and components/ carry no $schema key of their own — document.schema.json is the schema they are checked against, in step 3. 3. Check the work — jx validate . The deterministic gate, run after every edit. It walks the project in five passes: Both committed entry documents, for self-containment — a $ref that is a relative path, a URI, or a pointer to nothing means they are stale, and the fix is to re-run jx schema . This runs first and stops the walk, because every later pass compiles one of these files. project.json against the generated entry schema. Every document under components/ , pages/ , and layouts/ against the bundled document schema. Every project-local *.class.json against the class schema. Each enabled extension's schema fragments, compiled standalone. Clean runs print Project is valid (N files checked in ) . Failures print Project is INVALID , then one block per file: pages/about.json: - /children/0: must NOT have additional properties 4. Feed the failures back verbatim. Each line already names the file, the JSON pointer into it, and what is wrong — a complete fix instruction with nothing left to infer. Loop until validation is clean, then run jx build . Wire steps 1 and 3 into the agent's own instructions (\"run jx validate after every file you write; do not report success until it passes\") rather than running them yourself. An agent that can check its own work will, and the loop closes without you in it. What an agent can build The whole framework is reachable from JSON, so the ceiling is higher than \"a static page\": Pages, layouts, and components — routing from the pages/ tree, shared shells with slot , reusable custom elements. See Site architecture . Content collections — folders of Markdown, JSON, or CSV files with schema validation, queried into pages. See Content collections . Databases — connections and data sections in project.json become real tables (D1, Supabase, or SQLite) with CRUD and form actions. See Databases . Server functions — a state entry with timing: \"server\" compiles into a server handler your secrets can live behind. See Timing . Accounts and sessions — the auth extension adds sign-in, sessions, and per-table permissions. See Auth and secrets . One boundary is worth telling the agent up front: pages are prerendered at build time , and interactivity arrives as hydration islands. There is no per-request page rendering, and the route set is fixed when the build runs — a page that must exist per visitor is a client-side view over server data, not server-rendered HTML. The other thing to say up front is the adapter. A project with connection-backed data tables must set a server-capable build.adapter — cloudflare-workers , cloudflare-pages , node , or bun — and the build fails on static. Server functions want one too, since that is what packages them into a worker a host will actually run. See Build output and adapters . Related Authoring rules for agents — the briefing to hand an external coding agent Machine-readable docs — the schema and documentation endpoints an agent can fetch CLI commands — every flag of jx schema , jx validate , and the rest Schema composition — how the entry documents are assembled AI assistant — the agent that ships inside Studio"},{"id":"docs:framework/agents#working-with-agents","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#working-with-agents","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Working with agents","text":"A Jx project is a folder of JSON documents, and that one fact changes what it means to hand a website to a language model. The model edits the same pages/index.json a person edits in Studio — not a generated intermediate, not a pile of framework code standing in for the page. There is one artifact, and everybody works on it: you, Studio, and the agent. This page explains why that shape suits a model, where agents plug in, and the loop that turns a plausible answer into a checked one."},{"id":"docs:framework/agents#why-documents-are-tractable-where-code-is-not","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#why-documents-are-tractable-where-code-is-not","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Why documents are tractable where code is not","text":"Prompt-to-code tools produce programs. A program is \"correct\" only in the sense that it runs, and finding out whether it runs means executing it, in an environment, with a browser attached. A Jx document is a different kind of output: The shape is bounded. Every Jx file validates against one of three published JSON Schemas — one for documents, one for project.json , one for .class.json . A key either exists in the schema or it does not, and an invented \"styles\" where the schema says \"style\" is caught by a validator rather than by a blank page. Edits are structural, not textual. A page is a tree of addressable nodes, so \"add a button to the header\" is an insertion at a path, not a search-and-replace over source text. That is how Studio's assistant edits the canvas live, and why an external agent can change one property without touching the rest of the file. Every change is a reviewable diff. JSON diffs on property boundaries, so a small change in git diff is a small change in the page. Machine-written work needs review more than hand-written work does, and this is the format that makes review cheap. None of this makes a model correct. It makes a model checkable — and that is the property you can build a workflow on."},{"id":"docs:framework/agents#three-ways-an-agent-meets-a-jx-project","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#three-ways-an-agent-meets-a-jx-project","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Three ways an agent meets a Jx project","text":""},{"id":"docs:framework/agents#studios-built-in-assistant","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#studios-built-in-assistant","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Studio's built-in assistant","text":"A chat sidebar inside the editor that works on your project rather than talking about it: it creates pages and components, edits the document on the canvas while you watch, and answers questions by reading your files. It runs against an AI provider you connect, and everything it writes as a Jx document is validated before it lands. See AI assistant ."},{"id":"docs:framework/agents#an-external-coding-agent","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#an-external-coding-agent","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"An external coding agent","text":"Claude Code, Cursor, or your own script, working on the project folder like any other repository. Nothing is Jx-specific about the setup — the agent reads and writes files — but a briefing pays for itself, because the schema encodes rules the model would otherwise guess at (style is an object, IDL properties sit on the element, layouts use slot ). See Authoring rules for agents ."},{"id":"docs:framework/agents#validation-in-ci","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#validation-in-ci","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Validation in CI","text":"jx validate exits non-zero on any violation, so the command an agent runs after each edit is the command your pipeline can run on the pull request. Agent work and hand-written work pass through one gate, and the gate does not care which is which."},{"id":"docs:framework/agents#the-generate-validate-fix-loop","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#the-generate-validate-fix-loop","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"The generate-validate-fix loop","text":"1. Generate the project's schemas — jx schema . Run it once per project, and again after any change to project.json 's extensions array. It composes the core schemas with the fragments each enabled extension ships and writes two entry documents into the project root, project.schema.json and document.schema.json . Both are self-contained single-resource schemas : every referenced resource is embedded under $defs and every $ref is a root-relative JSON Pointer, so they resolve with no node_modules and no network. One resolution behavior for every consumer — your editor, Studio's Monaco, and jx validate alike. See Schema composition . 2. Let the agent write files. project.json binds itself with \"$schema\": \"./project.schema.json\" , so an editor with JSON language support autocompletes and underlines as the agent types. Documents under pages/ , layouts/ , and components/ carry no $schema key of their own — document.schema.json is the schema they are checked against, in step 3. 3. Check the work — jx validate . The deterministic gate, run after every edit. It walks the project in five passes: Both committed entry documents, for self-containment — a $ref that is a relative path, a URI, or a pointer to nothing means they are stale, and the fix is to re-run jx schema . This runs first and stops the walk, because every later pass compiles one of these files. project.json against the generated entry schema. Every document under components/ , pages/ , and layouts/ against the bundled document schema. Every project-local *.class.json against the class schema. Each enabled extension's schema fragments, compiled standalone. Clean runs print Project is valid (N files checked in ) . Failures print Project is INVALID , then one block per file: pages/about.json: - /children/0: must NOT have additional properties 4. Feed the failures back verbatim. Each line already names the file, the JSON pointer into it, and what is wrong — a complete fix instruction with nothing left to infer. Loop until validation is clean, then run jx build . Wire steps 1 and 3 into the agent's own instructions (\"run jx validate after every file you write; do not report success until it passes\") rather than running them yourself. An agent that can check its own work will, and the loop closes without you in it."},{"id":"docs:framework/agents#what-an-agent-can-build","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#what-an-agent-can-build","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"What an agent can build","text":"The whole framework is reachable from JSON, so the ceiling is higher than \"a static page\": Pages, layouts, and components — routing from the pages/ tree, shared shells with slot , reusable custom elements. See Site architecture . Content collections — folders of Markdown, JSON, or CSV files with schema validation, queried into pages. See Content collections . Databases — connections and data sections in project.json become real tables (D1, Supabase, or SQLite) with CRUD and form actions. See Databases . Server functions — a state entry with timing: \"server\" compiles into a server handler your secrets can live behind. See Timing . Accounts and sessions — the auth extension adds sign-in, sessions, and per-table permissions. See Auth and secrets . One boundary is worth telling the agent up front: pages are prerendered at build time , and interactivity arrives as hydration islands. There is no per-request page rendering, and the route set is fixed when the build runs — a page that must exist per visitor is a client-side view over server data, not server-rendered HTML. The other thing to say up front is the adapter. A project with connection-backed data tables must set a server-capable build.adapter — cloudflare-workers , cloudflare-pages , node , or bun — and the build fails on static. Server functions want one too, since that is what packages them into a worker a host will actually run. See Build output and adapters ."},{"id":"docs:framework/agents#related","collection":"docs","slug":"framework/agents","url":"/docs/framework/agents/#related","title":"Working with agents","description":"Why a Jx project is tractable for a language model, the three places an agent meets one, and the generate-validate-fix loop that keeps its work honest.","heading":"Related","text":"Authoring rules for agents — the briefing to hand an external coding agent Machine-readable docs — the schema and documentation endpoints an agent can fetch CLI commands — every flag of jx schema , jx validate , and the rest Schema composition — how the entry documents are assembled AI assistant — the agent that ships inside Studio"},{"id":"docs:framework/build","collection":"docs","slug":"framework/build","url":"/docs/framework/build/","title":"How compilation works","description":"What jx build does — route discovery, static detection, and the output tiers — and why most Jx pages ship zero JavaScript.","heading":"","text":"How compilation works jx build turns a Jx project — JSON documents in pages/ , layouts/ , and components/ — into a production site in dist/ . The compiler erases the Jx abstractions at build time: no JSON documents, no interpreter, and no framework code ship to production. A page only gets JavaScript when the compiler can prove it needs some, and the proof runs in one direction — everything is static until something dynamic is found. The only client-side dependencies a page can end up with are @vue/reactivity (~7 kB gzip) and lit-html (~3 kB gzip), loaded through an import map — and only on pages that need them. What jx build does Running jx build (see CLI commands ) orchestrates one pipeline: Load project.json and register the extensions it declares ( extensions ), which contribute file formats such as Markdown pages. Discover routes by scanning pages/ : pages/index.json → / , pages/about.json → /about , pages/blog/[slug].json → /blog/:slug , pages/docs/[...path].json → catch-all. Files starting with _ are not routed. .json pages are native; other extensions (like .md ) route through a format registered by an enabled extension. Expand dynamic routes — a [param] page's $paths definition produces one concrete route per entry. Compile each route : resolve its layout, merge $head from site + layout + page, inject the read-only $site / $page context, resolve build-time data, transform images for responsive output, then hand the assembled document to the compiler. Emit dist/ : one index.html per route (with build.trailingSlash: \"always\" , the default), compiled component modules and CSS under dist/components/ , public/ copied verbatim, plus sitemap.xml (when url is set in project.json ), _redirects , and — when build.adapter is set — a bundled server worker ( worker.js , or _worker.js + _routes.json for Cloudflare Pages). The build finishes with a summary ( Done: 12 routes → 34 files ) and exits non-zero if any route failed. Static detection The routing decision is a single recursive tree walk — isDynamic() — that never executes your code. A document compiles to plain HTML unless the walk finds one of: a state entry that exists at runtime (a plain value, a $prototype entry, or anything with a default ) a ${…} template string in a property, style, or attribute value a $ref binding on an element property a $switch node a mapped array ( $prototype: \"Array\" ) any child that is itself dynamic Three kinds of state are exempt because they are resolved during the build and then removed: the injected $site and $page context (read-only, never reactive) entries with timing: \"compiler\" — resolved at build time and baked into the HTML schema-only definitions (pure type information produces no output) What compiles away Site and page context looks like state, but it is data the compiler already has. This heading: { \"tagName\" : \"h1\" , \"textContent\" : \"${state.$site.name} — ${state.$page.title}\" } compiles to literal HTML with the template evaluated and gone: < h1 >Acme Realty — About us The same applies to timing: \"compiler\" data and to content collections: template strings over build-time values are evaluated against the resolved data, mapped arrays over resolved content are unrolled into repeated markup, and the now-spent state entries are stripped. What reaches isDynamic() afterwards is a plain tree — so a blog index that lists every post can still be a zero-JS page. The output tiers Fully static When nothing dynamic survives the build-time resolution, the page is plain HTML with its CSS in the head — zero JavaScript, no import map, no module scripts. This is the default outcome, not an optimization you opt into. Islands in a static shell A dynamic subtree inside an otherwise-static document doesn't drag the whole page into the client tier. The compiler cuts the subtree out, compiles it to a small custom-element module, and leaves a placeholder tag in the HTML: < jx-island-0 > < script type = \"module\" src = \"./_islands/jx-island-0.js\" > The module upgrades the element in place. Components you author with a hyphenated tagName (say site-counter ) work the same way: the page HTML stays static, and dist/components/site-counter.js loads only on pages that use the element. The import map added to those pages resolves @vue/reactivity and lit-html for the island modules. Dynamic pages When the page document itself is dynamic — it declares live state , binds $ref s, or uses runtime template strings — the compiler still pre-renders the full HTML, marks bound elements with data-bind attributes, and emits one small module that wires reactivity onto the existing DOM: reactive state, computed() for derived values, effect() per binding, and event handler hookup. There is no client-side re-render of the initial view; the JS only maintains what changes. Two more outputs sit alongside these tiers: .class.json documents compile to ES class modules, and timing: \"server\" entries generate server handlers — a per-route _server.js , or a single site-wide worker when build.adapter is set. Across all three tiers the emitter indents nested children so the generated HTML stays readable — except inside pre , textarea , and the rest of the tags browsers render with white-space: pre . There, and everywhere below them ( white-space inherits), children are concatenated with no separator, because indentation between elements would be content rather than formatting. This is what keeps a syntax-highlighted code block — one per token — rendering as the code you wrote. CSS extraction Style never ships as JavaScript. During compilation, every static style definition — the project-level style from project.json , the layout's, the page's, and each node's — is extracted into a single