@@ -62,6 +62,11 @@ jobs:
               exit 1
             fi
           done
+      - name: Verify executable application recipes
+        if: ${{ matrix.run_on == 'macos-latest' }}
+        run: |
+          python3 script/check-ai docs
+          python3 script/check-ai rust
       - name: Lint
         if: ${{ matrix.run_on == 'macos-latest' }}
         run: |
@@ -142,6 +147,10 @@ jobs:
           key: component-shell-cargo-x86_64-linux-gnu-${{ hashFiles('**/Cargo.lock') }}
       - name: Test component bindings
         run: cargo test -p gpui-component-shell --all-targets
+      - name: Verify generated TypeScript contracts
+        run: |
+          npm --prefix crates/component-shell/tests/types ci
+          npm --prefix crates/component-shell/tests/types test
       - name: Lint component bindings
         run: cargo clippy -p gpui-component-shell --all-targets -- -D warnings
       # The inventory test proves every public component is registered or
 
@@ -20,12 +20,14 @@ Documentation: <https://gpui-kit.com>
 ```text
 gpui-kit             The one crate applications depend on
 ├── gpui-base        Unstyled behavior, state, and infrastructure
-├── gpui-shell       JavaScript extensions for a Rust host
 └── gpui-component   GPUI Component: the complete styled UI system
 ```
 
-`gpui-kit` pins the matching GPUI release and re-exports every layer, so an
-application lists a single dependency and never GPUI itself.
+`gpui-kit` pins the matching GPUI release and re-exports GPUI, base, component,
+and assets, so a Rust application lists a single dependency. JavaScript extension
+hosts add `gpui-shell` separately; `gpui-component-shell` supplies the styled catalog.
+
+See the [executable application recipe and AI-assisted development acceptance checks](examples/ai_recipes/README.md) for a tested starting point and verification commands.
 
 ## Features
 
 
@@ -15,11 +15,10 @@ GPUI Kit 是一个综合性的 Rust 桌面应用开发框架。它将生产级 U
 ```text
 gpui-kit             应用唯一需要依赖的 crate
 ├── gpui-base        无样式的行为、状态与基础设施
-├── gpui-shell       为 Rust 宿主提供 JavaScript 扩展能力
 └── gpui-component   GPUI Component：完整的带样式 UI 系统
 ```
 
-`gpui-kit` 会固定配套的 GPUI 版本并重新导出全部三层，应用只需声明这一个依赖，无需接触 GPUI 本身。
+`gpui-kit` 会固定配套的 GPUI 版本并导出 GPUI、base、component 和 assets，Rust 应用只需声明这一个依赖。JavaScript 扩展宿主另行依赖 `gpui-shell`；`gpui-component-shell` 提供带样式的组件目录。
 
 ## 特性
 
 
@@ -0,0 +1,218 @@
+use std::{
+    fs,
+    path::PathBuf,
+    process::{Child, Command, ExitStatus, Stdio},
+    sync::atomic::{AtomicU64, Ordering},
+    thread,
+    time::{Duration, Instant},
+};
+
+use gpui::AppContext as _;
+
+static NEXT_APP: AtomicU64 = AtomicU64::new(0);
+
+struct CheckApp(PathBuf);
+
+impl CheckApp {
+    fn new(source: &str) -> Self {
+        let path = std::env::temp_dir().join(format!(
+            "gpui-component-shell-check-{}-{}",
+            std::process::id(),
+            NEXT_APP.fetch_add(1, Ordering::Relaxed)
+        ));
+        fs::create_dir(&path).unwrap();
+        fs::write(path.join("main.js"), source).unwrap();
+        Self(path)
+    }
+
+    fn run(&self) -> (ExitStatus, String, String) {
+        let stdout = self.0.join("stdout");
+        let stderr = self.0.join("stderr");
+        let mut child = CheckChild(
+            Command::new(env!("CARGO_BIN_EXE_gpui-component-shell"))
+                .env("XDG_DATA_HOME", self.0.join("data"))
+                .arg("check")
+                .arg(&self.0)
+                .arg("--print-spec")
+                .stdout(Stdio::from(fs::File::create(&stdout).unwrap()))
+                .stderr(Stdio::from(fs::File::create(&stderr).unwrap()))
+                .spawn()
+                .unwrap(),
+        );
+        let deadline = Instant::now() + Duration::from_secs(30);
+        let status = loop {
+            if let Some(status) = child.0.try_wait().unwrap() {
+                break status;
+            }
+            assert!(
+                Instant::now() < deadline,
+                "check did not exit within 30 seconds: {}",
+                fs::read_to_string(&stderr).unwrap()
+            );
+            thread::sleep(Duration::from_millis(20));
+        };
+        (
+            status,
+            fs::read_to_string(stdout).unwrap(),
+            fs::read_to_string(stderr).unwrap(),
+        )
+    }
+}
+
+impl Drop for CheckApp {
+    fn drop(&mut self) {
+        fs::remove_dir_all(&self.0).unwrap();
+    }
+}
+
+struct CheckChild(Child);
+
+impl Drop for CheckChild {
+    fn drop(&mut self) {
+        let _ = self.0.kill();
+        let _ = self.0.wait();
+    }
+}
+
+#[test]
+fn check_materializes_valid_typed_children_and_preserves_print_spec() {
+    let app = CheckApp::new(
+        r#"
+        import { View, div } from "gpui-kit";
+        import { HForm, Field } from "gpui-component";
+        export default class App extends View {
+            render() {
+                return new HForm().child(new Field().label("Name").child(div().child("Ada")));
+            }
+        }
+        "#,
+    );
+    let (status, stdout, stderr) = app.run();
+    assert!(status.success(), "{stdout}\n{stderr}");
+    assert!(
+        stdout.contains("Field") && stdout.contains("Ada"),
+        "{stdout}"
+    );
+    assert!(stdout.contains("check passed:"), "{stdout}");
+}
+
+#[test]
+fn check_rejects_an_ordinary_child_in_a_typed_form() {
+    let app = CheckApp::new(
+        r#"
+        import { View, div } from "gpui-kit";
+        import { HForm } from "gpui-component";
+        export default class App extends View {
+            render() { return div().child(new HForm().child(div())); }
+        }
+        "#,
+    );
+    let (status, stdout, stderr) = app.run();
+    assert_eq!(status.code(), Some(1), "{stdout}\n{stderr}");
+    assert!(stderr.contains("failed to materialize `Form`"), "{stderr}");
+    assert!(
+        stderr.contains("Field children; received an ordinary element"),
+        "{stderr}"
+    );
+    assert!(!stdout.contains("check passed:"), "{stdout}");
+}
+
+#[test]
+fn check_rejects_style_on_a_data_only_component() {
+    let app = CheckApp::new(
+        r#"
+        import { View, div } from "gpui-kit";
+        import { MenuItem } from "gpui-component";
+        export default class App extends View {
+            render() { return div().child(new MenuItem("Open", "open").p(2)); }
+        }
+        "#,
+    );
+    let (status, stdout, stderr) = app.run();
+    assert_eq!(status.code(), Some(1), "{stdout}\n{stderr}");
+    assert!(
+        stderr.contains("failed to materialize `MenuItem`"),
+        "{stderr}"
+    );
+    assert!(stderr.contains("does not implement Styled"), "{stderr}");
+    assert!(!stdout.contains("check passed:"), "{stdout}");
+}
+
+#[test]
+fn check_reports_load_and_render_failures_without_hanging() {
+    for (source, expected) in [
+        ("this is not javascript", "main.js"),
+        (
+            r#"import { View } from "gpui-kit";
+            export default class App extends View {
+                render() { throw new Error("render failed deliberately"); }
+            }"#,
+            "render failed deliberately",
+        ),
+        (
+            r#"import { View } from "gpui-kit";
+            export default class App extends View {
+                render() { while (true) {} }
+            }"#,
+            "interrupted",
+        ),
+    ] {
+        let (status, stdout, stderr) = CheckApp::new(source).run();
+        assert_eq!(status.code(), Some(1), "{stdout}\n{stderr}");
+        assert!(stderr.contains(expected), "{stderr}");
+        assert!(!stdout.contains("check passed:"), "{stdout}");
+    }
+}
+
+#[test]
+fn check_reports_invalid_metadata_before_opening_a_window() {
+    let app = CheckApp::new("export default 1;");
+    fs::write(app.0.join("gpui-shell.json"), "{}").unwrap();
+    let (status, stdout, stderr) = app.run();
+    assert_eq!(status.code(), Some(1), "{stdout}\n{stderr}");
+    assert!(stderr.contains("gpui-shell.json"), "{stderr}");
+    assert!(stderr.contains("check failed:"), "{stderr}");
+    assert!(!stdout.contains("check passed:"), "{stdout}");
+}
+
+#[gpui::test]
+fn runtime_check_preserves_errors_and_clears_them_before_the_next_check(
+    cx: &mut gpui::TestAppContext,
+) {
+    use std::ops::Deref as _;
+
+    cx.update(gpui_component_shell::init);
+    let runtime = gpui_component_shell::new_isolated_runtime().unwrap();
+    let window = cx.add_window(|window, cx| {
+        let empty = cx.new(|_| gpui::Empty);
+        gpui_component::Root::new(empty, window, cx)
+    });
+    let mut context = gpui::VisualTestContext::from_window(*window.deref(), cx);
+    let invalid = CheckApp::new(
+        r#"import { View, div } from "gpui-kit";
+        import { HForm } from "gpui-component";
+        export default class App extends View {
+            render() { return new HForm().child(div()); }
+        }"#,
+    );
+    let error = context
+        .update(|window, cx| runtime.check(&invalid.0, window, cx))
+        .expect_err("the Rust facade must return materialization failures");
+    assert!(format!("{error:#}").contains("Form accepts only registered Field children"));
+
+    let valid = CheckApp::new(
+        r#"import { View } from "gpui-kit";
+        import { HForm, Field } from "gpui-component";
+        export default class App extends View {
+            render() {
+                if (this.rendered) throw new Error("check rendered twice");
+                this.rendered = true;
+                return new HForm().child(new Field().child("checked once"));
+            }
+        }"#,
+    );
+    let description = context
+        .update(|window, cx| runtime.check(&valid.0, window, cx))
+        .expect("the next check must not inherit the previous materialization error");
+    assert!(description.contains("checked once"), "{description}");
+}
@@ -0,0 +1,14 @@
+# Generated type contracts
+
+Run from the repository root:
+
+```sh
+npm --prefix crates/component-shell/tests/types ci
+npm --prefix crates/component-shell/tests/types test
+```
+
+The harness generates fresh declarations with the styled host, compiles the strict positive TypeScript fixture and executes its emitted JavaScript, checks a separate strict negative fixture, checks the shipped registered-component JavaScript gallery, and runs valid and invalid scripts through the actual CLI. Temporary declarations and applications are removed after each run. Set `GPUI_COMPONENT_SHELL_BIN` to use an already built host; otherwise the harness uses `cargo run --locked`.
+
+Fluent methods retain the receiver's component contract. For example, `new Spinner().p(4).size('small')` remains valid, while `.on_click(...)` remains unavailable after styling or conditional chaining. `Spinner.role(...)` and `Spinner.transition(...)` are also rejected, including after styling; these behaviors remain supported on native `div()` builders. There is no separate hand-maintained runtime copy of the positive fixture. Native factories return `NativeElement`; `Element` is the union of renderable native and registered builders. Use `NativeElement` when a helper specifically needs native signatures such as numeric size, and `Element` for general render results and children.
+
+Consumer checking uses `skipLibCheck`, matching the generated editor configuration. It does not validate all ambient runtime library declarations. `@ts-expect-error` fixtures fail if a forbidden call becomes accepted; they are not casts that suppress unrelated fixture failures.
@@ -0,0 +1,34 @@
+import { div, View, type Element, type NativeElement, type Context } from 'gpui-kit';
+import { Spinner, Separator, Skeleton, HForm, Field, type SpinnerElement } from 'gpui-component';
+import { TextView } from 'gpui-base';
+
+function padded(element: Element): Element {
+  return element.p(2).when(true, current => current.p(4));
+}
+
+export default class FluentContracts extends View {
+  render(_cx: Context): Element {
+    const spinner: SpinnerElement = new Spinner()
+      .size('medium').p(4).flex()
+      .hover(style => style.p(2))
+      .active(style => style.p(1))
+      .focus(style => style.p(2))
+      .bg('#fff')
+      .when(true, element => element.size('small').p(2))
+      .map(element => element.size('large')).size('small');
+    const element: Element = spinner;
+    const answer: number = new Spinner().map(current => {
+      current.size('small');
+      return 42;
+    });
+    if (answer !== 42) throw new Error('map must preserve its return value');
+    const native: NativeElement = div();
+    return native.p(2).size(240).role('status').transition('opacity', 120).children([
+      padded(element),
+      new Separator().p(2).label('Section'),
+      new Skeleton().flex().secondary(),
+      new HForm().child(new Field().label('Name').child('Ada')).children([]).columns(2),
+      TextView.markdown('text', '# Hello').p(2).selectable().flex().scrollable(),
+    ]);
+  }
+}
@@ -0,0 +1,6 @@
+{
+  "name": "gpui-component-shell-type-contracts",
+  "private": true,
+  "scripts": { "test": "node run.mjs" },
+  "devDependencies": { "typescript": "5.9.3" }
+}