From 835c777714942ad46fb78e699892538fb06c6d53 Mon Sep 17 00:00:00 2001
From: Mark Polak <mapol@microsoft.com>
Date: Wed, 15 Jul 2026 16:43:18 +0200
Subject: [PATCH 1/4] Add render state schema generation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fe040cbf-edcc-4e6f-b829-f85e08f2d044
---
 Cargo.lock                                    |  21 +
 Cargo.toml                                    |   1 +
 DESIGN.md                                     |  63 ++
 crates/webui-cli/Cargo.toml                   |   2 +
 crates/webui-cli/README.md                    |  20 +-
 crates/webui-cli/src/commands/build.rs        | 179 ++++-
 crates/webui-cli/src/commands/mod.rs          |   3 +
 crates/webui-cli/src/commands/state_schema.rs | 365 ++++++++++
 .../src/commands/state_schema/inference.rs    | 419 ++++++++++++
 .../src/commands/state_schema/model.rs        | 264 +++++++
 .../src/commands/state_schema/scope.rs        |  99 +++
 ...sts__snapshots_component_scope_schema.snap |  63 ++
 ...s__snapshots_nested_collection_schema.snap | 105 +++
 ...s_declared_in_component_schema_bundle.snap | 114 ++++
 ...napshots_routes_example_schema_bundle.snap | 645 ++++++++++++++++++
 .../src/commands/state_schema/tests.rs        | 394 +++++++++++
 crates/webui-cli/src/main.rs                  |   1 +
 .../state-schema/component-scope/index.html   |  19 +
 .../component-scope/nested-label.html         |   1 +
 .../component-scope/profile-card.html         |   5 +
 .../nested-collections/group-list.html        |  20 +
 .../nested-collections/index.html             |   1 +
 .../state-schema/routed-shell/app-shell.html  |   4 +
 .../routed-shell/detail-page.html             |   1 +
 .../state-schema/routed-shell/home-page.html  |   3 +
 .../state-schema/routed-shell/index.html      |   1 +
 .../routed-shell/settings-page.html           |   1 +
 docs/ai.md                                    |  17 +
 docs/guide/cli/index.md                       |  67 +-
 docs/guide/concepts/state-management/index.md |  26 +
 examples/app/commerce/data/state.json         |   9 +-
 .../app/contact-book-manager/data/state.json  |   1 +
 32 files changed, 2908 insertions(+), 26 deletions(-)
 create mode 100644 crates/webui-cli/src/commands/state_schema.rs
 create mode 100644 crates/webui-cli/src/commands/state_schema/inference.rs
 create mode 100644 crates/webui-cli/src/commands/state_schema/model.rs
 create mode 100644 crates/webui-cli/src/commands/state_schema/scope.rs
 create mode 100644 crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
 create mode 100644 crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
 create mode 100644 crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
 create mode 100644 crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
 create mode 100644 crates/webui-cli/src/commands/state_schema/tests.rs
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/component-scope/index.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/component-scope/nested-label.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/component-scope/profile-card.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/nested-collections/group-list.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/nested-collections/index.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/routed-shell/app-shell.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/routed-shell/detail-page.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/routed-shell/home-page.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/routed-shell/index.html
 create mode 100644 crates/webui-cli/tests/fixtures/state-schema/routed-shell/settings-page.html

diff --git a/Cargo.lock b/Cargo.lock
index 9f061686..813dd945 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1574,6 +1574,19 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "insta"
+version = "1.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82"
+dependencies = [
+ "console",
+ "once_cell",
+ "serde",
+ "similar",
+ "tempfile",
+]
+
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
@@ -1816,6 +1829,7 @@ dependencies = [
  "clap",
  "console",
  "expand-tilde",
+ "insta",
  "log",
  "microsoft-webui",
  "microsoft-webui-dev-server",
@@ -1824,6 +1838,7 @@ dependencies = [
  "microsoft-webui-protocol",
  "microsoft-webui-tokens",
  "mime_guess",
+ "serde",
  "serde_json",
  "tempfile",
  "tokio",
@@ -2931,6 +2946,12 @@ version = "0.3.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
 
+[[package]]
+name = "similar"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbbb5d9659141646ae647b42fe094daf6c6192d1620870b449d9557f748b2daa"
+
 [[package]]
 name = "siphasher"
 version = "1.0.3"
diff --git a/Cargo.toml b/Cargo.toml
index 4171d0ae..83c00554 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -72,6 +72,7 @@ windows-sys = { version = "0.61.2", features = [
 
 # Test dependencies
 criterion = "0.8.2"
+insta = { version = "1.48.0", features = ["json"] }
 tempfile = "3.27.0"
 
 # Build dependencies
diff --git a/DESIGN.md b/DESIGN.md
index 1ed5dfbd..42fbddfe 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1793,6 +1793,69 @@ function returns `NULL`, call `webui_last_error()` for a human-readable diagnost
 
 The CLI specification and usage details are maintained in [crates/webui-cli/README.md](crates/webui-cli/README.md).
 
+### Render State JSON Schema
+
+`webui schema <protocol.bin>` analyzes the compiled entry and writes a
+JSON Schema draft 2020-12 document to stdout. `--entry` selects the entry
+fragment and `--title` sets the schema title.
+
+`webui build --emit-schema` runs the same analysis directly against the
+in-memory protocol and writes `<protocol-stem>.state.schema.json` beside the
+protocol. Schema generation and serialization complete before build outputs are
+written. Emission is opt-in because schemas are build-time tooling artifacts,
+not render-time requirements.
+
+For entries without routes, the output is a normal object schema. Inference
+uses the following rules:
+
+- Plain text and normal attribute values accept JSON scalars: `string`,
+  `number`, or `boolean`. Complex `:property` bindings remain unconstrained
+  until child-template usage provides stronger structural evidence.
+- Raw signals are strings.
+- Dotted paths create nested objects.
+- A terminal `.length` accepts the runtime's three valid forms: a string, an
+  array, or an object with a `length` property.
+- `<for>` collections create arrays; loop-item paths define the item schema.
+- Ordered predicates infer numbers. Equality predicates infer the type of a
+  literal operand.
+- Condition-only paths are optional because a missing condition value evaluates
+  false. A path referenced by rendered output or a collection remains required.
+- Normal component-attribute source paths are recorded as scalars, but
+  child-local comparisons do not re-type the parent path. Complex bindings
+  preserve structural origin through the child template. Static and computed
+  component-local values do not become root state properties.
+- Parser-synthesized `head_end`, `body_start`, and `body_end` signals are not
+  state.
+
+For routed entries, the output is a schema bundle. Each complete matched route
+chain receives a distinct schema under `$defs`. Top-level `anyOf` references
+those definitions, while `x-webui-routes` maps each route pattern to its
+definition:
+
+```json
+{
+  "$defs": {
+    "route": {},
+    "route.contacts.:id": {}
+  },
+  "anyOf": [
+    { "$ref": "#/$defs/route" },
+    { "$ref": "#/$defs/route.contacts.:id" }
+  ],
+  "x-webui-routes": {
+    "/": "#/$defs/route",
+    "/contacts/:id": "#/$defs/route.contacts.:id"
+  }
+}
+```
+
+Route definitions are not structurally deduplicated. Even routes with identical
+current shapes retain independent contracts so future changes do not
+unexpectedly couple them. Definition keys are readable route encodings, but
+consumers should still use `x-webui-routes` rather than constructing `$defs`
+keys. Host-language DTO generation and runtime schema validation are separate
+concerns and are not part of `schema`.
+
 ## Example Workflow
 
 Examples and end-to-end walkthroughs are maintained in [examples/README.md](examples/README.md)
diff --git a/crates/webui-cli/Cargo.toml b/crates/webui-cli/Cargo.toml
index 551286c9..bf226ac1 100644
--- a/crates/webui-cli/Cargo.toml
+++ b/crates/webui-cli/Cargo.toml
@@ -25,6 +25,7 @@ microsoft-webui-dev-server = { path = "../webui-dev-server", version = "0.0.18"
 clap = { workspace = true }
 anyhow = { workspace = true }
 console = { workspace = true }
+serde = { workspace = true }
 serde_json = { workspace = true }
 actix-web = { workspace = true }
 awc = { workspace = true }
@@ -36,6 +37,7 @@ tokio-stream = { workspace = true }
 log = { workspace = true }
 
 [dev-dependencies]
+insta = { workspace = true }
 tempfile = { workspace = true }
 microsoft-webui-protocol = { path = "../webui-protocol", version = "0.0.18" }
 
diff --git a/crates/webui-cli/README.md b/crates/webui-cli/README.md
index c9175637..081eed54 100644
--- a/crates/webui-cli/README.md
+++ b/crates/webui-cli/README.md
@@ -1,6 +1,6 @@
 # microsoft-webui-cli
 
-Command-line tool for the [WebUI](https://github.com/microsoft/webui) framework — build, serve, and inspect WebUI applications.
+Command-line tool for the [WebUI](https://github.com/microsoft/webui) framework - build, serve, inspect, and generate render-state schemas for WebUI applications.
 
 ## Install
 
@@ -17,7 +17,7 @@ This installs the `webui` binary.
 Build a WebUI application into a compiled protocol and CSS files.
 
 ```bash
-webui build [APP] --out <DIR> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>] [--asset-file-name-template <TEMPLATE>] [--css-public-base <BASE>]
+webui build [APP] --out <DIR> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>] [--emit-schema] [--asset-file-name-template <TEMPLATE>] [--css-public-base <BASE>]
 ```
 
 | Option | Default | Description |
@@ -27,6 +27,7 @@ webui build [APP] --out <DIR> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>]
 | `--entry` | `index.html` | Entry HTML file |
 | `--css` | `link` | CSS mode: `link` (external files) or `style` (inline) |
 | `--plugin` | *(none)* | Plugin identifier (see [Plugins](https://microsoft.github.io/webui/guide/concepts/plugins/) for available identifiers) |
+| `--emit-schema` | off | Emit `<protocol-stem>.state.schema.json` beside the protocol |
 | `--asset-file-name-template` | `[name].[ext]` | Emitted asset filename template. Tokens: `[name]`, `[hash]`, `[ext]` |
 | `--css-public-base` | *(none)* | Optional base URL/path prepended to Link-mode stylesheet hrefs |
 
@@ -34,6 +35,7 @@ webui build [APP] --out <DIR> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>]
 webui build ./src --out ./dist
 webui build ./src --out ./dist --plugin webui --css style
 webui build ./src --out ./dist/app1.bin
+webui build ./src --out ./dist/app1.bin --emit-schema
 webui build ./src --out ./dist --asset-file-name-template "[name]-[hash].[ext]"
 webui build ./src --out ./dist --asset-file-name-template "[name]-[hash].[ext]" --css-public-base "https://cdn.example.com/assets"
 ```
@@ -82,6 +84,20 @@ webui inspect <FILE>
 webui inspect ./dist/protocol.bin
 ```
 
+### `webui schema`
+
+Generate a JSON Schema for the render state referenced by a compiled protocol.
+
+```bash
+webui schema ./dist/protocol.bin \
+  --entry index.html \
+  --title MyAppState > ./dist/state.schema.json
+```
+
+Plain bindings accept string, number, or boolean values. Loops and dotted paths
+produce array and object schemas. Routed entries produce separate definitions
+for each route chain plus an `x-webui-routes` path-to-schema mapping.
+
 ## App Layout
 
 ```
diff --git a/crates/webui-cli/src/commands/build.rs b/crates/webui-cli/src/commands/build.rs
index bf20b20e..70971c58 100644
--- a/crates/webui-cli/src/commands/build.rs
+++ b/crates/webui-cli/src/commands/build.rs
@@ -5,7 +5,7 @@ use anyhow::{Context, Result};
 use clap::Args;
 use expand_tilde::expand_tilde;
 use std::collections::HashSet;
-use std::ffi::OsString;
+use std::ffi::{OsStr, OsString};
 use std::fs;
 use std::path::{Path, PathBuf};
 
@@ -28,6 +28,10 @@ pub struct BuildArgs {
     #[arg(long, value_delimiter = ',', value_name = "TAGS")]
     pub emit_component_assets: Vec<String>,
 
+    /// Emit a render-state JSON Schema beside the compiled protocol
+    #[arg(long)]
+    pub emit_schema: bool,
+
     /// Design token theme to validate against: a JSON file path or npm package name.
     /// Missing unresolved CSS tokens fail the build.
     #[arg(long)]
@@ -58,34 +62,50 @@ fn resolve_out(out: &Path) -> (PathBuf, OsString) {
     }
 }
 
+fn schema_file_name(protocol_name: &OsStr) -> OsString {
+    let stem = Path::new(protocol_name)
+        .file_stem()
+        .filter(|value| !value.is_empty())
+        .unwrap_or(protocol_name);
+    let mut name = stem.to_os_string();
+    name.push(".state.schema.json");
+    name
+}
+
 fn validate_output_file_names(
-    protocol_name: &std::ffi::OsStr,
+    protocol_name: &OsStr,
+    schema_name: Option<&OsStr>,
     result: &webui::BuildResult,
 ) -> Result<()> {
-    let mut names =
-        HashSet::with_capacity(1 + result.css_files.len() + result.component_asset_files.len());
-    names.insert(protocol_name.to_os_string());
+    let mut names = HashSet::with_capacity(
+        1 + usize::from(schema_name.is_some())
+            + result.css_files.len()
+            + result.component_asset_files.len(),
+    );
+    insert_output_file_name(&mut names, protocol_name)?;
+    if let Some(schema_name) = schema_name {
+        insert_output_file_name(&mut names, schema_name)?;
+    }
     for (name, _) in &result.css_files {
-        let name = OsString::from(name);
-        if !names.insert(name.clone()) {
-            anyhow::bail!(
-                "output filename collision for '{}'. Adjust --asset-file-name-template to include [ext] or another unique asset-type segment.",
-                name.to_string_lossy()
-            );
-        }
+        insert_output_file_name(&mut names, OsStr::new(name))?;
     }
     for file in &result.component_asset_files {
-        let name = OsString::from(&file.name);
-        if !names.insert(name.clone()) {
-            anyhow::bail!(
-                "output filename collision for '{}'. Adjust --asset-file-name-template to include [ext] or another unique asset-type segment.",
-                name.to_string_lossy()
-            );
-        }
+        insert_output_file_name(&mut names, OsStr::new(&file.name))?;
     }
     Ok(())
 }
 
+fn insert_output_file_name(names: &mut HashSet<String>, name: &OsStr) -> Result<()> {
+    let key = name.to_string_lossy().to_lowercase();
+    if names.insert(key) {
+        return Ok(());
+    }
+    anyhow::bail!(
+        "output filename collision for '{}'. Choose a different --out filename or adjust --asset-file-name-template.",
+        name.to_string_lossy()
+    );
+}
+
 pub fn execute(args: &BuildArgs) -> Result<()> {
     run(args).inspect_err(|err| {
         output::error(err);
@@ -120,6 +140,8 @@ fn run(args: &BuildArgs) -> Result<()> {
 
     let (out_dir, protocol_name) = resolve_out(&out);
     let protocol_path = out_dir.join(&protocol_name);
+    let schema_name = args.emit_schema.then(|| schema_file_name(&protocol_name));
+    let schema_path = schema_name.as_ref().map(|name| out_dir.join(name));
 
     output::header("WebUI Build");
     output::field("App", &app.display());
@@ -135,6 +157,9 @@ fn run(args: &BuildArgs) -> Result<()> {
     if !args.emit_component_assets.is_empty() {
         output::field("Component assets", &args.emit_component_assets.join(", "));
     }
+    if let Some(schema_path) = &schema_path {
+        output::field("Schema", &schema_path.display());
+    }
     if let Some(ref theme) = args.theme {
         output::field("Theme", theme);
     }
@@ -148,7 +173,20 @@ fn run(args: &BuildArgs) -> Result<()> {
         .map(|theme| load_theme(theme, &app))
         .transpose()?;
     let result = webui::build(build_options).with_context(|| "Build failed")?;
-    validate_output_file_names(&protocol_name, &result)?;
+    validate_output_file_names(&protocol_name, schema_name.as_deref(), &result)?;
+    let schema_output = schema_path
+        .as_ref()
+        .map(|path| -> Result<(PathBuf, Vec<u8>)> {
+            let schema = super::state_schema::generate_schema(
+                &result.protocol,
+                &args.app_args.entry,
+                super::state_schema::DEFAULT_SCHEMA_TITLE,
+            )?;
+            let output = super::state_schema::schema_to_pretty_json(&schema)
+                .with_context(|| "Failed to serialize render-state schema")?;
+            Ok((path.clone(), output.into_bytes()))
+        })
+        .transpose()?;
 
     fs::create_dir_all(&out_dir)
         .with_context(|| format!("Failed to create {}", out_dir.display()))?;
@@ -167,6 +205,10 @@ fn run(args: &BuildArgs) -> Result<()> {
             )
         })?;
     }
+    if let Some((schema_path, schema_bytes)) = &schema_output {
+        fs::write(schema_path, schema_bytes)
+            .with_context(|| format!("Failed to write {}", schema_path.display()))?;
+    }
     let stats = result.stats;
 
     output::success(&format!(
@@ -202,11 +244,20 @@ fn run(args: &BuildArgs) -> Result<()> {
         ));
     }
 
-    let files_written = 1 + stats.css_file_count + result.component_asset_files.len();
+    let files_written = 1
+        + stats.css_file_count
+        + result.component_asset_files.len()
+        + usize::from(schema_output.is_some());
     output::success(&format!(
         "Wrote {}",
         console::style(Path::new(&protocol_name).display()).bold()
     ));
+    if let Some(schema_name) = schema_name {
+        output::success(&format!(
+            "Wrote {}",
+            console::style(Path::new(&schema_name).display()).bold()
+        ));
+    }
 
     for advisory in &result.warnings {
         output::warning_diagnostic(advisory);
@@ -239,6 +290,7 @@ pub fn build(app: &std::path::Path, out: &std::path::Path, entry: &str) -> Resul
         },
         out: out.to_path_buf(),
         emit_component_assets: Vec::new(),
+        emit_schema: false,
         theme: None,
     })
 }
@@ -347,6 +399,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -383,6 +436,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: vec!["mail-thread".to_string()],
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -436,6 +490,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: vec!["mail-thread".to_string(), "mail-thread".to_string()],
+            emit_schema: false,
             theme: None,
         });
 
@@ -466,6 +521,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: vec!["fast-card".to_string()],
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -504,6 +560,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: vec!["mail-thread".to_string()],
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -640,6 +697,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -725,6 +783,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -807,6 +866,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -860,6 +920,7 @@ mod tests {
             },
             out: out_dir.path().to_path_buf(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: Some(
                 app_dir
                     .path()
@@ -900,6 +961,7 @@ mod tests {
             },
             out: custom_path.clone(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -915,6 +977,45 @@ mod tests {
 
         // CSS files are emitted next to the renamed protocol.
         assert!(out_dir.path().join("my-card.css").exists());
+        assert!(!out_dir.path().join("app1.state.schema.json").exists());
+    }
+
+    #[test]
+    fn test_build_emits_schema_beside_custom_protocol() {
+        let app_dir = create_app_dir(&[(
+            "index.html",
+            "<h1>{{title}}</h1><for each=\"item in items\">{{item.name}}</for>",
+        )]);
+        let out_dir = TempDir::new().unwrap();
+        let protocol_path = out_dir.path().join("catalog.bin");
+
+        run(&BuildArgs {
+            app_args: AppArgs {
+                app: app_dir.path().to_path_buf(),
+                entry: "index.html".to_string(),
+                css: CssStrategy::Link,
+                dom: DomStrategy::Shadow,
+                plugin: None,
+                components: Vec::new(),
+                asset_file_name_template: DEFAULT_ASSET_FILE_NAME_TEMPLATE.to_string(),
+                css_public_base: None,
+                legal_comments: LegalComments::Inline,
+            },
+            out: protocol_path.clone(),
+            emit_component_assets: Vec::new(),
+            emit_schema: true,
+            theme: None,
+        })
+        .unwrap();
+
+        let schema_path = out_dir.path().join("catalog.state.schema.json");
+        assert!(protocol_path.exists());
+        assert!(schema_path.exists());
+        let schema: serde_json::Value =
+            serde_json::from_str(&fs::read_to_string(schema_path).unwrap()).unwrap();
+        assert_eq!(schema["title"], "WebUIState");
+        assert_eq!(schema["properties"]["items"]["type"], "array");
+        assert!(schema["properties"]["title"]["type"].is_array());
     }
 
     #[test]
@@ -937,6 +1038,7 @@ mod tests {
             },
             out: nested.clone(),
             emit_component_assets: Vec::new(),
+            emit_schema: false,
             theme: None,
         })
         .unwrap();
@@ -952,6 +1054,41 @@ mod tests {
         assert_eq!(name, "protocol.bin");
     }
 
+    #[test]
+    fn test_schema_file_name_tracks_protocol_stem() {
+        assert_eq!(
+            schema_file_name(std::ffi::OsStr::new("protocol.bin")),
+            "protocol.state.schema.json"
+        );
+        assert_eq!(
+            schema_file_name(std::ffi::OsStr::new("app1.bin")),
+            "app1.state.schema.json"
+        );
+    }
+
+    #[test]
+    fn test_schema_collision_check_is_case_insensitive() {
+        let app_dir = create_app_dir(&[("index.html", "<h1>Hello</h1>")]);
+        let mut result = webui::build(webui::BuildOptions {
+            app_dir: app_dir.path().to_path_buf(),
+            ..webui::BuildOptions::default()
+        })
+        .unwrap();
+        result.css_files.push((
+            "catalog.state.schema.json".to_string(),
+            "collision".to_string(),
+        ));
+
+        let error = validate_output_file_names(
+            std::ffi::OsStr::new("Catalog.bin"),
+            Some(std::ffi::OsStr::new("Catalog.state.schema.json")),
+            &result,
+        )
+        .unwrap_err();
+
+        assert!(error.to_string().contains("filename collision"));
+    }
+
     #[test]
     fn test_resolve_out_bin_file_with_parent() {
         let (dir, name) = resolve_out(Path::new("./dist/app1.bin"));
diff --git a/crates/webui-cli/src/commands/mod.rs b/crates/webui-cli/src/commands/mod.rs
index b90f444a..4140efd8 100644
--- a/crates/webui-cli/src/commands/mod.rs
+++ b/crates/webui-cli/src/commands/mod.rs
@@ -5,6 +5,7 @@ pub mod build;
 pub mod common;
 pub mod inspect;
 pub mod serve;
+pub mod state_schema;
 
 use clap::Subcommand;
 
@@ -16,4 +17,6 @@ pub enum Commands {
     Inspect(inspect::InspectArgs),
     /// Start a development server with live reload
     Serve(serve::ServeArgs),
+    /// Generate a JSON Schema for a compiled protocol's render state
+    Schema(state_schema::SchemaArgs),
 }
diff --git a/crates/webui-cli/src/commands/state_schema.rs b/crates/webui-cli/src/commands/state_schema.rs
new file mode 100644
index 00000000..8f72eb2e
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema.rs
@@ -0,0 +1,365 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+mod inference;
+mod model;
+mod scope;
+#[cfg(test)]
+mod tests;
+
+use anyhow::{bail, Context, Result};
+use clap::Args;
+use expand_tilde::expand_tilde;
+use inference::SchemaInference;
+use serde::ser::{SerializeMap, Serializer};
+use serde::Serialize;
+use serde_json::{Map, Value};
+use std::collections::BTreeSet;
+use std::path::PathBuf;
+use webui_handler::route_matcher;
+use webui_protocol::web_ui_fragment;
+use webui_protocol::{WebUIFragmentRoute, WebUIProtocol};
+
+use crate::utils::output;
+
+const JSON_SCHEMA_DIALECT: &str = "https://json-schema.org/draft/2020-12/schema";
+pub(super) const DEFAULT_SCHEMA_TITLE: &str = "WebUIState";
+
+#[derive(Args)]
+pub struct SchemaArgs {
+    /// Path to a protocol.bin file
+    pub file: PathBuf,
+
+    /// Entry fragment to analyze
+    #[arg(long, default_value = "index.html")]
+    pub entry: String,
+
+    /// Schema title
+    #[arg(long, default_value = DEFAULT_SCHEMA_TITLE)]
+    pub title: String,
+}
+
+struct RouteChain<'a> {
+    path: String,
+    components: Vec<&'a str>,
+}
+
+struct PendingRoute<'a> {
+    route: &'a WebUIFragmentRoute,
+    parent_path: String,
+    components: Vec<&'a str>,
+}
+
+pub(super) struct SchemaDocument<'a>(&'a Value);
+
+impl<'a> SchemaDocument<'a> {
+    pub(super) fn new(schema: &'a Value) -> Self {
+        Self(schema)
+    }
+}
+
+impl Serialize for SchemaDocument<'_> {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        let Value::Object(schema) = self.0 else {
+            return self.0.serialize(serializer);
+        };
+
+        let mut map = serializer.serialize_map(Some(schema.len()))?;
+        if let Some(dialect) = schema.get("$schema") {
+            map.serialize_entry("$schema", dialect)?;
+        }
+        for (name, value) in schema {
+            if name != "$schema" {
+                map.serialize_entry(name, value)?;
+            }
+        }
+        map.end()
+    }
+}
+
+pub(super) fn schema_to_pretty_json(schema: &Value) -> serde_json::Result<String> {
+    serde_json::to_string_pretty(&SchemaDocument::new(schema))
+}
+
+pub fn execute(args: &SchemaArgs) -> Result<()> {
+    run(args).inspect_err(|error| {
+        output::error(error);
+        eprintln!();
+    })
+}
+
+fn run(args: &SchemaArgs) -> Result<()> {
+    let input_file = expand_tilde(&args.file)
+        .with_context(|| format!("Failed to expand input path: {}", args.file.display()))?
+        .into_owned();
+
+    let protocol = WebUIProtocol::from_protobuf_file(&input_file)
+        .with_context(|| format!("Failed to read protocol {}", input_file.display()))?;
+    let schema = generate_schema(&protocol, &args.entry, &args.title)
+        .with_context(|| format!("Failed to generate schema for entry {}", args.entry))?;
+    let output = schema_to_pretty_json(&schema)?;
+    println!("{output}");
+    Ok(())
+}
+
+pub(super) fn generate_schema(protocol: &WebUIProtocol, entry: &str, title: &str) -> Result<Value> {
+    if !protocol.fragments.contains_key(entry) {
+        bail!("Entry fragment '{entry}' was not found in the protocol");
+    }
+
+    let routes = collect_route_chains(protocol, entry)?;
+    if routes.is_empty() {
+        let mut inference = SchemaInference::new(protocol);
+        inference.infer_entry(entry)?;
+        return Ok(with_schema_metadata(inference.into_schema(), title));
+    }
+
+    generate_route_bundle(protocol, entry, title, &routes)
+}
+
+fn generate_route_bundle(
+    protocol: &WebUIProtocol,
+    entry: &str,
+    title: &str,
+    routes: &[RouteChain<'_>],
+) -> Result<Value> {
+    let mut definitions = Map::new();
+    let mut route_refs = Map::new();
+    let mut alternatives = Vec::with_capacity(routes.len());
+    let mut definition_keys = BTreeSet::new();
+
+    for route in routes {
+        let key = route_definition_key(&route.path);
+        if !definition_keys.insert(key.clone()) {
+            bail!(
+                "Route path '{}' collides with another generated schema definition",
+                route.path
+            );
+        }
+
+        let mut inference = SchemaInference::new(protocol);
+        inference.infer_entry(entry)?;
+        for component in &route.components {
+            inference.infer_root_component(component)?;
+        }
+
+        let route_title = route_schema_title(title, &route.path);
+        let schema = with_title(inference.into_schema(), &route_title);
+        let schema_ref = definition_ref(&key);
+        definitions.insert(key, schema);
+        route_refs.insert(route.path.clone(), Value::String(schema_ref.clone()));
+        alternatives.push(ref_schema(schema_ref));
+    }
+
+    let mut schema = Map::new();
+    schema.insert(
+        "$schema".to_string(),
+        Value::String(JSON_SCHEMA_DIALECT.to_string()),
+    );
+    schema.insert("$defs".to_string(), Value::Object(definitions));
+    schema.insert("anyOf".to_string(), Value::Array(alternatives));
+    schema.insert("title".to_string(), Value::String(title.to_string()));
+    schema.insert("x-webui-routes".to_string(), Value::Object(route_refs));
+    Ok(Value::Object(schema))
+}
+
+fn collect_route_chains<'a>(
+    protocol: &'a WebUIProtocol,
+    entry: &str,
+) -> Result<Vec<RouteChain<'a>>> {
+    let root_routes = collect_root_routes(protocol, entry)?;
+
+    if root_routes.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut pending = Vec::with_capacity(root_routes.len());
+    for route in root_routes.into_iter().rev() {
+        pending.push(PendingRoute {
+            route,
+            parent_path: "/".to_string(),
+            components: Vec::new(),
+        });
+    }
+
+    let mut chains = Vec::new();
+    while let Some(current) = pending.pop() {
+        let path = normalize_route_path(&route_matcher::resolve_route_path(
+            &current.route.path,
+            &current.parent_path,
+        ));
+        let mut components = current.components;
+        let component_was_visited = components
+            .iter()
+            .any(|component| *component == current.route.fragment_id);
+        components.push(current.route.fragment_id.as_str());
+
+        let mut child_routes = Vec::with_capacity(current.route.children.len());
+        child_routes.extend(&current.route.children);
+        if !component_was_visited {
+            child_routes.extend(collect_root_routes(protocol, &current.route.fragment_id)?);
+        }
+
+        let has_zero_segment_child = child_routes
+            .iter()
+            .any(|child| child_matches_parent_path(&path, &child.path));
+        if child_routes.is_empty() || !has_zero_segment_child {
+            chains.push(RouteChain {
+                path: path.clone(),
+                components: components.clone(),
+            });
+        }
+
+        for child in child_routes.into_iter().rev() {
+            pending.push(PendingRoute {
+                route: child,
+                parent_path: path.clone(),
+                components: components.clone(),
+            });
+        }
+    }
+
+    chains.sort_unstable_by(|left, right| left.path.cmp(&right.path));
+    for pair in chains.windows(2) {
+        if pair[0].path == pair[1].path {
+            bail!(
+                "Multiple route chains resolve to the schema path '{}'",
+                pair[0].path
+            );
+        }
+    }
+    Ok(chains)
+}
+
+fn collect_root_routes<'a>(
+    protocol: &'a WebUIProtocol,
+    entry: &str,
+) -> Result<Vec<&'a WebUIFragmentRoute>> {
+    let mut routes = Vec::new();
+    let mut visited = BTreeSet::new();
+    let mut pending = vec![entry];
+
+    while let Some(fragment_id) = pending.pop() {
+        if !visited.insert(fragment_id) {
+            continue;
+        }
+        let fragment_list = protocol
+            .fragments
+            .get(fragment_id)
+            .with_context(|| format!("Protocol fragment '{fragment_id}' was not found"))?;
+        for fragment in &fragment_list.fragments {
+            match fragment.fragment.as_ref() {
+                Some(web_ui_fragment::Fragment::Component(component)) => {
+                    pending.push(component.fragment_id.as_str());
+                }
+                Some(web_ui_fragment::Fragment::ForLoop(for_loop)) => {
+                    pending.push(for_loop.fragment_id.as_str());
+                }
+                Some(web_ui_fragment::Fragment::IfCond(if_cond)) => {
+                    pending.push(if_cond.fragment_id.as_str());
+                }
+                Some(web_ui_fragment::Fragment::Route(route)) => routes.push(route),
+                _ => {}
+            }
+        }
+    }
+    Ok(routes)
+}
+
+fn child_matches_parent_path(parent: &str, child: &str) -> bool {
+    let resolved = normalize_route_path(&route_matcher::resolve_route_path(child, parent));
+    if resolved == parent {
+        return true;
+    }
+    if child.starts_with('/') {
+        return false;
+    }
+
+    let relative = child.strip_prefix("./").unwrap_or(child);
+    relative
+        .split('/')
+        .filter(|segment| !segment.is_empty())
+        .all(|segment| {
+            segment.starts_with('*') || (segment.starts_with(':') && segment.ends_with('?'))
+        })
+}
+
+fn normalize_route_path(path: &str) -> String {
+    let trimmed = path.trim_end_matches('/');
+    if trimmed.is_empty() {
+        "/".to_string()
+    } else if trimmed.starts_with('/') {
+        trimmed.to_string()
+    } else {
+        let mut normalized = String::with_capacity(trimmed.len() + 1);
+        normalized.push('/');
+        normalized.push_str(trimmed);
+        normalized
+    }
+}
+
+fn route_definition_key(path: &str) -> String {
+    const HEX: &[u8; 16] = b"0123456789abcdef";
+
+    let mut key = String::with_capacity(path.len() + "route.".len());
+    key.push_str("route");
+    for segment in path.trim_matches('/').split('/') {
+        if segment.is_empty() {
+            continue;
+        }
+        key.push('.');
+        for byte in segment.bytes() {
+            if byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b':' | b'?' | b'*') {
+                key.push(char::from(byte));
+            } else {
+                key.push('%');
+                key.push(char::from(HEX[usize::from(byte >> 4)]));
+                key.push(char::from(HEX[usize::from(byte & 0x0f)]));
+            }
+        }
+    }
+    key
+}
+
+fn definition_ref(key: &str) -> String {
+    let mut schema_ref = String::with_capacity("#/$defs/".len() + key.len());
+    schema_ref.push_str("#/$defs/");
+    schema_ref.push_str(key);
+    schema_ref
+}
+
+fn route_schema_title(title: &str, path: &str) -> String {
+    let mut route_title = String::with_capacity(title.len() + path.len() + 3);
+    route_title.push_str(title);
+    route_title.push_str(" (");
+    route_title.push_str(path);
+    route_title.push(')');
+    route_title
+}
+
+fn ref_schema(schema_ref: String) -> Value {
+    let mut schema = Map::new();
+    schema.insert("$ref".to_string(), Value::String(schema_ref));
+    Value::Object(schema)
+}
+
+fn with_schema_metadata(schema: Value, title: &str) -> Value {
+    let mut schema = with_title(schema, title);
+    if let Some(object) = schema.as_object_mut() {
+        object.insert(
+            "$schema".to_string(),
+            Value::String(JSON_SCHEMA_DIALECT.to_string()),
+        );
+    }
+    schema
+}
+
+fn with_title(mut schema: Value, title: &str) -> Value {
+    if let Some(object) = schema.as_object_mut() {
+        object.insert("title".to_string(), Value::String(title.to_string()));
+    }
+    schema
+}
diff --git a/crates/webui-cli/src/commands/state_schema/inference.rs b/crates/webui-cli/src/commands/state_schema/inference.rs
new file mode 100644
index 00000000..072f28d8
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/inference.rs
@@ -0,0 +1,419 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use anyhow::{Context, Result};
+use serde_json::Value;
+use std::collections::{BTreeMap, BTreeSet};
+use std::rc::Rc;
+use webui_protocol::condition_expr;
+use webui_protocol::web_ui_fragment;
+use webui_protocol::{
+    ComparisonOperator, ConditionExpr, WebUIFragment, WebUIFragmentAttribute, WebUIProtocol,
+};
+
+use super::model::{add_array_path, add_resolved_path, node_to_schema, InferredKind, Node};
+use super::scope::{array_item_path, has_component_scope, resolve_path, BindingOrigin, Scope};
+
+struct WalkFrame<'a> {
+    fragment_id: &'a str,
+    fragments: &'a [WebUIFragment],
+    next_index: usize,
+    scope: Rc<Scope>,
+    component_attrs: BTreeMap<String, BindingOrigin>,
+    collecting_component_attrs: bool,
+    binding_requirement: Requirement,
+}
+
+#[derive(Default)]
+struct WalkState<'a> {
+    stack: Vec<WalkFrame<'a>>,
+    active_fragments: BTreeSet<&'a str>,
+}
+
+enum NextFrame<'a> {
+    None,
+    Push {
+        fragment_id: &'a str,
+        scope: Rc<Scope>,
+        binding_requirement: Requirement,
+    },
+}
+
+#[derive(Clone, Copy)]
+enum Requirement {
+    Optional,
+    Scoped,
+    Required,
+}
+
+pub(super) struct SchemaInference<'a> {
+    protocol: &'a WebUIProtocol,
+    root: Node,
+}
+
+impl<'a> SchemaInference<'a> {
+    pub(super) fn new(protocol: &'a WebUIProtocol) -> Self {
+        Self {
+            protocol,
+            root: Node::root(),
+        }
+    }
+
+    pub(super) fn infer_entry(&mut self, fragment_id: &'a str) -> Result<()> {
+        self.infer_fragment(fragment_id, Rc::new(Scope::Root))
+    }
+
+    pub(super) fn infer_root_component(&mut self, fragment_id: &'a str) -> Result<()> {
+        self.infer_fragment(
+            fragment_id,
+            Rc::new(Scope::Component {
+                attrs: BTreeMap::new(),
+                require_global_fallback: true,
+            }),
+        )
+    }
+
+    fn infer_fragment(&mut self, fragment_id: &'a str, scope: Rc<Scope>) -> Result<()> {
+        let mut walk = WalkState::default();
+        self.push_frame(fragment_id, scope, Requirement::Required, &mut walk)?;
+
+        while !walk.stack.is_empty() {
+            let should_pop = walk
+                .stack
+                .last()
+                .is_some_and(|frame| frame.next_index >= frame.fragments.len());
+            if should_pop {
+                if let Some(frame) = walk.stack.pop() {
+                    walk.active_fragments.remove(frame.fragment_id);
+                }
+                continue;
+            }
+
+            let action = {
+                let Some(frame) = walk.stack.last_mut() else {
+                    break;
+                };
+                let fragment = &frame.fragments[frame.next_index];
+                frame.next_index += 1;
+                self.process_fragment(fragment, frame)
+            };
+
+            if let NextFrame::Push {
+                fragment_id,
+                scope,
+                binding_requirement,
+            } = action
+            {
+                self.push_frame(fragment_id, scope, binding_requirement, &mut walk)?;
+            }
+        }
+        Ok(())
+    }
+
+    pub(super) fn into_schema(self) -> Value {
+        node_to_schema(&self.root)
+    }
+
+    fn push_frame(
+        &self,
+        fragment_id: &'a str,
+        scope: Rc<Scope>,
+        binding_requirement: Requirement,
+        walk: &mut WalkState<'a>,
+    ) -> Result<()> {
+        if walk.active_fragments.contains(fragment_id) {
+            return Ok(());
+        }
+        let fragment_list = self
+            .protocol
+            .fragments
+            .get(fragment_id)
+            .with_context(|| format!("Protocol fragment '{fragment_id}' was not found"))?;
+        walk.active_fragments.insert(fragment_id);
+        walk.stack.push(WalkFrame {
+            fragment_id,
+            fragments: &fragment_list.fragments,
+            next_index: 0,
+            scope,
+            component_attrs: BTreeMap::new(),
+            collecting_component_attrs: false,
+            binding_requirement,
+        });
+        Ok(())
+    }
+
+    fn process_fragment(
+        &mut self,
+        fragment: &'a WebUIFragment,
+        frame: &mut WalkFrame<'a>,
+    ) -> NextFrame<'a> {
+        match fragment.fragment.as_ref() {
+            Some(web_ui_fragment::Fragment::Signal(signal)) => {
+                if !is_runtime_signal(&signal.value, signal.raw) {
+                    add_path(
+                        &mut self.root,
+                        &frame.scope,
+                        &signal.value,
+                        if signal.raw {
+                            InferredKind::String
+                        } else {
+                            InferredKind::Scalar
+                        },
+                        frame.binding_requirement,
+                    );
+                }
+                NextFrame::None
+            }
+            Some(web_ui_fragment::Fragment::ForLoop(for_loop)) => {
+                let origin = resolve_path(&frame.scope, &for_loop.collection);
+                let item_origin = match origin {
+                    BindingOrigin::RootPath { path, required } => {
+                        add_array_path(&mut self.root, &path, required);
+                        BindingOrigin::RootPath {
+                            path: array_item_path(path),
+                            required,
+                        }
+                    }
+                    BindingOrigin::LocalOnly => BindingOrigin::LocalOnly,
+                };
+                NextFrame::Push {
+                    fragment_id: &for_loop.fragment_id,
+                    scope: Rc::new(Scope::Loop {
+                        item: for_loop.item.clone(),
+                        origin: item_origin,
+                        parent: Rc::clone(&frame.scope),
+                    }),
+                    binding_requirement: Requirement::Required,
+                }
+            }
+            Some(web_ui_fragment::Fragment::IfCond(if_cond)) => {
+                if let Some(condition) = &if_cond.condition {
+                    add_condition_paths(&mut self.root, &frame.scope, condition);
+                }
+                NextFrame::Push {
+                    fragment_id: &if_cond.fragment_id,
+                    scope: Rc::clone(&frame.scope),
+                    binding_requirement: Requirement::Required,
+                }
+            }
+            Some(web_ui_fragment::Fragment::Attribute(attribute)) => {
+                self.process_attribute(attribute, frame)
+            }
+            Some(web_ui_fragment::Fragment::Component(component)) => {
+                let attrs = if frame.collecting_component_attrs {
+                    frame.collecting_component_attrs = false;
+                    std::mem::take(&mut frame.component_attrs)
+                } else {
+                    BTreeMap::new()
+                };
+                let require_global_fallback = !has_component_scope(&frame.scope);
+                NextFrame::Push {
+                    fragment_id: &component.fragment_id,
+                    scope: Rc::new(Scope::Component {
+                        attrs,
+                        require_global_fallback,
+                    }),
+                    binding_requirement: Requirement::Required,
+                }
+            }
+            Some(web_ui_fragment::Fragment::Raw(_))
+            | Some(web_ui_fragment::Fragment::Plugin(_))
+            | Some(web_ui_fragment::Fragment::Route(_))
+            | Some(web_ui_fragment::Fragment::Outlet(_))
+            | None => NextFrame::None,
+        }
+    }
+
+    fn process_attribute(
+        &mut self,
+        attribute: &'a WebUIFragmentAttribute,
+        frame: &mut WalkFrame<'a>,
+    ) -> NextFrame<'a> {
+        if attribute.attr_start {
+            frame.component_attrs.clear();
+            frame.collecting_component_attrs = true;
+        }
+
+        if let Some(condition) = &attribute.condition_tree {
+            add_condition_paths(&mut self.root, &frame.scope, condition);
+        } else if !attribute.template.is_empty() {
+            // The template fragment is traversed below with the parent scope.
+        } else if !attribute.raw_value && !attribute.value.is_empty() {
+            add_path(
+                &mut self.root,
+                &frame.scope,
+                &attribute.value,
+                if attribute.complex {
+                    InferredKind::Any
+                } else {
+                    InferredKind::Scalar
+                },
+                Requirement::Scoped,
+            );
+        }
+
+        if frame.collecting_component_attrs && !attribute.attr_skip {
+            let name = component_attr_name(&attribute.name);
+            let origin = if attribute.condition_tree.is_some()
+                || !attribute.template.is_empty()
+                || attribute.raw_value
+                || attribute.value.is_empty()
+                || !attribute.complex
+            {
+                BindingOrigin::LocalOnly
+            } else {
+                resolve_path(&frame.scope, &attribute.value)
+            };
+            frame.component_attrs.insert(name, origin);
+        }
+
+        if attribute.template.is_empty() {
+            NextFrame::None
+        } else {
+            NextFrame::Push {
+                fragment_id: &attribute.template,
+                scope: Rc::clone(&frame.scope),
+                binding_requirement: Requirement::Scoped,
+            }
+        }
+    }
+}
+
+fn component_attr_name(name: &str) -> String {
+    let stripped = name.strip_prefix(':').unwrap_or(name);
+    webui_protocol::attrs::attribute_to_camel(stripped)
+}
+
+fn add_condition_paths(root: &mut Node, scope: &Rc<Scope>, condition: &ConditionExpr) {
+    let mut pending = vec![condition];
+    while let Some(current) = pending.pop() {
+        match current.expr.as_ref() {
+            Some(condition_expr::Expr::Identifier(identifier)) => {
+                add_path(
+                    root,
+                    scope,
+                    &identifier.value,
+                    InferredKind::Any,
+                    Requirement::Optional,
+                );
+            }
+            Some(condition_expr::Expr::Predicate(predicate)) => {
+                add_predicate_paths(root, scope, predicate);
+            }
+            Some(condition_expr::Expr::Not(not)) => {
+                if let Some(inner) = &not.condition {
+                    pending.push(inner);
+                }
+            }
+            Some(condition_expr::Expr::Compound(compound)) => {
+                if let Some(right) = &compound.right {
+                    pending.push(right);
+                }
+                if let Some(left) = &compound.left {
+                    pending.push(left);
+                }
+            }
+            None => {}
+        }
+    }
+}
+
+fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_protocol::Predicate) {
+    let operator = ComparisonOperator::try_from(predicate.operator).ok();
+    let left_literal = literal_kind(&predicate.left);
+    let right_literal = literal_kind(&predicate.right);
+
+    match operator {
+        Some(ComparisonOperator::GreaterThan)
+        | Some(ComparisonOperator::LessThan)
+        | Some(ComparisonOperator::GreaterThanOrEqual)
+        | Some(ComparisonOperator::LessThanOrEqual) => {
+            if left_literal.is_none() {
+                add_path(
+                    root,
+                    scope,
+                    &predicate.left,
+                    InferredKind::Number,
+                    Requirement::Optional,
+                );
+            }
+            if right_literal.is_none() {
+                add_path(
+                    root,
+                    scope,
+                    &predicate.right,
+                    InferredKind::Number,
+                    Requirement::Optional,
+                );
+            }
+        }
+        _ => match (left_literal, right_literal) {
+            (None, Some(kind)) => {
+                add_path(root, scope, &predicate.left, kind, Requirement::Optional)
+            }
+            (Some(kind), None) => {
+                add_path(root, scope, &predicate.right, kind, Requirement::Optional)
+            }
+            (None, None) => {
+                add_path(
+                    root,
+                    scope,
+                    &predicate.left,
+                    InferredKind::Scalar,
+                    Requirement::Optional,
+                );
+                add_path(
+                    root,
+                    scope,
+                    &predicate.right,
+                    InferredKind::Scalar,
+                    Requirement::Optional,
+                );
+            }
+            (Some(_), Some(_)) => {}
+        },
+    }
+}
+
+fn literal_kind(value: &str) -> Option<InferredKind> {
+    if value == "true" || value == "false" {
+        return Some(InferredKind::Boolean);
+    }
+    if value.parse::<f64>().is_ok() {
+        return Some(InferredKind::Number);
+    }
+    if (value.starts_with('"') && value.ends_with('"'))
+        || (value.starts_with('\'') && value.ends_with('\''))
+    {
+        return Some(InferredKind::String);
+    }
+    None
+}
+
+fn add_path(
+    root: &mut Node,
+    scope: &Rc<Scope>,
+    path: &str,
+    kind: InferredKind,
+    requirement: Requirement,
+) {
+    if path.is_empty() || literal_kind(path).is_some() {
+        return;
+    }
+    if let BindingOrigin::RootPath {
+        path: resolved,
+        required: scope_required,
+    } = resolve_path(scope, path)
+    {
+        let required = match requirement {
+            Requirement::Optional => false,
+            Requirement::Scoped => scope_required,
+            Requirement::Required => true,
+        };
+        add_resolved_path(root, &resolved, kind, required);
+    }
+}
+
+fn is_runtime_signal(value: &str, raw: bool) -> bool {
+    raw && matches!(value, "head_end" | "body_start" | "body_end")
+}
diff --git a/crates/webui-cli/src/commands/state_schema/model.rs b/crates/webui-cli/src/commands/state_schema/model.rs
new file mode 100644
index 00000000..19b06210
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/model.rs
@@ -0,0 +1,264 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use serde_json::{Map, Value};
+use std::collections::BTreeMap;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum InferredKind {
+    Any,
+    Scalar,
+    String,
+    Boolean,
+    Number,
+    Object,
+}
+
+#[derive(Default)]
+pub(super) struct Node {
+    kind: Option<InferredKind>,
+    required: bool,
+    length_kind: Option<InferredKind>,
+    length_required: bool,
+    children: BTreeMap<String, Node>,
+    array_item: Option<Box<Node>>,
+}
+
+enum SchemaTask<'a> {
+    Visit(&'a Node),
+    FinishArray,
+    FinishObject(&'a Node),
+}
+
+impl Node {
+    pub(super) fn root() -> Self {
+        Self {
+            kind: Some(InferredKind::Object),
+            ..Self::default()
+        }
+    }
+}
+
+pub(super) fn add_resolved_path(root: &mut Node, path: &str, kind: InferredKind, required: bool) {
+    let mut parts = path.split('.').filter(|part| !part.is_empty()).peekable();
+    let mut current = root;
+    let mut saw_part = false;
+    while let Some(part) = parts.next() {
+        if part == "length" && saw_part && parts.peek().is_none() {
+            current.length_kind = Some(merge_kind(current.length_kind, kind));
+            current.length_required |= required;
+            return;
+        }
+        current = descend_node(current, part, required);
+        saw_part = true;
+    }
+    if saw_part {
+        current.kind = Some(merge_kind(current.kind, kind));
+    }
+}
+
+pub(super) fn add_array_path(root: &mut Node, path: &str, required: bool) {
+    let mut current = root;
+    let mut saw_part = false;
+    for part in path.split('.').filter(|part| !part.is_empty()) {
+        current = descend_node(current, part, required);
+        saw_part = true;
+    }
+    if saw_part {
+        current
+            .array_item
+            .get_or_insert_with(|| Box::new(Node::default()));
+    }
+}
+
+pub(super) fn node_to_schema(root: &Node) -> Value {
+    let mut tasks = vec![SchemaTask::Visit(root)];
+    let mut values = Vec::new();
+    while let Some(task) = tasks.pop() {
+        match task {
+            SchemaTask::Visit(node) => {
+                if let Some(item) = &node.array_item {
+                    tasks.push(SchemaTask::FinishArray);
+                    tasks.push(SchemaTask::Visit(item));
+                } else if !node.children.is_empty() || node.kind == Some(InferredKind::Object) {
+                    tasks.push(SchemaTask::FinishObject(node));
+                    for child in node.children.values().rev() {
+                        tasks.push(SchemaTask::Visit(child));
+                    }
+                } else if let Some(kind) = node.length_kind {
+                    values.push(length_parent_schema(kind, node.length_required, node.kind));
+                } else {
+                    values.push(leaf_schema(node.kind.unwrap_or(InferredKind::Any)));
+                }
+            }
+            SchemaTask::FinishArray => {
+                let item = values.pop().unwrap_or_else(any_schema);
+                let mut schema = Map::new();
+                schema.insert("items".to_string(), item);
+                schema.insert("type".to_string(), Value::String("array".to_string()));
+                values.push(Value::Object(schema));
+            }
+            SchemaTask::FinishObject(node) => {
+                let child_count = node.children.len();
+                let split_at = values.len().saturating_sub(child_count);
+                let child_values = values.split_off(split_at);
+                let mut properties = Map::new();
+                let required_count = node
+                    .children
+                    .values()
+                    .filter(|child| child.required)
+                    .count();
+                let mut required = Vec::with_capacity(required_count);
+                for ((name, child), child_schema) in node.children.iter().zip(child_values) {
+                    properties.insert(name.clone(), child_schema);
+                    if child.required {
+                        required.push(Value::String(name.clone()));
+                    }
+                }
+                if let Some(kind) = node.length_kind {
+                    if !properties.contains_key("length") {
+                        properties.insert("length".to_string(), leaf_schema(kind));
+                        if node.length_required {
+                            required.push(Value::String("length".to_string()));
+                        }
+                    }
+                }
+                required.sort_unstable_by(|left, right| left.as_str().cmp(&right.as_str()));
+
+                let mut schema = Map::new();
+                schema.insert("properties".to_string(), Value::Object(properties));
+                schema.insert("required".to_string(), Value::Array(required));
+                schema.insert("type".to_string(), Value::String("object".to_string()));
+                values.push(Value::Object(schema));
+            }
+        }
+    }
+    values.pop().unwrap_or_else(|| object_schema(Map::new()))
+}
+
+fn descend_node<'a>(current: &'a mut Node, part: &str, required: bool) -> &'a mut Node {
+    let (name, array_depth) = split_array_suffix(part);
+    if array_depth > 0 {
+        current.kind.get_or_insert(InferredKind::Object);
+        let array = current.children.entry(name.to_string()).or_default();
+        array.required |= required;
+        let mut item = array;
+        for _ in 0..array_depth {
+            item = item
+                .array_item
+                .get_or_insert_with(|| Box::new(Node::default()));
+        }
+        return item;
+    }
+
+    fn split_array_suffix(mut part: &str) -> (&str, usize) {
+        let mut depth = 0;
+        while let Some(base) = part.strip_suffix("[]") {
+            part = base;
+            depth += 1;
+        }
+        (part, depth)
+    }
+
+    current.kind.get_or_insert(InferredKind::Object);
+    let child = current.children.entry(part.to_string()).or_default();
+    child.required |= required;
+    child
+}
+
+fn merge_kind(existing: Option<InferredKind>, incoming: InferredKind) -> InferredKind {
+    match (existing, incoming) {
+        (Some(InferredKind::Object), _) | (_, InferredKind::Object) => InferredKind::Object,
+        (Some(InferredKind::Any), specific) => specific,
+        (Some(specific), InferredKind::Any) => specific,
+        (Some(InferredKind::Scalar), specific) => specific,
+        (Some(specific), InferredKind::Scalar) => specific,
+        (Some(existing), incoming) if existing == incoming => existing,
+        (Some(_), _) => InferredKind::Scalar,
+        (None, incoming) => incoming,
+    }
+}
+
+fn leaf_schema(kind: InferredKind) -> Value {
+    match kind {
+        InferredKind::Scalar => scalar_schema(),
+        InferredKind::Any => any_schema(),
+        InferredKind::String => type_schema("string"),
+        InferredKind::Boolean => type_schema("boolean"),
+        InferredKind::Number => type_schema("number"),
+        InferredKind::Object => object_schema(Map::new()),
+    }
+}
+
+fn any_schema() -> Value {
+    Value::Object(Map::new())
+}
+
+fn length_parent_schema(
+    kind: InferredKind,
+    length_required: bool,
+    parent_kind: Option<InferredKind>,
+) -> Value {
+    match parent_kind {
+        Some(InferredKind::Scalar | InferredKind::String) => return type_schema("string"),
+        Some(InferredKind::Number | InferredKind::Boolean) => return Value::Bool(false),
+        Some(InferredKind::Object) => return object_schema(Map::new()),
+        Some(InferredKind::Any) | None => {}
+    }
+
+    let mut array_schema = Map::new();
+    array_schema.insert("items".to_string(), any_schema());
+    array_schema.insert("type".to_string(), Value::String("array".to_string()));
+
+    let mut object_properties = Map::new();
+    object_properties.insert("length".to_string(), leaf_schema(kind));
+    let mut object_schema = Map::new();
+    object_schema.insert("properties".to_string(), Value::Object(object_properties));
+    object_schema.insert(
+        "required".to_string(),
+        if length_required {
+            Value::Array(vec![Value::String("length".to_string())])
+        } else {
+            Value::Array(Vec::new())
+        },
+    );
+    object_schema.insert("type".to_string(), Value::String("object".to_string()));
+
+    let mut schema = Map::new();
+    schema.insert(
+        "anyOf".to_string(),
+        Value::Array(vec![
+            type_schema("string"),
+            Value::Object(array_schema),
+            Value::Object(object_schema),
+        ]),
+    );
+    Value::Object(schema)
+}
+
+fn scalar_schema() -> Value {
+    let mut schema = Map::new();
+    schema.insert(
+        "type".to_string(),
+        Value::Array(vec![
+            Value::String("string".to_string()),
+            Value::String("number".to_string()),
+            Value::String("boolean".to_string()),
+        ]),
+    );
+    Value::Object(schema)
+}
+
+fn type_schema(kind: &str) -> Value {
+    let mut schema = Map::new();
+    schema.insert("type".to_string(), Value::String(kind.to_string()));
+    Value::Object(schema)
+}
+
+fn object_schema(properties: Map<String, Value>) -> Value {
+    let mut schema = Map::new();
+    schema.insert("properties".to_string(), Value::Object(properties));
+    schema.insert("required".to_string(), Value::Array(Vec::new()));
+    schema.insert("type".to_string(), Value::String("object".to_string()));
+    Value::Object(schema)
+}
diff --git a/crates/webui-cli/src/commands/state_schema/scope.rs b/crates/webui-cli/src/commands/state_schema/scope.rs
new file mode 100644
index 00000000..a502a6ed
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/scope.rs
@@ -0,0 +1,99 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+use std::collections::BTreeMap;
+use std::rc::Rc;
+
+#[derive(Clone)]
+pub(super) enum BindingOrigin {
+    RootPath { path: String, required: bool },
+    LocalOnly,
+}
+
+pub(super) enum Scope {
+    Root,
+    Component {
+        attrs: BTreeMap<String, BindingOrigin>,
+        require_global_fallback: bool,
+    },
+    Loop {
+        item: String,
+        origin: BindingOrigin,
+        parent: Rc<Scope>,
+    },
+}
+
+pub(super) fn resolve_path(scope: &Rc<Scope>, path: &str) -> BindingOrigin {
+    let (first, rest) = path
+        .split_once('.')
+        .map_or((path, None), |(first, rest)| (first, Some(rest)));
+    let mut current = scope.as_ref();
+    loop {
+        match current {
+            Scope::Root => {
+                return BindingOrigin::RootPath {
+                    path: path.to_string(),
+                    required: true,
+                };
+            }
+            Scope::Component {
+                attrs,
+                require_global_fallback,
+            } => {
+                let Some(origin) = attrs.get(first) else {
+                    return BindingOrigin::RootPath {
+                        path: path.to_string(),
+                        required: *require_global_fallback,
+                    };
+                };
+                return append_origin(origin, rest);
+            }
+            Scope::Loop {
+                item,
+                origin,
+                parent,
+            } => {
+                if item == first {
+                    return append_origin(origin, rest);
+                }
+                current = parent.as_ref();
+            }
+        }
+    }
+}
+
+pub(super) fn has_component_scope(scope: &Rc<Scope>) -> bool {
+    let mut current = scope.as_ref();
+    loop {
+        match current {
+            Scope::Root => return false,
+            Scope::Component { .. } => return true,
+            Scope::Loop { parent, .. } => current = parent.as_ref(),
+        }
+    }
+}
+
+pub(super) fn array_item_path(mut collection: String) -> String {
+    collection.reserve(2);
+    collection.push_str("[]");
+    collection
+}
+
+fn append_origin(origin: &BindingOrigin, rest: Option<&str>) -> BindingOrigin {
+    match origin {
+        BindingOrigin::RootPath { path, required } => {
+            let mut resolved =
+                String::with_capacity(path.len() + rest.map_or(0, |value| value.len() + 1));
+            resolved.push_str(path);
+            if let Some(rest) = rest {
+                resolved.push('.');
+                resolved.push_str(rest);
+            }
+            BindingOrigin::RootPath {
+                path: resolved,
+                required: *required,
+            }
+        }
+        BindingOrigin::LocalOnly => BindingOrigin::LocalOnly,
+    }
+}
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
new file mode 100644
index 00000000..03aba1f2
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
@@ -0,0 +1,63 @@
+---
+source: crates/webui-cli/src/commands/state_schema/tests.rs
+expression: schema
+---
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "alignment": {
+      "type": "string"
+    },
+    "globalLabel": {
+      "type": [
+        "string",
+        "number",
+        "boolean"
+      ]
+    },
+    "pageTitle": {
+      "type": [
+        "string",
+        "number",
+        "boolean"
+      ]
+    },
+    "payload": {},
+    "remainingCount": {
+      "type": [
+        "string",
+        "number",
+        "boolean"
+      ]
+    },
+    "trustedHtml": {
+      "type": "string"
+    },
+    "user": {
+      "properties": {
+        "active": {},
+        "name": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "globalLabel",
+    "pageTitle",
+    "payload",
+    "remainingCount",
+    "trustedHtml",
+    "user"
+  ],
+  "title": "ComponentScopeState",
+  "type": "object"
+}
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
new file mode 100644
index 00000000..b99329c1
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
@@ -0,0 +1,105 @@
+---
+source: crates/webui-cli/src/commands/state_schema/tests.rs
+expression: schema
+---
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "properties": {
+    "flexible": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "items": {},
+          "type": "array"
+        },
+        {
+          "properties": {
+            "length": {
+              "type": [
+                "string",
+                "number",
+                "boolean"
+              ]
+            }
+          },
+          "required": [
+            "length"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "groups": {
+      "items": {
+        "properties": {
+          "items": {
+            "items": {
+              "properties": {
+                "count": {
+                  "type": "number"
+                },
+                "name": {
+                  "type": [
+                    "string",
+                    "number",
+                    "boolean"
+                  ]
+                }
+              },
+              "required": [
+                "count",
+                "name"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "name": {
+            "type": [
+              "string",
+              "number",
+              "boolean"
+            ]
+          }
+        },
+        "required": [
+          "items",
+          "name"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "label": {
+      "type": "string"
+    },
+    "matrix": {
+      "items": {
+        "items": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "type": "array"
+      },
+      "type": "array"
+    },
+    "unobserved": {
+      "items": {},
+      "type": "array"
+    }
+  },
+  "required": [
+    "flexible",
+    "groups",
+    "label",
+    "matrix",
+    "unobserved"
+  ],
+  "title": "NestedCollectionsState",
+  "type": "object"
+}
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
new file mode 100644
index 00000000..8bc24f23
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
@@ -0,0 +1,114 @@
+---
+source: crates/webui-cli/src/commands/state_schema/tests.rs
+expression: "SchemaDocument::new(&schema)"
+---
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$defs": {
+    "route": {
+      "properties": {
+        "homeTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "shellTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        }
+      },
+      "required": [
+        "homeTitle",
+        "shellTitle"
+      ],
+      "title": "RoutedShellState (/)",
+      "type": "object"
+    },
+    "route.details.:id": {
+      "properties": {
+        "detailTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "homeTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "shellTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        }
+      },
+      "required": [
+        "detailTitle",
+        "homeTitle",
+        "shellTitle"
+      ],
+      "title": "RoutedShellState (/details/:id)",
+      "type": "object"
+    },
+    "route.settings": {
+      "properties": {
+        "homeTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "settingsTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "shellTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        }
+      },
+      "required": [
+        "homeTitle",
+        "settingsTitle",
+        "shellTitle"
+      ],
+      "title": "RoutedShellState (/settings)",
+      "type": "object"
+    }
+  },
+  "anyOf": [
+    {
+      "$ref": "#/$defs/route"
+    },
+    {
+      "$ref": "#/$defs/route.details.:id"
+    },
+    {
+      "$ref": "#/$defs/route.settings"
+    }
+  ],
+  "title": "RoutedShellState",
+  "x-webui-routes": {
+    "/": "#/$defs/route",
+    "/details/:id": "#/$defs/route.details.:id",
+    "/settings": "#/$defs/route.settings"
+  }
+}
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
new file mode 100644
index 00000000..22fb73ee
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
@@ -0,0 +1,645 @@
+---
+source: crates/webui-cli/src/commands/state_schema/tests.rs
+expression: "SchemaDocument::new(&schema)"
+---
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$defs": {
+    "route": {
+      "properties": {
+        "appTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "basePath": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "language": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sections": {
+          "items": {
+            "properties": {
+              "icon": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "icon",
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "textdirection": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        }
+      },
+      "required": [
+        "appTitle",
+        "basePath",
+        "language",
+        "sections",
+        "textdirection",
+        "title"
+      ],
+      "title": "RoutesState (/)",
+      "type": "object"
+    },
+    "route.sections.:sectionId": {
+      "properties": {
+        "appTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "basePath": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "language": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionIcon": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sections": {
+          "items": {
+            "properties": {
+              "icon": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "icon",
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "textdirection": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topicId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topics": {
+          "items": {
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "appTitle",
+        "basePath",
+        "language",
+        "sectionIcon",
+        "sectionId",
+        "sectionName",
+        "sections",
+        "textdirection",
+        "title",
+        "topics"
+      ],
+      "title": "RoutesState (/sections/:sectionId)",
+      "type": "object"
+    },
+    "route.sections.:sectionId.topics.:topicId": {
+      "properties": {
+        "appTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "basePath": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "language": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessonId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessons": {
+          "items": {
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "sectionIcon": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sections": {
+          "items": {
+            "properties": {
+              "icon": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "icon",
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "textdirection": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topicId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topicName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topics": {
+          "items": {
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "appTitle",
+        "basePath",
+        "language",
+        "lessons",
+        "sectionIcon",
+        "sectionId",
+        "sectionName",
+        "sections",
+        "textdirection",
+        "title",
+        "topicId",
+        "topicName",
+        "topics"
+      ],
+      "title": "RoutesState (/sections/:sectionId/topics/:topicId)",
+      "type": "object"
+    },
+    "route.sections.:sectionId.topics.:topicId.lessons.:lessonId": {
+      "properties": {
+        "appTitle": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "basePath": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "language": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessonContent": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessonId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessonName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "lessons": {
+          "items": {
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "sectionIcon": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sectionName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "sections": {
+          "items": {
+            "properties": {
+              "icon": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "icon",
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "textdirection": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topicId": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topicName": {
+          "type": [
+            "string",
+            "number",
+            "boolean"
+          ]
+        },
+        "topics": {
+          "items": {
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "number",
+                  "boolean"
+                ]
+              }
+            },
+            "required": [
+              "id",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "appTitle",
+        "basePath",
+        "language",
+        "lessonContent",
+        "lessonName",
+        "lessons",
+        "sectionIcon",
+        "sectionId",
+        "sectionName",
+        "sections",
+        "textdirection",
+        "title",
+        "topicId",
+        "topicName",
+        "topics"
+      ],
+      "title": "RoutesState (/sections/:sectionId/topics/:topicId/lessons/:lessonId)",
+      "type": "object"
+    }
+  },
+  "anyOf": [
+    {
+      "$ref": "#/$defs/route"
+    },
+    {
+      "$ref": "#/$defs/route.sections.:sectionId"
+    },
+    {
+      "$ref": "#/$defs/route.sections.:sectionId.topics.:topicId"
+    },
+    {
+      "$ref": "#/$defs/route.sections.:sectionId.topics.:topicId.lessons.:lessonId"
+    }
+  ],
+  "title": "RoutesState",
+  "x-webui-routes": {
+    "/": "#/$defs/route",
+    "/sections/:sectionId": "#/$defs/route.sections.:sectionId",
+    "/sections/:sectionId/topics/:topicId": "#/$defs/route.sections.:sectionId.topics.:topicId",
+    "/sections/:sectionId/topics/:topicId/lessons/:lessonId": "#/$defs/route.sections.:sectionId.topics.:topicId.lessons.:lessonId"
+  }
+}
diff --git a/crates/webui-cli/src/commands/state_schema/tests.rs b/crates/webui-cli/src/commands/state_schema/tests.rs
new file mode 100644
index 00000000..6abf2573
--- /dev/null
+++ b/crates/webui-cli/src/commands/state_schema/tests.rs
@@ -0,0 +1,394 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+#![allow(clippy::disallowed_methods)]
+
+use super::*;
+use std::collections::BTreeSet;
+use std::fs;
+use std::path::{Path, PathBuf};
+use webui::{BuildOptions, Plugin};
+
+struct ExampleCase {
+    name: &'static str,
+    plugin: Plugin,
+    uses_theme: bool,
+}
+
+const EXAMPLES: &[ExampleCase] = &[
+    ExampleCase {
+        name: "calculator",
+        plugin: Plugin::WebUI,
+        uses_theme: false,
+    },
+    ExampleCase {
+        name: "commerce",
+        plugin: Plugin::WebUI,
+        uses_theme: false,
+    },
+    ExampleCase {
+        name: "component-assets",
+        plugin: Plugin::WebUI,
+        uses_theme: true,
+    },
+    ExampleCase {
+        name: "contact-book-manager",
+        plugin: Plugin::WebUI,
+        uses_theme: true,
+    },
+    ExampleCase {
+        name: "hello-world",
+        plugin: Plugin::WebUI,
+        uses_theme: true,
+    },
+    ExampleCase {
+        name: "todo-fast",
+        plugin: Plugin::FastV3,
+        uses_theme: true,
+    },
+    ExampleCase {
+        name: "todo-webui",
+        plugin: Plugin::WebUI,
+        uses_theme: false,
+    },
+];
+
+#[test]
+fn snapshots_component_scope_schema() {
+    let schema = build_fixture_schema("component-scope", "ComponentScopeState");
+    insta::assert_json_snapshot!(SchemaDocument::new(&schema));
+}
+
+#[test]
+fn snapshots_nested_collection_schema() {
+    let schema = build_fixture_schema("nested-collections", "NestedCollectionsState");
+    insta::assert_json_snapshot!(SchemaDocument::new(&schema));
+}
+
+#[test]
+fn snapshots_routes_example_schema_bundle() {
+    let app_dir = workspace_root().join("examples/app/routes/src");
+    let schema = build_schema(&app_dir, Plugin::WebUI, None, "RoutesState");
+    insta::assert_json_snapshot!(SchemaDocument::new(&schema));
+}
+
+#[test]
+fn snapshots_routes_declared_in_component_schema_bundle() {
+    let schema = build_fixture_schema("routed-shell", "RoutedShellState");
+    insta::assert_json_snapshot!(SchemaDocument::new(&schema));
+}
+
+#[test]
+fn route_definition_keys_are_injective_for_common_collisions() {
+    assert_ne!(route_definition_key("/"), route_definition_key("/root"));
+    assert_ne!(
+        route_definition_key("/:id"),
+        route_definition_key("/param_id")
+    );
+    assert_ne!(route_definition_key("/A"), route_definition_key("/a"));
+    assert_ne!(route_definition_key("/a.b"), route_definition_key("/a/b"));
+    assert_eq!(
+        route_definition_key("/sections/:sectionId"),
+        "route.sections.:sectionId"
+    );
+}
+
+#[test]
+fn optional_child_replaces_parent_only_route_chain() {
+    let route = WebUIFragmentRoute {
+        path: "/".to_string(),
+        fragment_id: "shell".to_string(),
+        children: vec![WebUIFragmentRoute {
+            path: ":tab?".to_string(),
+            fragment_id: "tab-page".to_string(),
+            exact: true,
+            ..WebUIFragmentRoute::default()
+        }],
+        ..WebUIFragmentRoute::default()
+    };
+    let protocol = protocol_with_entry_routes(vec![route]);
+    let routes = collect_route_chains(&protocol, "index.html").unwrap();
+
+    assert_eq!(routes.len(), 1);
+    assert_eq!(routes[0].path, "/:tab?");
+    assert_eq!(routes[0].components, ["shell", "tab-page"]);
+}
+
+#[test]
+fn zero_segment_child_detection_matches_route_syntax() {
+    assert!(child_matches_parent_path("/parent", ""));
+    assert!(child_matches_parent_path("/parent", "./"));
+    assert!(child_matches_parent_path("/parent", ":id?"));
+    assert!(child_matches_parent_path("/parent", "*rest"));
+    assert!(!child_matches_parent_path("/parent", "./child"));
+}
+
+#[test]
+fn routes_inside_control_flow_fragments_are_discovered() {
+    let if_route = WebUIFragmentRoute {
+        path: "/conditional".to_string(),
+        fragment_id: "conditional-page".to_string(),
+        exact: true,
+        ..WebUIFragmentRoute::default()
+    };
+    let loop_route = WebUIFragmentRoute {
+        path: "/repeated".to_string(),
+        fragment_id: "repeated-page".to_string(),
+        exact: true,
+        ..WebUIFragmentRoute::default()
+    };
+    let records = std::collections::HashMap::from([
+        (
+            "index.html".to_string(),
+            webui_protocol::FragmentList {
+                fragments: vec![
+                    webui_protocol::WebUIFragment::if_cond(
+                        webui_protocol::ConditionExpr::identifier("showRoutes"),
+                        "if-routes",
+                    ),
+                    webui_protocol::WebUIFragment::for_loop("item", "routeItems", "for-routes"),
+                ],
+            },
+        ),
+        (
+            "if-routes".to_string(),
+            webui_protocol::FragmentList {
+                fragments: vec![webui_protocol::WebUIFragment::route_from(if_route)],
+            },
+        ),
+        (
+            "for-routes".to_string(),
+            webui_protocol::FragmentList {
+                fragments: vec![webui_protocol::WebUIFragment::route_from(loop_route)],
+            },
+        ),
+        (
+            "conditional-page".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+        (
+            "repeated-page".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+    ]);
+    let protocol = WebUIProtocol::new(records);
+    let routes = collect_route_chains(&protocol, "index.html").unwrap();
+    let paths: Vec<&str> = routes.iter().map(|route| route.path.as_str()).collect();
+
+    assert_eq!(paths, ["/conditional", "/repeated"]);
+}
+
+#[test]
+fn example_state_files_match_generated_schemas() {
+    let workspace = workspace_root();
+    assert_all_state_examples_are_covered(&workspace);
+    let theme_path = workspace.join("packages/webui-examples-theme/tokens.json");
+
+    for example in EXAMPLES {
+        let app_root = workspace.join("examples/app").join(example.name);
+        let theme = example
+            .uses_theme
+            .then(|| webui::load_token_file(&theme_path).unwrap());
+        let result = build_app(&app_root.join("src"), example.plugin, theme.clone());
+        let schema = generate_schema(&result.protocol, "index.html", example.name).unwrap();
+        let state_path = app_root.join("data/state.json");
+        let mut state: Value =
+            serde_json::from_str(&fs::read_to_string(&state_path).unwrap()).unwrap();
+
+        if let Some(theme) = theme {
+            let token_css = webui_tokens::resolve_tokens(&result.protocol.tokens, &theme).unwrap();
+            webui_tokens::inject_token_css(&mut state, &token_css.css);
+        }
+        state
+            .as_object_mut()
+            .unwrap()
+            .insert("basePath".to_string(), Value::String("/".to_string()));
+
+        let state_schema = schema_for_route(&schema, "/");
+        let errors = validate_state(state_schema, &state);
+        assert!(
+            errors.is_empty(),
+            "{} state does not match its generated schema:\n{}",
+            example.name,
+            errors.join("\n")
+        );
+    }
+}
+
+#[test]
+fn missing_entry_is_an_error() {
+    let protocol = WebUIProtocol::new(std::collections::HashMap::new());
+    let error = generate_schema(&protocol, "missing.html", "MissingState").unwrap_err();
+    assert!(error.to_string().contains("missing.html"));
+}
+
+fn build_fixture_schema(fixture: &str, title: &str) -> Value {
+    let app_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+        .join("tests/fixtures/state-schema")
+        .join(fixture);
+    build_schema(&app_dir, Plugin::WebUI, None, title)
+}
+
+fn build_schema(
+    app_dir: &Path,
+    plugin: Plugin,
+    theme: Option<webui::TokenFile>,
+    title: &str,
+) -> Value {
+    let result = build_app(app_dir, plugin, theme);
+    generate_schema(&result.protocol, "index.html", title).unwrap()
+}
+
+fn build_app(
+    app_dir: &Path,
+    plugin: Plugin,
+    theme: Option<webui::TokenFile>,
+) -> webui::BuildResult {
+    webui::build(BuildOptions {
+        app_dir: app_dir.to_path_buf(),
+        plugin: Some(plugin),
+        theme,
+        ..BuildOptions::default()
+    })
+    .unwrap()
+}
+
+fn workspace_root() -> PathBuf {
+    PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..")
+}
+
+fn assert_all_state_examples_are_covered(workspace: &Path) {
+    let examples_dir = workspace.join("examples/app");
+    let discovered: BTreeSet<String> = fs::read_dir(&examples_dir)
+        .unwrap()
+        .filter_map(|entry| {
+            let entry = entry.unwrap();
+            let path = entry.path();
+            if path.join("src/index.html").is_file() && path.join("data/state.json").is_file() {
+                Some(entry.file_name().to_string_lossy().into_owned())
+            } else {
+                None
+            }
+        })
+        .collect();
+    let expected: BTreeSet<String> = EXAMPLES
+        .iter()
+        .map(|example| example.name.to_string())
+        .collect();
+    assert_eq!(discovered, expected);
+}
+
+fn schema_for_route<'a>(schema: &'a Value, route: &str) -> &'a Value {
+    let Some(routes) = schema.get("x-webui-routes").and_then(Value::as_object) else {
+        return schema;
+    };
+    let schema_ref = routes.get(route).and_then(Value::as_str).unwrap();
+    let key = schema_ref.strip_prefix("#/$defs/").unwrap();
+    &schema["$defs"][key]
+}
+
+fn validate_state(schema: &Value, state: &Value) -> Vec<String> {
+    let mut errors = Vec::new();
+    let mut pending = vec![(schema, state, "$".to_string())];
+    while let Some((current_schema, current_value, path)) = pending.pop() {
+        let actual_type = json_type(current_value);
+        if !schema_accepts_type(current_schema, actual_type) {
+            errors.push(format!(
+                "{path}: expected {}, found {actual_type}",
+                display_schema_type(current_schema)
+            ));
+            continue;
+        }
+
+        if let (Some(properties), Some(object)) = (
+            current_schema.get("properties").and_then(Value::as_object),
+            current_value.as_object(),
+        ) {
+            if let Some(required) = current_schema.get("required").and_then(Value::as_array) {
+                for name in required.iter().filter_map(Value::as_str) {
+                    if !object.contains_key(name) {
+                        errors.push(format!("{path}.{name}: missing required property"));
+                    }
+                }
+            }
+            for (name, child_schema) in properties {
+                if let Some(child_value) = object.get(name) {
+                    pending.push((child_schema, child_value, format!("{path}.{name}")));
+                }
+            }
+        } else if let (Some(item_schema), Some(items)) =
+            (current_schema.get("items"), current_value.as_array())
+        {
+            for (index, item) in items.iter().enumerate() {
+                pending.push((item_schema, item, format!("{path}[{index}]")));
+            }
+        }
+    }
+    errors
+}
+
+fn schema_accepts_type(schema: &Value, actual: &str) -> bool {
+    match schema.get("type") {
+        Some(Value::String(expected)) => expected == actual,
+        Some(Value::Array(expected)) => expected.iter().any(|value| value.as_str() == Some(actual)),
+        _ => true,
+    }
+}
+
+fn display_schema_type(schema: &Value) -> String {
+    match schema.get("type") {
+        Some(Value::String(expected)) => expected.clone(),
+        Some(Value::Array(expected)) => {
+            let mut display = String::new();
+            for value in expected.iter().filter_map(Value::as_str) {
+                if !display.is_empty() {
+                    display.push_str(" | ");
+                }
+                display.push_str(value);
+            }
+            display
+        }
+        _ => "any JSON value".to_string(),
+    }
+}
+
+fn json_type(value: &Value) -> &'static str {
+    match value {
+        Value::Null => "null",
+        Value::Bool(_) => "boolean",
+        Value::Number(_) => "number",
+        Value::String(_) => "string",
+        Value::Array(_) => "array",
+        Value::Object(_) => "object",
+    }
+}
+
+fn protocol_with_entry_routes(routes: Vec<WebUIFragmentRoute>) -> WebUIProtocol {
+    let mut component_ids = BTreeSet::new();
+    let mut pending: Vec<&WebUIFragmentRoute> = routes.iter().collect();
+    while let Some(route) = pending.pop() {
+        component_ids.insert(route.fragment_id.clone());
+        pending.extend(&route.children);
+    }
+    let fragments = routes
+        .into_iter()
+        .map(webui_protocol::WebUIFragment::route_from)
+        .collect();
+    let mut records = std::collections::HashMap::from([(
+        "index.html".to_string(),
+        webui_protocol::FragmentList { fragments },
+    )]);
+    for component_id in component_ids {
+        records.insert(
+            component_id,
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        );
+    }
+    WebUIProtocol::new(records)
+}
diff --git a/crates/webui-cli/src/main.rs b/crates/webui-cli/src/main.rs
index b06144a7..cb1eb064 100644
--- a/crates/webui-cli/src/main.rs
+++ b/crates/webui-cli/src/main.rs
@@ -33,6 +33,7 @@ fn main() {
         Commands::Build(args) => commands::build::execute(args),
         Commands::Inspect(args) => commands::inspect::execute(args),
         Commands::Serve(args) => commands::serve::execute(args),
+        Commands::Schema(args) => commands::state_schema::execute(args),
     };
 
     if let Err(err) = result {
diff --git a/crates/webui-cli/tests/fixtures/state-schema/component-scope/index.html b/crates/webui-cli/tests/fixtures/state-schema/component-scope/index.html
new file mode 100644
index 00000000..c2166976
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/component-scope/index.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <title>{{pageTitle}}</title>
+</head>
+<body>
+  <profile-card
+    display-name="{{user.name}}"
+    ?active="{{user.active}}"
+    label="Profile"
+    :payload="{{payload}}"
+  ></profile-card>
+  <p>{{remainingCount}}</p>
+  <div>{{{trustedHtml}}}</div>
+  <if condition="alignment == 'right'">
+    <span>Right aligned</span>
+  </if>
+</body>
+</html>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/component-scope/nested-label.html b/crates/webui-cli/tests/fixtures/state-schema/component-scope/nested-label.html
new file mode 100644
index 00000000..8245a91f
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/component-scope/nested-label.html
@@ -0,0 +1 @@
+<span>{{globalLabel}}</span>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/component-scope/profile-card.html b/crates/webui-cli/tests/fixtures/state-schema/component-scope/profile-card.html
new file mode 100644
index 00000000..1409fe2b
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/component-scope/profile-card.html
@@ -0,0 +1,5 @@
+<h1>{{displayName}}</h1>
+<if condition="active == true">
+  <span>{{label}}</span>
+</if>
+<nested-label></nested-label>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/nested-collections/group-list.html b/crates/webui-cli/tests/fixtures/state-schema/nested-collections/group-list.html
new file mode 100644
index 00000000..de5d12ad
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/nested-collections/group-list.html
@@ -0,0 +1,20 @@
+<for each="group in groups">
+  <h2>{{group.name}}</h2>
+  <for each="item in group.items">
+    <span>{{item.name}}</span>
+    <if condition="item.count > 0">
+      <strong>{{item.count}}</strong>
+    </if>
+  </for>
+</for>
+<span>{{label}}</span>
+<span>{{label.length}}</span>
+<span>{{flexible.length}}</span>
+<for each="row in matrix">
+  <for each="cell in row">
+    <span>{{cell}}</span>
+  </for>
+</for>
+<for each="unused in unobserved">
+  <span>Static item</span>
+</for>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/nested-collections/index.html b/crates/webui-cli/tests/fixtures/state-schema/nested-collections/index.html
new file mode 100644
index 00000000..3435102b
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/nested-collections/index.html
@@ -0,0 +1 @@
+<group-list :groups="{{groups}}"></group-list>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/routed-shell/app-shell.html b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/app-shell.html
new file mode 100644
index 00000000..4878053d
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/app-shell.html
@@ -0,0 +1,4 @@
+<h1>{{shellTitle}}</h1>
+<route path="/" component="home-page">
+  <route path="./details/:id" component="detail-page" exact />
+</route>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/routed-shell/detail-page.html b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/detail-page.html
new file mode 100644
index 00000000..9eea5141
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/detail-page.html
@@ -0,0 +1 @@
+<h3>{{detailTitle}}</h3>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/routed-shell/home-page.html b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/home-page.html
new file mode 100644
index 00000000..d3de8fb6
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/home-page.html
@@ -0,0 +1,3 @@
+<h2>{{homeTitle}}</h2>
+<route path="./settings" component="settings-page" exact />
+<outlet />
diff --git a/crates/webui-cli/tests/fixtures/state-schema/routed-shell/index.html b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/index.html
new file mode 100644
index 00000000..5b991168
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/index.html
@@ -0,0 +1 @@
+<app-shell></app-shell>
diff --git a/crates/webui-cli/tests/fixtures/state-schema/routed-shell/settings-page.html b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/settings-page.html
new file mode 100644
index 00000000..f5191aa0
--- /dev/null
+++ b/crates/webui-cli/tests/fixtures/state-schema/routed-shell/settings-page.html
@@ -0,0 +1 @@
+<h3>{{settingsTitle}}</h3>
diff --git a/docs/ai.md b/docs/ai.md
index 1256828a..6847d447 100644
--- a/docs/ai.md
+++ b/docs/ai.md
@@ -590,6 +590,7 @@ webui build ./src --out ./dist --plugin=webui
 | `--plugin <NAME>` | none | Plugin identifier (e.g. `webui`) |
 | `--components <PACKAGE>` | none | Extra component sources (repeatable) |
 | `--emit-component-assets <TAGS>` | none | Comma-separated root component tags emitted as static `.webui.js` ESM assets in `--out` |
+| `--emit-schema` | false | Emit `<protocol-stem>.state.schema.json` beside the protocol |
 | `--theme <PACKAGE>` | none | Design token theme to validate against (see below) |
 | `--asset-file-name-template <TEMPLATE>` | `[name].[ext]` | Emitted asset filename template for Link-mode CSS files and static component assets. Tokens: `[name]`, `[hash]`, `[ext]` |
 | `--css-public-base <BASE>` | none | Public URL/path prefix for Link-mode CSS hrefs |
@@ -673,6 +674,22 @@ webui inspect ./dist/protocol.bin
 webui inspect ./dist/protocol.bin | jq '.fragments | keys'
 ```
 
+### Generate render-state schema
+
+```bash
+webui schema ./dist/protocol.bin \
+  --entry index.html \
+  --title MyAppState > ./dist/state.schema.json
+```
+
+For non-routed entries this emits one object schema. Plain rendered bindings
+accept `string`, `number`, or `boolean`; loops and dotted paths infer arrays and
+objects. For routed entries, every complete route chain gets its own `$defs`
+schema, and `x-webui-routes` maps route patterns to those definitions. The
+schemas are build-time contracts; WebUI does not validate them during rendering.
+Use `webui build --emit-schema` to create the protocol and its paired schema in
+one build.
+
 ## Build Diagnostics & Error Output
 
 Authoring mistakes fail `webui build` with a structured, actionable diagnostic
diff --git a/docs/guide/cli/index.md b/docs/guide/cli/index.md
index 1e0b5f04..011b4d88 100644
--- a/docs/guide/cli/index.md
+++ b/docs/guide/cli/index.md
@@ -33,7 +33,7 @@ Use `--format json` in editors, CI, or AI/agent tooling that needs to parse buil
 Build a WebUI application from an app folder.
 
 ```bash
-webui build [APP] --out <OUT> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>] [--components <SOURCE>]... [--emit-component-assets <TAGS>] [--theme <VALUE>] [--asset-file-name-template <TEMPLATE>] [--css-public-base <BASE>] [--legal-comments <MODE>]
+webui build [APP] --out <OUT> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>] [--components <SOURCE>]... [--emit-component-assets <TAGS>] [--emit-schema] [--theme <VALUE>] [--asset-file-name-template <TEMPLATE>] [--css-public-base <BASE>] [--legal-comments <MODE>]
 ```
 
 **Arguments:**
@@ -48,6 +48,7 @@ webui build [APP] --out <OUT> [--entry <FILE>] [--css <MODE>] [--plugin <NAME>]
 | `--dom <STRATEGY>` | DOM strategy: `shadow` or `light` | `shadow` |
 | `--components <SOURCE>` | Additional component sources (npm packages or local paths). Repeatable. | *(none)* |
 | `--emit-component-assets <TAGS>` | Comma-separated root component tags to emit as static WebUI component assets in `--out` | *(none)* |
+| `--emit-schema` | Emit `<protocol-stem>.state.schema.json` beside the compiled protocol | off |
 | `--theme <VALUE>` | Design token theme to validate against: a JSON file path or npm package name. Missing required tokens fail the build. | *(none)* |
 | `--asset-file-name-template <TEMPLATE>` | Emitted asset filename template for Link-mode CSS files and static component assets. Tokens: `[name]`, `[hash]`, `[ext]` | `[name].[ext]` |
 | `--css-public-base <BASE>` | Optional public URL/path prefix for Link-mode CSS hrefs | *(none)* |
@@ -180,6 +181,9 @@ webui build ./my-app --out ./dist --components ./shared/components
 # Customize the protocol filename (useful when building multiple apps to one folder)
 webui build ./src/apps/app1 --out ./dist/app1.bin
 webui build ./src/apps/app2 --out ./dist/app2.bin
+
+# Emit a paired state schema without a second protocol read
+webui build ./src/apps/app1 --out ./dist/app1.bin --emit-schema
 ```
 
 ### `webui inspect`
@@ -209,6 +213,67 @@ webui inspect dist/protocol.bin | jq '.fragments["index.html"]'
 webui inspect dist/protocol.bin | jq '.fragments | keys | length'
 ```
 
+### `webui schema`
+
+Generate a JSON Schema draft 2020-12 document describing the render state used
+by a compiled protocol.
+
+```bash
+webui schema <FILE> [--entry <FILE>] [--title <TITLE>]
+```
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `FILE` | Path to a compiled `protocol.bin` file | *(required)* |
+| `--entry <FILE>` | Entry fragment to analyze | `index.html` |
+| `--title <TITLE>` | Schema title | `WebUIState` |
+
+The schema is written to stdout:
+
+```bash
+webui schema ./dist/protocol.bin \
+  --title ContactBookState > ./dist/state.schema.json
+```
+
+Plain rendered bindings and normal attributes accept JSON strings, numbers, or
+booleans. Complex `:property` bindings remain unconstrained until their child
+template usage provides stronger evidence. Structural usage narrows the schema:
+dotted paths create objects, `<for>` collections create arrays, raw bindings
+are strings, and typed comparisons infer their operand type. Condition-only
+paths remain optional because missing condition values evaluate false.
+Terminal `.length` access accepts strings, arrays, or objects with a `length`
+property, matching runtime state lookup.
+
+Component-local attributes are resolved back to the parent state paths that
+populate them. Static attributes do not become root state properties. The
+parser's internal `head_end`, `body_start`, and `body_end` signals are excluded.
+
+For an entry containing routes, each complete route chain gets an independent
+schema under `$defs`. `x-webui-routes` maps route patterns to those definitions:
+
+```json
+{
+  "$defs": {
+    "route": { "type": "object" },
+    "route.contacts.:id": { "type": "object" }
+  },
+  "x-webui-routes": {
+    "/": "#/$defs/route",
+    "/contacts/:id": "#/$defs/route.contacts.:id"
+  }
+}
+```
+
+The route metadata is intended for build-time tooling and future typed route
+APIs. Tooling should resolve definition references through `x-webui-routes`
+rather than constructing keys. WebUI does not perform runtime JSON Schema
+validation.
+
+Use `webui build --emit-schema` when building the protocol and schema together.
+For `--out ./dist/catalog.bin`, the paired schema is written to
+`./dist/catalog.state.schema.json`. The standalone `webui schema` command
+remains useful for existing protocol artifacts.
+
 ### `webui serve`
 
 Start a development server that builds, renders, and serves a WebUI application. Enable live reload with `--watch`.
diff --git a/docs/guide/concepts/state-management/index.md b/docs/guide/concepts/state-management/index.md
index fdd991e3..78b3be36 100644
--- a/docs/guide/concepts/state-management/index.md
+++ b/docs/guide/concepts/state-management/index.md
@@ -208,6 +208,32 @@ By default, signal values are HTML-escaped to prevent XSS:
 
 > ⚠️ Never use triple braces for user input or URL parameters. An attacker could inject `<script>` tags.
 
+## Generating a State Schema
+
+After building an application, generate a JSON Schema for its render state:
+
+```bash
+webui schema ./dist/protocol.bin \
+  --title MyAppState > ./dist/state.schema.json
+```
+
+When building both artifacts together:
+
+```bash
+webui build ./src --out ./dist/app.bin --emit-schema
+```
+
+This writes `app.bin` and `app.state.schema.json`.
+
+Plain bindings accept JSON strings, numbers, or booleans. Dotted paths and
+loops infer nested objects and arrays. Values used only by conditions are
+optional because missing condition state evaluates false.
+
+Routed applications produce one named schema per complete route chain. The
+`x-webui-routes` mapping connects each route pattern to its state definition,
+allowing build-time tools to generate route-specific types without adding
+runtime validation overhead.
+
 ## Learn More
 
 - [Signals](/guide/concepts/directives/signals) - Template binding syntax
diff --git a/examples/app/commerce/data/state.json b/examples/app/commerce/data/state.json
index a38de926..3e5bd856 100644
--- a/examples/app/commerce/data/state.json
+++ b/examples/app/commerce/data/state.json
@@ -1,6 +1,11 @@
 {
   "storeName": "WebUI Store",
+  "searchQuery": "",
   "cartItemCount": "0",
+  "cartHref": "/?cart=open",
+  "cartCloseHref": "/",
+  "cartOpen": "",
+  "currentPath": "/",
   "navCategories": [
     { "handle": "shirts", "title": "Shirts" },
     { "handle": "stickers", "title": "Stickers" },
@@ -14,7 +19,7 @@
   "featuredProducts": [],
   "carouselProducts": [],
   "cartEmpty": true,
-  "cartSubtotal": "$0.00",
-  "cartTaxes": "$0.00",
+  "subtotal": "$0.00",
+  "taxes": "$0.00",
   "cartItems": []
 }
diff --git a/examples/app/contact-book-manager/data/state.json b/examples/app/contact-book-manager/data/state.json
index aca9050e..35bcabc5 100644
--- a/examples/app/contact-book-manager/data/state.json
+++ b/examples/app/contact-book-manager/data/state.json
@@ -1,4 +1,5 @@
 {
+  "page": "dashboard",
   "searchQuery": "",
   "activeGroup": "all",
   "groups": ["Work", "Family", "Friends", "Other"],

From 320b9fb3fd02cf22cf34ce8b01b5b28d81b51382 Mon Sep 17 00:00:00 2001
From: Mark Polak <mapol@microsoft.com>
Date: Wed, 15 Jul 2026 19:03:46 +0200
Subject: [PATCH 2/4] Fix schema references and literal bindings

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fe040cbf-edcc-4e6f-b829-f85e08f2d044
---
 crates/webui-cli/src/commands/state_schema.rs |  11 +-
 .../src/commands/state_schema/inference.rs    |  31 ++---
 .../src/commands/state_schema/tests.rs        | 108 ++++++++++++++++++
 3 files changed, 128 insertions(+), 22 deletions(-)

diff --git a/crates/webui-cli/src/commands/state_schema.rs b/crates/webui-cli/src/commands/state_schema.rs
index 8f72eb2e..d4cf71ed 100644
--- a/crates/webui-cli/src/commands/state_schema.rs
+++ b/crates/webui-cli/src/commands/state_schema.rs
@@ -325,9 +325,16 @@ fn route_definition_key(path: &str) -> String {
 }
 
 fn definition_ref(key: &str) -> String {
-    let mut schema_ref = String::with_capacity("#/$defs/".len() + key.len());
+    let mut schema_ref = String::with_capacity("#/$defs/".len() + key.len() + 4);
     schema_ref.push_str("#/$defs/");
-    schema_ref.push_str(key);
+    for character in key.chars() {
+        match character {
+            '~' => schema_ref.push_str("~0"),
+            '/' => schema_ref.push_str("~1"),
+            '%' => schema_ref.push_str("%25"),
+            _ => schema_ref.push(character),
+        }
+    }
     schema_ref
 }
 
diff --git a/crates/webui-cli/src/commands/state_schema/inference.rs b/crates/webui-cli/src/commands/state_schema/inference.rs
index 072f28d8..e88badb0 100644
--- a/crates/webui-cli/src/commands/state_schema/inference.rs
+++ b/crates/webui-cli/src/commands/state_schema/inference.rs
@@ -320,7 +320,6 @@ fn add_condition_paths(root: &mut Node, scope: &Rc<Scope>, condition: &Condition
 
 fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_protocol::Predicate) {
     let operator = ComparisonOperator::try_from(predicate.operator).ok();
-    let left_literal = literal_kind(&predicate.left);
     let right_literal = literal_kind(&predicate.right);
 
     match operator {
@@ -328,15 +327,13 @@ fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_pro
         | Some(ComparisonOperator::LessThan)
         | Some(ComparisonOperator::GreaterThanOrEqual)
         | Some(ComparisonOperator::LessThanOrEqual) => {
-            if left_literal.is_none() {
-                add_path(
-                    root,
-                    scope,
-                    &predicate.left,
-                    InferredKind::Number,
-                    Requirement::Optional,
-                );
-            }
+            add_path(
+                root,
+                scope,
+                &predicate.left,
+                InferredKind::Number,
+                Requirement::Optional,
+            );
             if right_literal.is_none() {
                 add_path(
                     root,
@@ -347,14 +344,9 @@ fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_pro
                 );
             }
         }
-        _ => match (left_literal, right_literal) {
-            (None, Some(kind)) => {
-                add_path(root, scope, &predicate.left, kind, Requirement::Optional)
-            }
-            (Some(kind), None) => {
-                add_path(root, scope, &predicate.right, kind, Requirement::Optional)
-            }
-            (None, None) => {
+        _ => match right_literal {
+            Some(kind) => add_path(root, scope, &predicate.left, kind, Requirement::Optional),
+            None => {
                 add_path(
                     root,
                     scope,
@@ -370,7 +362,6 @@ fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_pro
                     Requirement::Optional,
                 );
             }
-            (Some(_), Some(_)) => {}
         },
     }
 }
@@ -397,7 +388,7 @@ fn add_path(
     kind: InferredKind,
     requirement: Requirement,
 ) {
-    if path.is_empty() || literal_kind(path).is_some() {
+    if path.is_empty() {
         return;
     }
     if let BindingOrigin::RootPath {
diff --git a/crates/webui-cli/src/commands/state_schema/tests.rs b/crates/webui-cli/src/commands/state_schema/tests.rs
index 6abf2573..e3d90d8b 100644
--- a/crates/webui-cli/src/commands/state_schema/tests.rs
+++ b/crates/webui-cli/src/commands/state_schema/tests.rs
@@ -93,6 +93,33 @@ fn route_definition_keys_are_injective_for_common_collisions() {
     );
 }
 
+#[test]
+fn encoded_route_references_resolve_to_definition_keys() {
+    let paths = ["/docs/v1.0", "/café", "/a b", "/100%"];
+    let routes = paths
+        .iter()
+        .enumerate()
+        .map(|(index, path)| WebUIFragmentRoute {
+            path: (*path).to_string(),
+            fragment_id: format!("page-{index}"),
+            exact: true,
+            ..WebUIFragmentRoute::default()
+        })
+        .collect();
+    let protocol = protocol_with_entry_routes(routes);
+    let schema = generate_schema(&protocol, "index.html", "EncodedRoutesState").unwrap();
+    let definitions = schema["$defs"].as_object().unwrap();
+
+    for path in paths {
+        let schema_ref = schema["x-webui-routes"][path].as_str().unwrap();
+        let key = decode_definition_ref(schema_ref);
+        assert!(
+            definitions.contains_key(&key),
+            "missing definition for {path}"
+        );
+    }
+}
+
 #[test]
 fn optional_child_replaces_parent_only_route_chain() {
     let route = WebUIFragmentRoute {
@@ -182,6 +209,56 @@ fn routes_inside_control_flow_fragments_are_discovered() {
     assert_eq!(paths, ["/conditional", "/repeated"]);
 }
 
+#[test]
+fn literal_looking_binding_names_remain_state_paths() {
+    let protocol = WebUIProtocol::new(std::collections::HashMap::from([
+        (
+            "index.html".to_string(),
+            webui_protocol::FragmentList {
+                fragments: vec![
+                    webui_protocol::WebUIFragment::signal("true", false),
+                    webui_protocol::WebUIFragment::signal("42", false),
+                    webui_protocol::WebUIFragment::if_cond(
+                        webui_protocol::ConditionExpr::predicate(
+                            "false",
+                            webui_protocol::ComparisonOperator::Equal,
+                            "true",
+                        ),
+                        "bool-condition",
+                    ),
+                    webui_protocol::WebUIFragment::if_cond(
+                        webui_protocol::ConditionExpr::predicate(
+                            "123",
+                            webui_protocol::ComparisonOperator::GreaterThan,
+                            "0",
+                        ),
+                        "number-condition",
+                    ),
+                ],
+            },
+        ),
+        (
+            "bool-condition".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+        (
+            "number-condition".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+    ]));
+
+    let schema = generate_schema(&protocol, "index.html", "LiteralKeysState").unwrap();
+    assert!(schema["properties"]["true"]["type"].is_array());
+    assert!(schema["properties"]["42"]["type"].is_array());
+    assert_eq!(schema["properties"]["false"]["type"], "boolean");
+    assert_eq!(schema["properties"]["123"]["type"], "number");
+    assert_eq!(schema["required"], serde_json::json!(["42", "true"]));
+}
+
 #[test]
 fn example_state_files_match_generated_schemas() {
     let workspace = workspace_root();
@@ -392,3 +469,34 @@ fn protocol_with_entry_routes(routes: Vec<WebUIFragmentRoute>) -> WebUIProtocol
     }
     WebUIProtocol::new(records)
 }
+
+fn decode_definition_ref(schema_ref: &str) -> String {
+    let token = schema_ref.strip_prefix("#/$defs/").unwrap();
+    let bytes = token.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+    while index < bytes.len() {
+        if bytes[index] == b'%' {
+            let high = hex_value(bytes[index + 1]);
+            let low = hex_value(bytes[index + 2]);
+            decoded.push((high << 4) | low);
+            index += 3;
+        } else {
+            decoded.push(bytes[index]);
+            index += 1;
+        }
+    }
+    String::from_utf8(decoded)
+        .unwrap()
+        .replace("~1", "/")
+        .replace("~0", "~")
+}
+
+fn hex_value(byte: u8) -> u8 {
+    match byte {
+        b'0'..=b'9' => byte - b'0',
+        b'a'..=b'f' => byte - b'a' + 10,
+        b'A'..=b'F' => byte - b'A' + 10,
+        _ => panic!("invalid hex digit in generated schema reference"),
+    }
+}

From 1b347c76723504d99840affaaa165e6ac5a40041 Mon Sep 17 00:00:00 2001
From: Mark Polak <mapol@microsoft.com>
Date: Wed, 22 Jul 2026 14:02:53 +0200
Subject: [PATCH 3/4] Refine schema types for code generation

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fe040cbf-edcc-4e6f-b829-f85e08f2d044
---
 DESIGN.md                                     |   7 +-
 crates/webui-cli/README.md                    |   2 +
 .../src/commands/state_schema/inference.rs    |  83 ++++-
 .../src/commands/state_schema/model.rs        | 106 +++++-
 ...sts__snapshots_component_scope_schema.snap |  28 +-
 ...s__snapshots_nested_collection_schema.snap |  17 +-
 ...s_declared_in_component_schema_bundle.snap |  40 ++-
 ...napshots_routes_example_schema_bundle.snap | 305 ++++++++++++++----
 .../src/commands/state_schema/tests.rs        |  45 +++
 docs/ai.md                                    |   4 +
 docs/guide/cli/index.md                       |   5 +
 docs/guide/concepts/state-management/index.md |   4 +
 12 files changed, 537 insertions(+), 109 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index 42fbddfe..91cb4183 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -1811,13 +1811,18 @@ uses the following rules:
 - Plain text and normal attribute values accept JSON scalars: `string`,
   `number`, or `boolean`. Complex `:property` bindings remain unconstrained
   until child-template usage provides stronger structural evidence.
+- Broad scalar and truthiness schemas can carry non-validating generation
+  metadata under `x-webui.preferredType`. Plain rendered values prefer
+  `string`; condition identifiers prefer `boolean`. Validators continue to use
+  the standard `type`/`anyOf` contract.
 - Raw signals are strings.
 - Dotted paths create nested objects.
 - A terminal `.length` accepts the runtime's three valid forms: a string, an
   array, or an object with a `length` property.
 - `<for>` collections create arrays; loop-item paths define the item schema.
 - Ordered predicates infer numbers. Equality predicates infer the type of a
-  literal operand.
+  literal operand; integer literals produce `integer`, and known types propagate
+  across path-to-path equality.
 - Condition-only paths are optional because a missing condition value evaluates
   false. A path referenced by rendered output or a collection remains required.
 - Normal component-attribute source paths are recorded as scalars, but
diff --git a/crates/webui-cli/README.md b/crates/webui-cli/README.md
index 081eed54..969bb0f2 100644
--- a/crates/webui-cli/README.md
+++ b/crates/webui-cli/README.md
@@ -97,6 +97,8 @@ webui schema ./dist/protocol.bin \
 Plain bindings accept string, number, or boolean values. Loops and dotted paths
 produce array and object schemas. Routed entries produce separate definitions
 for each route chain plus an `x-webui-routes` path-to-schema mapping.
+Broad values may include `x-webui.preferredType` as a non-validating hint for
+future host-language type generation.
 
 ## App Layout
 
diff --git a/crates/webui-cli/src/commands/state_schema/inference.rs b/crates/webui-cli/src/commands/state_schema/inference.rs
index e88badb0..0b39cf3e 100644
--- a/crates/webui-cli/src/commands/state_schema/inference.rs
+++ b/crates/webui-cli/src/commands/state_schema/inference.rs
@@ -11,7 +11,10 @@ use webui_protocol::{
     ComparisonOperator, ConditionExpr, WebUIFragment, WebUIFragmentAttribute, WebUIProtocol,
 };
 
-use super::model::{add_array_path, add_resolved_path, node_to_schema, InferredKind, Node};
+use super::model::{
+    add_array_path, add_resolved_path, node_to_schema, resolved_kind, InferredKind, Node,
+    PreferredKind,
+};
 use super::scope::{array_item_path, has_component_scope, resolve_path, BindingOrigin, Scope};
 
 struct WalkFrame<'a> {
@@ -46,6 +49,28 @@ enum Requirement {
     Required,
 }
 
+#[derive(Clone, Copy)]
+struct TypeEvidence {
+    kind: InferredKind,
+    preferred: Option<PreferredKind>,
+}
+
+impl TypeEvidence {
+    fn exact(kind: InferredKind) -> Self {
+        Self {
+            kind,
+            preferred: None,
+        }
+    }
+
+    fn preferred(kind: InferredKind, preferred: PreferredKind) -> Self {
+        Self {
+            kind,
+            preferred: Some(preferred),
+        }
+    }
+}
+
 pub(super) struct SchemaInference<'a> {
     protocol: &'a WebUIProtocol,
     root: Node,
@@ -155,9 +180,9 @@ impl<'a> SchemaInference<'a> {
                         &frame.scope,
                         &signal.value,
                         if signal.raw {
-                            InferredKind::String
+                            TypeEvidence::exact(InferredKind::String)
                         } else {
-                            InferredKind::Scalar
+                            TypeEvidence::preferred(InferredKind::Scalar, PreferredKind::String)
                         },
                         frame.binding_requirement,
                     );
@@ -244,9 +269,9 @@ impl<'a> SchemaInference<'a> {
                 &frame.scope,
                 &attribute.value,
                 if attribute.complex {
-                    InferredKind::Any
+                    TypeEvidence::exact(InferredKind::Any)
                 } else {
-                    InferredKind::Scalar
+                    TypeEvidence::preferred(InferredKind::Scalar, PreferredKind::String)
                 },
                 Requirement::Scoped,
             );
@@ -293,7 +318,7 @@ fn add_condition_paths(root: &mut Node, scope: &Rc<Scope>, condition: &Condition
                     root,
                     scope,
                     &identifier.value,
-                    InferredKind::Any,
+                    TypeEvidence::preferred(InferredKind::Any, PreferredKind::Boolean),
                     Requirement::Optional,
                 );
             }
@@ -331,7 +356,7 @@ fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_pro
                 root,
                 scope,
                 &predicate.left,
-                InferredKind::Number,
+                TypeEvidence::exact(InferredKind::Number),
                 Requirement::Optional,
             );
             if right_literal.is_none() {
@@ -339,26 +364,33 @@ fn add_predicate_paths(root: &mut Node, scope: &Rc<Scope>, predicate: &webui_pro
                     root,
                     scope,
                     &predicate.right,
-                    InferredKind::Number,
+                    TypeEvidence::exact(InferredKind::Number),
                     Requirement::Optional,
                 );
             }
         }
         _ => match right_literal {
-            Some(kind) => add_path(root, scope, &predicate.left, kind, Requirement::Optional),
+            Some(kind) => add_path(
+                root,
+                scope,
+                &predicate.left,
+                TypeEvidence::exact(kind),
+                Requirement::Optional,
+            ),
             None => {
+                let evidence = predicate_path_evidence(root, scope, predicate);
                 add_path(
                     root,
                     scope,
                     &predicate.left,
-                    InferredKind::Scalar,
+                    evidence,
                     Requirement::Optional,
                 );
                 add_path(
                     root,
                     scope,
                     &predicate.right,
-                    InferredKind::Scalar,
+                    evidence,
                     Requirement::Optional,
                 );
             }
@@ -370,6 +402,9 @@ fn literal_kind(value: &str) -> Option<InferredKind> {
     if value == "true" || value == "false" {
         return Some(InferredKind::Boolean);
     }
+    if value.parse::<i64>().is_ok() || value.parse::<u64>().is_ok() {
+        return Some(InferredKind::Integer);
+    }
     if value.parse::<f64>().is_ok() {
         return Some(InferredKind::Number);
     }
@@ -381,11 +416,33 @@ fn literal_kind(value: &str) -> Option<InferredKind> {
     None
 }
 
+fn predicate_path_evidence(
+    root: &Node,
+    scope: &Rc<Scope>,
+    predicate: &webui_protocol::Predicate,
+) -> TypeEvidence {
+    for path in [&predicate.left, &predicate.right] {
+        let BindingOrigin::RootPath { path, .. } = resolve_path(scope, path) else {
+            continue;
+        };
+        if let Some(
+            kind @ (InferredKind::String
+            | InferredKind::Boolean
+            | InferredKind::Integer
+            | InferredKind::Number),
+        ) = resolved_kind(root, &path)
+        {
+            return TypeEvidence::exact(kind);
+        }
+    }
+    TypeEvidence::preferred(InferredKind::Scalar, PreferredKind::String)
+}
+
 fn add_path(
     root: &mut Node,
     scope: &Rc<Scope>,
     path: &str,
-    kind: InferredKind,
+    evidence: TypeEvidence,
     requirement: Requirement,
 ) {
     if path.is_empty() {
@@ -401,7 +458,7 @@ fn add_path(
             Requirement::Scoped => scope_required,
             Requirement::Required => true,
         };
-        add_resolved_path(root, &resolved, kind, required);
+        add_resolved_path(root, &resolved, evidence.kind, evidence.preferred, required);
     }
 }
 
diff --git a/crates/webui-cli/src/commands/state_schema/model.rs b/crates/webui-cli/src/commands/state_schema/model.rs
index 19b06210..a74ea5fa 100644
--- a/crates/webui-cli/src/commands/state_schema/model.rs
+++ b/crates/webui-cli/src/commands/state_schema/model.rs
@@ -10,13 +10,21 @@ pub(super) enum InferredKind {
     Scalar,
     String,
     Boolean,
+    Integer,
     Number,
     Object,
 }
 
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(super) enum PreferredKind {
+    String,
+    Boolean,
+}
+
 #[derive(Default)]
 pub(super) struct Node {
     kind: Option<InferredKind>,
+    preferred: Option<PreferredKind>,
     required: bool,
     length_kind: Option<InferredKind>,
     length_required: bool,
@@ -39,7 +47,13 @@ impl Node {
     }
 }
 
-pub(super) fn add_resolved_path(root: &mut Node, path: &str, kind: InferredKind, required: bool) {
+pub(super) fn add_resolved_path(
+    root: &mut Node,
+    path: &str,
+    kind: InferredKind,
+    preferred: Option<PreferredKind>,
+    required: bool,
+) {
     let mut parts = path.split('.').filter(|part| !part.is_empty()).peekable();
     let mut current = root;
     let mut saw_part = false;
@@ -54,6 +68,7 @@ pub(super) fn add_resolved_path(root: &mut Node, path: &str, kind: InferredKind,
     }
     if saw_part {
         current.kind = Some(merge_kind(current.kind, kind));
+        current.preferred = merge_preferred(current.preferred, preferred);
     }
 }
 
@@ -71,6 +86,22 @@ pub(super) fn add_array_path(root: &mut Node, path: &str, required: bool) {
     }
 }
 
+pub(super) fn resolved_kind(root: &Node, path: &str) -> Option<InferredKind> {
+    let mut current = root;
+    let mut parts = path.split('.').filter(|part| !part.is_empty()).peekable();
+    while let Some(part) = parts.next() {
+        if part == "length" && parts.peek().is_none() {
+            return current.length_kind;
+        }
+        let (name, array_depth) = split_array_suffix(part);
+        current = current.children.get(name)?;
+        for _ in 0..array_depth {
+            current = current.array_item.as_deref()?;
+        }
+    }
+    current.kind
+}
+
 pub(super) fn node_to_schema(root: &Node) -> Value {
     let mut tasks = vec![SchemaTask::Visit(root)];
     let mut values = Vec::new();
@@ -88,7 +119,10 @@ pub(super) fn node_to_schema(root: &Node) -> Value {
                 } else if let Some(kind) = node.length_kind {
                     values.push(length_parent_schema(kind, node.length_required, node.kind));
                 } else {
-                    values.push(leaf_schema(node.kind.unwrap_or(InferredKind::Any)));
+                    values.push(leaf_schema(
+                        node.kind.unwrap_or(InferredKind::Any),
+                        node.preferred,
+                    ));
                 }
             }
             SchemaTask::FinishArray => {
@@ -117,7 +151,7 @@ pub(super) fn node_to_schema(root: &Node) -> Value {
                 }
                 if let Some(kind) = node.length_kind {
                     if !properties.contains_key("length") {
-                        properties.insert("length".to_string(), leaf_schema(kind));
+                        properties.insert("length".to_string(), leaf_schema(kind, None));
                         if node.length_required {
                             required.push(Value::String("length".to_string()));
                         }
@@ -151,24 +185,26 @@ fn descend_node<'a>(current: &'a mut Node, part: &str, required: bool) -> &'a mu
         return item;
     }
 
-    fn split_array_suffix(mut part: &str) -> (&str, usize) {
-        let mut depth = 0;
-        while let Some(base) = part.strip_suffix("[]") {
-            part = base;
-            depth += 1;
-        }
-        (part, depth)
-    }
-
     current.kind.get_or_insert(InferredKind::Object);
     let child = current.children.entry(part.to_string()).or_default();
     child.required |= required;
     child
 }
 
+fn split_array_suffix(mut part: &str) -> (&str, usize) {
+    let mut depth = 0;
+    while let Some(base) = part.strip_suffix("[]") {
+        part = base;
+        depth += 1;
+    }
+    (part, depth)
+}
+
 fn merge_kind(existing: Option<InferredKind>, incoming: InferredKind) -> InferredKind {
     match (existing, incoming) {
         (Some(InferredKind::Object), _) | (_, InferredKind::Object) => InferredKind::Object,
+        (Some(InferredKind::Number), InferredKind::Integer)
+        | (Some(InferredKind::Integer), InferredKind::Number) => InferredKind::Number,
         (Some(InferredKind::Any), specific) => specific,
         (Some(specific), InferredKind::Any) => specific,
         (Some(InferredKind::Scalar), specific) => specific,
@@ -179,14 +215,31 @@ fn merge_kind(existing: Option<InferredKind>, incoming: InferredKind) -> Inferre
     }
 }
 
-fn leaf_schema(kind: InferredKind) -> Value {
-    match kind {
+fn merge_preferred(
+    existing: Option<PreferredKind>,
+    incoming: Option<PreferredKind>,
+) -> Option<PreferredKind> {
+    match (existing, incoming) {
+        (Some(existing), Some(incoming)) if existing == incoming => Some(existing),
+        (None, preferred) | (preferred, None) => preferred,
+        (Some(_), Some(_)) => None,
+    }
+}
+
+fn leaf_schema(kind: InferredKind, preferred: Option<PreferredKind>) -> Value {
+    let schema = match kind {
         InferredKind::Scalar => scalar_schema(),
         InferredKind::Any => any_schema(),
         InferredKind::String => type_schema("string"),
         InferredKind::Boolean => type_schema("boolean"),
+        InferredKind::Integer => type_schema("integer"),
         InferredKind::Number => type_schema("number"),
         InferredKind::Object => object_schema(Map::new()),
+    };
+    if matches!(kind, InferredKind::Scalar | InferredKind::Any) {
+        with_preferred_type(schema, preferred)
+    } else {
+        schema
     }
 }
 
@@ -201,7 +254,9 @@ fn length_parent_schema(
 ) -> Value {
     match parent_kind {
         Some(InferredKind::Scalar | InferredKind::String) => return type_schema("string"),
-        Some(InferredKind::Number | InferredKind::Boolean) => return Value::Bool(false),
+        Some(InferredKind::Integer | InferredKind::Number | InferredKind::Boolean) => {
+            return Value::Bool(false);
+        }
         Some(InferredKind::Object) => return object_schema(Map::new()),
         Some(InferredKind::Any) | None => {}
     }
@@ -211,7 +266,7 @@ fn length_parent_schema(
     array_schema.insert("type".to_string(), Value::String("array".to_string()));
 
     let mut object_properties = Map::new();
-    object_properties.insert("length".to_string(), leaf_schema(kind));
+    object_properties.insert("length".to_string(), leaf_schema(kind, None));
     let mut object_schema = Map::new();
     object_schema.insert("properties".to_string(), Value::Object(object_properties));
     object_schema.insert(
@@ -262,3 +317,22 @@ fn object_schema(properties: Map<String, Value>) -> Value {
     schema.insert("type".to_string(), Value::String("object".to_string()));
     Value::Object(schema)
 }
+
+fn with_preferred_type(mut schema: Value, preferred: Option<PreferredKind>) -> Value {
+    let Some(preferred) = preferred else {
+        return schema;
+    };
+    let preferred = match preferred {
+        PreferredKind::String => "string",
+        PreferredKind::Boolean => "boolean",
+    };
+    if let Some(object) = schema.as_object_mut() {
+        let mut webui = Map::new();
+        webui.insert(
+            "preferredType".to_string(),
+            Value::String(preferred.to_string()),
+        );
+        object.insert("x-webui".to_string(), Value::Object(webui));
+    }
+    schema
+}
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
index 03aba1f2..dcb30831 100644
--- a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_component_scope_schema.snap
@@ -1,6 +1,6 @@
 ---
 source: crates/webui-cli/src/commands/state_schema/tests.rs
-expression: schema
+expression: "SchemaDocument::new(&schema)"
 ---
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -13,14 +13,20 @@ expression: schema
         "string",
         "number",
         "boolean"
-      ]
+      ],
+      "x-webui": {
+        "preferredType": "string"
+      }
     },
     "pageTitle": {
       "type": [
         "string",
         "number",
         "boolean"
-      ]
+      ],
+      "x-webui": {
+        "preferredType": "string"
+      }
     },
     "payload": {},
     "remainingCount": {
@@ -28,20 +34,30 @@ expression: schema
         "string",
         "number",
         "boolean"
-      ]
+      ],
+      "x-webui": {
+        "preferredType": "string"
+      }
     },
     "trustedHtml": {
       "type": "string"
     },
     "user": {
       "properties": {
-        "active": {},
+        "active": {
+          "x-webui": {
+            "preferredType": "boolean"
+          }
+        },
         "name": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         }
       },
       "required": [
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
index b99329c1..f894274d 100644
--- a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_nested_collection_schema.snap
@@ -1,6 +1,6 @@
 ---
 source: crates/webui-cli/src/commands/state_schema/tests.rs
-expression: schema
+expression: "SchemaDocument::new(&schema)"
 ---
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
@@ -45,7 +45,10 @@ expression: schema
                     "string",
                     "number",
                     "boolean"
-                  ]
+                  ],
+                  "x-webui": {
+                    "preferredType": "string"
+                  }
                 }
               },
               "required": [
@@ -61,7 +64,10 @@ expression: schema
               "string",
               "number",
               "boolean"
-            ]
+            ],
+            "x-webui": {
+              "preferredType": "string"
+            }
           }
         },
         "required": [
@@ -82,7 +88,10 @@ expression: schema
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "type": "array"
       },
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
index 8bc24f23..2db14f15 100644
--- a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_declared_in_component_schema_bundle.snap
@@ -12,14 +12,20 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "shellTitle": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         }
       },
       "required": [
@@ -36,21 +42,30 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "homeTitle": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "shellTitle": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         }
       },
       "required": [
@@ -68,21 +83,30 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "settingsTitle": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "shellTitle": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         }
       },
       "required": [
diff --git a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
index 22fb73ee..b5cf5b93 100644
--- a/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
+++ b/crates/webui-cli/src/commands/state_schema/snapshots/webui__commands__state_schema__tests__snapshots_routes_example_schema_bundle.snap
@@ -12,28 +12,40 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "basePath": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "language": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sections": {
           "items": {
@@ -43,21 +55,30 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "id": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -74,14 +95,20 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "title": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         }
       },
       "required": [
@@ -102,42 +129,60 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "basePath": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "language": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionIcon": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sections": {
           "items": {
@@ -147,21 +192,30 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "id": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -178,21 +232,30 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "title": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topicId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topics": {
           "items": {
@@ -202,14 +265,20 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -243,28 +312,40 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "basePath": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "language": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessonId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessons": {
           "items": {
@@ -274,14 +355,20 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -297,21 +384,30 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sections": {
           "items": {
@@ -321,21 +417,30 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "id": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -352,28 +457,40 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "title": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topicId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topicName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topics": {
           "items": {
@@ -383,14 +500,20 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -427,42 +550,60 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "basePath": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "language": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessonContent": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessonId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessonName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "lessons": {
           "items": {
@@ -472,14 +613,20 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -495,21 +642,30 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sectionName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "sections": {
           "items": {
@@ -519,21 +675,30 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "id": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
@@ -550,28 +715,40 @@ expression: "SchemaDocument::new(&schema)"
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "title": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topicId": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topicName": {
           "type": [
             "string",
             "number",
             "boolean"
-          ]
+          ],
+          "x-webui": {
+            "preferredType": "string"
+          }
         },
         "topics": {
           "items": {
@@ -581,14 +758,20 @@ expression: "SchemaDocument::new(&schema)"
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               },
               "name": {
                 "type": [
                   "string",
                   "number",
                   "boolean"
-                ]
+                ],
+                "x-webui": {
+                  "preferredType": "string"
+                }
               }
             },
             "required": [
diff --git a/crates/webui-cli/src/commands/state_schema/tests.rs b/crates/webui-cli/src/commands/state_schema/tests.rs
index e3d90d8b..cad6ce74 100644
--- a/crates/webui-cli/src/commands/state_schema/tests.rs
+++ b/crates/webui-cli/src/commands/state_schema/tests.rs
@@ -259,6 +259,51 @@ fn literal_looking_binding_names_remain_state_paths() {
     assert_eq!(schema["required"], serde_json::json!(["42", "true"]));
 }
 
+#[test]
+fn integer_literal_type_propagates_across_path_equality() {
+    let protocol = WebUIProtocol::new(std::collections::HashMap::from([
+        (
+            "index.html".to_string(),
+            webui_protocol::FragmentList {
+                fragments: vec![
+                    webui_protocol::WebUIFragment::if_cond(
+                        webui_protocol::ConditionExpr::predicate(
+                            "currentDisplay",
+                            webui_protocol::ComparisonOperator::Equal,
+                            "1",
+                        ),
+                        "first-condition",
+                    ),
+                    webui_protocol::WebUIFragment::if_cond(
+                        webui_protocol::ConditionExpr::predicate(
+                            "currentDisplay",
+                            webui_protocol::ComparisonOperator::Equal,
+                            "totalApps",
+                        ),
+                        "second-condition",
+                    ),
+                ],
+            },
+        ),
+        (
+            "first-condition".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+        (
+            "second-condition".to_string(),
+            webui_protocol::FragmentList {
+                fragments: Vec::new(),
+            },
+        ),
+    ]));
+
+    let schema = generate_schema(&protocol, "index.html", "CounterState").unwrap();
+    assert_eq!(schema["properties"]["currentDisplay"]["type"], "integer");
+    assert_eq!(schema["properties"]["totalApps"]["type"], "integer");
+}
+
 #[test]
 fn example_state_files_match_generated_schemas() {
     let workspace = workspace_root();
diff --git a/docs/ai.md b/docs/ai.md
index 6847d447..fd19d13c 100644
--- a/docs/ai.md
+++ b/docs/ai.md
@@ -690,6 +690,10 @@ schemas are build-time contracts; WebUI does not validate them during rendering.
 Use `webui build --emit-schema` to create the protocol and its paired schema in
 one build.
 
+Broad scalar and condition schemas may include a non-validating
+`x-webui.preferredType` hint. Integer literals infer `integer`, and known types
+propagate across path-to-path equality.
+
 ## Build Diagnostics & Error Output
 
 Authoring mistakes fail `webui build` with a structured, actionable diagnostic
diff --git a/docs/guide/cli/index.md b/docs/guide/cli/index.md
index 011b4d88..ae76592e 100644
--- a/docs/guide/cli/index.md
+++ b/docs/guide/cli/index.md
@@ -244,6 +244,11 @@ paths remain optional because missing condition values evaluate false.
 Terminal `.length` access accepts strings, arrays, or objects with a `length`
 property, matching runtime state lookup.
 
+Broad scalar and condition schemas may include a non-validating
+`x-webui.preferredType` hint. Plain rendered values prefer `string`, conditions
+prefer `boolean`, and integer literals produce the standard JSON Schema
+`integer` type. Known types propagate across path-to-path equality.
+
 Component-local attributes are resolved back to the parent state paths that
 populate them. Static attributes do not become root state properties. The
 parser's internal `head_end`, `body_start`, and `body_end` signals are excluded.
diff --git a/docs/guide/concepts/state-management/index.md b/docs/guide/concepts/state-management/index.md
index 78b3be36..7be4ab0f 100644
--- a/docs/guide/concepts/state-management/index.md
+++ b/docs/guide/concepts/state-management/index.md
@@ -229,6 +229,10 @@ Plain bindings accept JSON strings, numbers, or booleans. Dotted paths and
 loops infer nested objects and arrays. Values used only by conditions are
 optional because missing condition state evaluates false.
 
+Broad values may include `x-webui.preferredType` as a non-validating hint for
+host-language type generation. Integer literals infer `integer`, and known
+types propagate across path-to-path equality.
+
 Routed applications produce one named schema per complete route chain. The
 `x-webui-routes` mapping connects each route pattern to its state definition,
 allowing build-time tools to generate route-specific types without adding

From 4b636fdea05282e7ee2fc90b8028f005bc055c2a Mon Sep 17 00:00:00 2001
From: Mark Polak <mapol@microsoft.com>
Date: Wed, 22 Jul 2026 15:23:34 +0200
Subject: [PATCH 4/4] Fix schema build test after main merge

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: fe040cbf-edcc-4e6f-b829-f85e08f2d044
---
 crates/webui-cli/src/commands/build.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/webui-cli/src/commands/build.rs b/crates/webui-cli/src/commands/build.rs
index d0a9ac5e..f9d56c44 100644
--- a/crates/webui-cli/src/commands/build.rs
+++ b/crates/webui-cli/src/commands/build.rs
@@ -1011,6 +1011,7 @@ mod tests {
                 dom: DomStrategy::Shadow,
                 plugin: None,
                 components: Vec::new(),
+                projection_manifests: Vec::new(),
                 asset_file_name_template: DEFAULT_ASSET_FILE_NAME_TEMPLATE.to_string(),
                 css_public_base: None,
                 legal_comments: LegalComments::Inline,