From c65f40992d13e477dd6e640793f21acc5a442c85 Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Mon, 17 Aug 2026 09:58:35 -0500
Subject: [PATCH 1/6] feat(ts): support root markup component imports

- Discover and embed root markup component sources for desktop and mobile builds.
- Cover hot reload, automation, replay, path budgets, and empty source sets.
- Move Kanban composition into a real component file and update authoring docs.
---
 build.zig                                     |  38 +++++-
 build/app.zig                                 | 122 +++++++++++++++++-
 .../src/app/docs/building-components/page.mdx |  61 ++-------
 docs/src/app/docs/native-ui/page.mdx          |  12 +-
 docs/src/app/docs/typescript/page.mdx         |   2 +
 docs/src/app/docs/windows/page.mdx            |   2 +-
 examples/kanban/README.md                     |   2 +-
 examples/kanban/src/app.native                |  77 ++---------
 .../kanban/src/components/board-column.native |  26 ++++
 skill-data/native-ui/SKILL.md                 |   2 +-
 skill-data/ts-core/SKILL.md                   |   2 +-
 src/app_runner/ts_core_main.zig               |   3 +-
 src/app_runner/ts_core_mobile.zig             |   3 +-
 src/runtime/ui_app_tests.zig                  |  27 ++--
 tests/ts-core/components/actions.native       |  10 ++
 tests/ts-core/kanban_e2e_tests.zig            |  35 ++++-
 tests/ts-core/markup_e2e_tests.zig            |  12 +-
 tests/ts-core/markup_view.native              |  10 +-
 18 files changed, 282 insertions(+), 164 deletions(-)
 create mode 100644 examples/kanban/src/components/board-column.native
 create mode 100644 tests/ts-core/components/actions.native

diff --git a/build.zig b/build.zig
index fe06de11f..6b270b3db 100644
--- a/build.zig
+++ b/build.zig
@@ -97,6 +97,20 @@ test "service archive support matches ScriptC localized object formats" {
     try std.testing.expect(app_build.serviceArchiveSupported(windows_host, native_windows_msvc));
 }
 
+test "root TypeScript markup discovery classification and resolver budgets" {
+    const app_build = @import("build/app.zig");
+    try std.testing.expect(app_build.isRootMarkupSourcePath("components/card.native"));
+    try std.testing.expect(app_build.isRootMarkupSourcePath("feature/nested/panel.native"));
+    try std.testing.expect(!app_build.isRootMarkupSourcePath("app.native"));
+    try std.testing.expect(!app_build.isRootMarkupSourcePath("windows/settings.native"));
+    try std.testing.expect(!app_build.isRootMarkupSourcePath("components/card.ts"));
+
+    try std.testing.expect(app_build.markupSourcePathWithinBudget("a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a"));
+    try std.testing.expect(!app_build.markupSourcePathWithinBudget("a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a"));
+    try std.testing.expect(app_build.markupSourcePathWithinBudget("a" ** 200));
+    try std.testing.expect(!app_build.markupSourcePathWithinBudget("a" ** 201));
+}
+
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const host_target = b.graph.host;
@@ -658,6 +672,9 @@ pub fn build(b: *std.Build) void {
         const ai_chat_e2e_run = b.addRunArtifact(ts_core_artifacts.ai_chat);
         const feed_reader_e2e_run = b.addRunArtifact(ts_core_artifacts.feed_reader);
         const services_e2e_run = b.addRunArtifact(ts_core_artifacts.services);
+        const markup_components_e2e_step = b.step("test-ts-markup-components-e2e", "Run root component-file compiled, interpreter, automation, and replay coverage");
+        markup_components_e2e_step.dependOn(&markup_e2e_run.step);
+        markup_components_e2e_step.dependOn(&kanban_e2e_run.step);
         ts_services_e2e_step.dependOn(&feed_reader_e2e_run.step);
         ts_services_e2e_step.dependOn(&services_e2e_run.step);
         // The same fixture through the in-process carrier (ServicePool over
@@ -2348,12 +2365,12 @@ pub fn build(b: *std.Build) void {
         \\provenance="$("$cli" automate provenance kanban-canvas "$button_id" 2>/dev/null)"
         \\case "$provenance" in *"authored=markup"*"root=src/app.native"*) ;; *) echo "writeback smoke: button provenance was not markup-authored: $provenance" >&2; exit 1 ;; esac
         \\case "$provenance" in *"node file=src/app.native"*) ;; *) echo "writeback smoke: button provenance named the wrong file: $provenance" >&2; exit 1 ;; esac
-        \\# 2. Loop provenance: the boot view is deliberately self-contained,
-        \\# so a card title reports its node in app.native plus its iteration key.
+        \\# 2. Imported-loop provenance: a card title reports its authored
+        \\# component file plus its iteration key.
         \\card_id="$(printf '%s\n' "$snapshot" | sed -n 's/.*widget @w1\/kanban-canvas#\([0-9][0-9]*\) role=text name="Retry failed agent runs".*/\1/p' | head -n 1)"
         \\case "$card_id" in ''|*[!0-9]*) echo "writeback smoke: card text id was missing from the snapshot" >&2; exit 1 ;; esac
         \\card_provenance="$("$cli" automate provenance kanban-canvas "$card_id" 2>/dev/null)"
-        \\case "$card_provenance" in *"node file=src/app.native"*) ;; *) echo "writeback smoke: card provenance named the wrong file: $card_provenance" >&2; exit 1 ;; esac
+        \\case "$card_provenance" in *"node file=src/components/board-column.native"*) ;; *) echo "writeback smoke: card provenance named the wrong file: $card_provenance" >&2; exit 1 ;; esac
         \\case "$card_provenance" in *"keys="*) ;; *) echo "writeback smoke: card provenance missed the iteration key: $card_provenance" >&2; exit 1 ;; esac
         \\# 3. Write-back: flip the Todo heading through the verb; the app's own
         \\# hot-reload watch picks the file change up and repaints.
@@ -3308,9 +3325,17 @@ fn tsCoreE2eArtifact(
     e2e_mod.addImport("native_sdk", desktop_mod);
     e2e_mod.addImport("ts_core_fixture", fixture_mod);
 
-    // The markup battery: the .native view + automation + record/replay
-    // guarantees over the markup fixture's compiled core.
-    const markup_e2e_mod = module(b, target, optimize, "tests/ts-core/markup_e2e_tests.zig");
+    // The markup battery: the imported .native view + automation +
+    // record/replay guarantees over the markup fixture's compiled core.
+    const markup_view_stage = b.addWriteFiles();
+    const markup_view_root = markup_view_stage.addCopyFile(b.path("tests/ts-core/markup_e2e_tests.zig"), "markup_e2e_tests.zig");
+    _ = markup_view_stage.addCopyFile(b.path("tests/ts-core/markup_view.native"), "markup_view.native");
+    _ = markup_view_stage.addCopyFile(b.path("tests/ts-core/components/actions.native"), "components/actions.native");
+    const markup_e2e_mod = b.createModule(.{
+        .root_source_file = markup_view_root,
+        .target = target,
+        .optimize = optimize,
+    });
     markup_e2e_mod.addImport("native_sdk", desktop_mod);
     markup_e2e_mod.addImport("ts_markup_fixture", markup_fixture_mod);
 
@@ -3326,6 +3351,7 @@ fn tsCoreE2eArtifact(
     const kanban_stage = b.addWriteFiles();
     const kanban_root = kanban_stage.addCopyFile(b.path("tests/ts-core/kanban_e2e_tests.zig"), "kanban_e2e_tests.zig");
     _ = kanban_stage.addCopyFile(b.path("examples/kanban/src/app.native"), "app.native");
+    _ = kanban_stage.addCopyFile(b.path("examples/kanban/src/components/board-column.native"), "components/board-column.native");
     const kanban_mod = b.createModule(.{
         .root_source_file = kanban_root,
         .target = target,
diff --git a/build/app.zig b/build/app.zig
index 03678f94c..396de2ed7 100644
--- a/build/app.zig
+++ b/build/app.zig
@@ -81,7 +81,7 @@ const TsWindowView = struct {
     staged_path: []const u8,
 };
 
-const TsWindowSource = struct {
+const TsMarkupSource = struct {
     set_path: []const u8,
     source_path: []const u8,
     staged_path: []const u8,
@@ -89,9 +89,45 @@ const TsWindowSource = struct {
 
 const TsWindowViews = struct {
     views: []const TsWindowView,
-    sources: []const TsWindowSource,
+    sources: []const TsMarkupSource,
 };
 
+const TsAppMarkupSources = struct {
+    /// Non-root, non-window files discovered under src/. Window files are
+    /// staged by the existing secondary-window registry and must not be
+    /// copied a second time.
+    files: []const TsMarkupSource,
+    /// The root view's embedded resolver set. Its path keys are relative to
+    /// src/, matching the root disk watcher; existing window sources are
+    /// projected under their staged `windows/...` names.
+    sources: []const TsMarkupSource,
+};
+
+const max_markup_source_path_len = 200;
+const max_markup_source_path_segments = 24;
+
+pub fn markupSourcePathWithinBudget(path: []const u8) bool {
+    var segments: usize = 0;
+    var it = std.mem.tokenizeScalar(u8, path, '/');
+    while (it.next() != null) segments += 1;
+    return path.len <= max_markup_source_path_len and segments <= max_markup_source_path_segments;
+}
+
+fn validateMarkupSourcePath(path: []const u8) void {
+    if (!markupSourcePathWithinBudget(path)) {
+        std.debug.panic(
+            "\nTypeScript markup source path `{s}` exceeds the import resolver budget: keep every src/-relative .native path at most {d} bytes and {d} segments\n",
+            .{ path, max_markup_source_path_len, max_markup_source_path_segments },
+        );
+    }
+}
+
+pub fn isRootMarkupSourcePath(path: []const u8) bool {
+    return std.mem.endsWith(u8, path, ".native") and
+        !std.mem.eql(u8, path, "app.native") and
+        !std.mem.startsWith(u8, path, "windows/");
+}
+
 /// Default TypeScript secondary-window views are statically discovered under
 /// `src/windows/`: `settings.native` serves descriptor label `settings`.
 /// Direct files form the generated launcher's closed, comptime-compiled view
@@ -104,7 +140,7 @@ fn collectTsWindowViews(b: *std.Build, app_root: []const u8) TsWindowViews {
     var walker = dir.walk(b.allocator) catch return .{ .views = &.{}, .sources = &.{} };
     defer walker.deinit();
     var views: std.ArrayList(TsWindowView) = .empty;
-    var sources: std.ArrayList(TsWindowSource) = .empty;
+    var sources: std.ArrayList(TsMarkupSource) = .empty;
     while (walker.next(b.graph.io) catch null) |entry| {
         if (entry.kind != .file or !std.mem.endsWith(u8, entry.path, ".native")) continue;
         const normalized_path = b.dupe(entry.path);
@@ -141,14 +177,85 @@ fn collectTsWindowViews(b: *std.Build, app_root: []const u8) TsWindowViews {
     }.than;
     std.mem.sort(TsWindowView, views.items, {}, less);
     const source_less = struct {
-        fn than(_: void, a: TsWindowSource, z: TsWindowSource) bool {
+        fn than(_: void, a: TsMarkupSource, z: TsMarkupSource) bool {
             return std.mem.order(u8, a.set_path, z.set_path) == .lt;
         }
     }.than;
-    std.mem.sort(TsWindowSource, sources.items, {}, source_less);
+    std.mem.sort(TsMarkupSource, sources.items, {}, source_less);
     return .{ .views = views.items, .sources = sources.items };
 }
 
+/// The root TypeScript view resolves imports from every `.native` file under
+/// `src/` except itself. Window files already come from collectTsWindowViews;
+/// append those under `windows/...` keys so this set matches the root disk
+/// resolver without changing the separate window resolver root.
+fn collectAppMarkupSources(b: *std.Build, app_root: []const u8, window_views: TsWindowViews) TsAppMarkupSources {
+    const src_path = appPath(b, app_root, "src");
+    var dir = b.build_root.handle.openDir(b.graph.io, src_path, .{ .iterate = true }) catch
+        return .{ .files = &.{}, .sources = &.{} };
+    defer dir.close(b.graph.io);
+    var walker = dir.walk(b.allocator) catch return .{ .files = &.{}, .sources = &.{} };
+    defer walker.deinit();
+
+    var files: std.ArrayList(TsMarkupSource) = .empty;
+    while (walker.next(b.graph.io) catch null) |entry| {
+        if (entry.kind != .file or !std.mem.endsWith(u8, entry.path, ".native")) continue;
+        const normalized_path = b.dupe(entry.path);
+        for (normalized_path) |*char| {
+            if (char.* == '\\') char.* = '/';
+        }
+        if (!isRootMarkupSourcePath(normalized_path)) continue;
+        validateMarkupSourcePath(normalized_path);
+        files.append(b.allocator, .{
+            .set_path = normalized_path,
+            .source_path = b.fmt("src/{s}", .{normalized_path}),
+            .staged_path = normalized_path,
+        }) catch @panic("OOM");
+    }
+
+    const less = struct {
+        fn than(_: void, a: TsMarkupSource, z: TsMarkupSource) bool {
+            return std.mem.order(u8, a.set_path, z.set_path) == .lt;
+        }
+    }.than;
+    std.mem.sort(TsMarkupSource, files.items, {}, less);
+
+    var sources: std.ArrayList(TsMarkupSource) = .empty;
+    sources.ensureTotalCapacity(b.allocator, files.items.len + window_views.sources.len) catch @panic("OOM");
+    sources.appendSliceAssumeCapacity(files.items);
+    for (window_views.sources) |source| {
+        validateMarkupSourcePath(source.staged_path);
+        sources.appendAssumeCapacity(.{
+            .set_path = source.staged_path,
+            .source_path = source.source_path,
+            .staged_path = source.staged_path,
+        });
+    }
+    std.mem.sort(TsMarkupSource, sources.items, {}, less);
+    return .{ .files = files.items, .sources = sources.items };
+}
+
+fn tsAppMarkupSourcesSource(b: *std.Build, registry: TsAppMarkupSources) []const u8 {
+    var out: std.ArrayList(u8) = .empty;
+    out.appendSlice(b.allocator,
+        \\//! Generated by build/app.zig from src/**/*.native.
+        \\const native_sdk = @import("native_sdk");
+        \\const canvas = native_sdk.canvas;
+        \\pub const sources = [_]canvas.ui_markup.SourceFile{
+        \\
+    ) catch @panic("OOM");
+    for (registry.sources) |source| {
+        const line = std.fmt.allocPrint(
+            b.allocator,
+            "    .{{ .path = \"{f}\", .source = @embedFile(\"{f}\") }},\n",
+            .{ std.zig.fmtString(source.set_path), std.zig.fmtString(source.staged_path) },
+        ) catch @panic("OOM");
+        out.appendSlice(b.allocator, line) catch @panic("OOM");
+    }
+    out.appendSlice(b.allocator, "};\n") catch @panic("OOM");
+    return out.items;
+}
+
 fn tsWindowRegistrySource(b: *std.Build, registry: TsWindowViews) []const u8 {
     const views = registry.views;
     var out: std.ArrayList(u8) = .empty;
@@ -757,6 +864,7 @@ fn tsCoreStage(
 ) TsCoreStage {
     const node = tsCorePreflight(b, dep, app_root);
     const window_views = collectTsWindowViews(b, app_root);
+    const app_markup_sources = collectAppMarkupSources(b, app_root, window_views);
     const has_services = appHasServiceFiles(b, app_root);
     if (!scriptcCompileSupported(b.graph.host.result, target)) {
         panicUnsupportedScriptcTarget(b, b.graph.host.result, target);
@@ -1052,9 +1160,13 @@ fn tsCoreStage(
     , .{ service_carrier, service_pool_workers }));
     _ = staged.addCopyFile(migrations_zig, "migrations.zig");
     _ = staged.addCopyFile(b.path(appPath(b, app_root, "src/app.native")), "app.native");
+    for (app_markup_sources.files) |source| {
+        _ = staged.addCopyFile(b.path(appPath(b, app_root, source.source_path)), source.staged_path);
+    }
     for (window_views.sources) |source| {
         _ = staged.addCopyFile(b.path(appPath(b, app_root, source.source_path)), source.staged_path);
     }
+    _ = staged.add("app_sources.zig", tsAppMarkupSourcesSource(b, app_markup_sources));
     _ = staged.add("window_views.zig", tsWindowRegistrySource(b, window_views));
     const main_root = staged.addCopyFile(dep.path("src/app_runner/ts_core_main.zig"), "main.zig");
     // The mobile wiring stages beside the desktop entry: same mirror, same
diff --git a/docs/src/app/docs/building-components/page.mdx b/docs/src/app/docs/building-components/page.mdx
index e6369b7ba..0e4425840 100644
--- a/docs/src/app/docs/building-components/page.mdx
+++ b/docs/src/app/docs/building-components/page.mdx
@@ -1,6 +1,6 @@
 # Building Components
 
-The library's built-ins cover the common register, and [theming](/docs/theming) restyles all of them at once. This page is about the pieces the library does not hand you: how to build a component of your own — first as a markup template, then as a Zig view function when the shape needs one — how it themes, and how component files spread across an app. Component code is toolkit-extension territory, so the Zig here applies whatever language the app core is written in: a TypeScript app that needs one custom widget writes that widget in Zig and keeps its core in TypeScript. The mechanics (template grammar, import rules, slots) are specified in [Native UI](/docs/native-ui#templates); this page builds one real component end to end.
+The library's built-ins cover the common register, and [theming](/docs/theming) restyles all of them at once. App components are Native markup templates: they compose built-ins, accept values through template args, accept content through slots, and live in `.native` component files. Component logic stays in the TypeScript core's ordinary `update` and derived helpers. The mechanics (template grammar, import rules, slots) are specified in [Native UI](/docs/native-ui#templates); this page builds one real component end to end.
 
 The ownership model in one line: **use and theme the built-ins by default; eject a library composite when you need to own its shape; build new composites from primitives when the library has no shape for it.** The last two are this page.
 
@@ -91,37 +91,11 @@ Args carry values; a `<slot/>` carries markup. A template body may mark one inse
 
 This is the container-component pattern: the template owns the frame, the caller owns the content. The full rules (one slot per body, children without a slot are an error, ids hash as if inlined) are in [Native UI § Components](/docs/native-ui#components).
 
-## When a component needs Zig
-
-The markup grammar is deliberately closed, and a few shapes sit outside it — the honest list is in [Native UI § Elements](/docs/native-ui#elements): components that carry **image ids** (pixels registered at runtime; the avatar's `image="{binding}"` is the one declarative exception), **per-cell templates** (a data grid's arbitrary render-per-column callbacks), and **Zig-side floating surfaces** (`popover`, `menu_surface`; the anchored `dropdown-menu` covers the declarative case). Beyond those, anything needing per-state styling past tokens (`ElementOptions.style`) or logic past the expression language belongs in Zig.
-
-A Zig component is just a function that takes the view builder and returns a node — the same primitives markup lowers to, with the same structural identity rules:
-
-```zig
-const canvas = native_sdk.canvas;
-const Ui = canvas.Ui(Msg);
-
-/// A contact row with an avatar image. Image pixels are registered at
-/// runtime and referenced by ImageId — a runtime value markup attributes
-/// cannot carry — so this component is a Zig view function.
-fn contactRow(ui: *Ui, name: []const u8, initials: []const u8, image: canvas.ImageId) Ui.Node {
-    return ui.el(.row, .{
-        .gap = 10,
-        .padding = 8,
-        .cross = .center,
-        .style_tokens = .{ .background = .surface, .radius = .md },
-        .semantics = .{ .role = .listitem, .label = name },
-    }, .{
-        // A zero id keeps the initials fallback — write the id into the
-        // model only on successful registration, and loading states cost
-        // no extra branch here.
-        ui.avatar(.{ .image = image, .size = .sm }, initials),
-        ui.text(.{ .grow = 1 }, name),
-    });
-}
-```
+## Put component logic in the core
+
+Templates own structure, not state. Keep state transitions in `update`, expose reusable derived values as exported TypeScript helpers, and bind those values into the component. A component never runs an app callback while the view builds.
 
-Call it from any Zig view (`contactRow(ui, contact.name, contact.initials, contact.avatar_image)`), key it inside `ui.each` loops like any node, and compose it with everything else the builder makes. Markup views and Zig views are not either/or per app — a markup root can be paired with Zig-built windows, and a Zig root can embed compiled markup fragments — but one component is one form: pick markup when the grammar covers it (hot reload and `native check` come free), Zig when it does not.
+When the closed markup vocabulary does not expose a lower-level engine capability yet, there is no app-side escape element or required Zig file. Use the nearest built-in composition and track the missing grammar admission. Toolkit extensions remain an SDK implementation concern.
 
 ## Theming your component
 
@@ -129,31 +103,18 @@ Your component themes the same way the built-ins do: through the token system, n
 
 In markup, the style attributes (`background`, `foreground`, `border-color`, `radius`, ...) are token **references** — the stat card above says `background="surface"`, not a hex value. References resolve against the app's live tokens on every rebuild, so the card follows dark mode, a theme-pack switch, and every override with zero component code. Unknown token names are check/compile errors.
 
-In a Zig view, `ElementOptions.style_tokens` is the same channel — `.style_tokens = .{ .background = .surface, .radius = .md }` records the reference, and the app loop resolves it against the current `DesignTokens` when the tree finalizes (`finalizeWithTokens`), re-resolving on every retheme. Explicit values through `ElementOptions.style` always win over a token reference; use them only for the values that are genuinely not design tokens (a user-picked highlight color, a data-derived fill).
-
-State washes follow one rule: hover feedback belongs to acting controls. List rows, menu items, buttons, and tab triggers wash on hover because the fill is the affordance — it names the thing you are about to act on. An image-forward content tile is the opposite case — a cover-art grid, a photo card — where the pointer rests on content, not a control register, and a wash over the artwork reads as a smudge. Those surfaces go quiet with the quiet-surface knob, `.style = .{ .quiet_hover = true }`, which silences only the hover fill: the pressed wash still marks the moment of commitment, and the focus ring, cursor intent, and hit testing keep their own channels. Like everything per-state beyond tokens, it is a Zig-side style decision; markup stays in the token vocabulary.
+State washes follow the built-in controls' behavior. Markup components customize their token references and compose the appropriate control kinds; app components do not add a second per-state styling channel.
 
-And the parts of your component that are built-in controls stay themed for free: the `<button>` inside the empty-state template wears `controls.button_primary` from the active theme, the `text` leaves read the typography rungs, the focus ring follows the token geometry. A template or view function composes primitives, so it inherits the whole register through them — retheme the app and your components move with it. That inheritance is the reason to reach for tokens before props: a component that takes a `color` arg has opted out of every future theme.
+And the parts of your component that are built-in controls stay themed for free: the `<button>` inside the empty-state template wears `controls.button_primary` from the active theme, the `text` leaves read the typography rungs, the focus ring follows the token geometry. A template composes primitives, so it inherits the whole register through them — retheme the app and your components move with it. That inheritance is the reason to reach for tokens before props: a component that takes a `color` arg has opted out of every future theme.
 
 ## Distributing components across an app
 
 Component files live wherever you like under the markup root (the root view file's directory) — `src/components/` is the convention the tooling writes to, and subdirectories work (`<import src="components/cards/stat-card.native"/>`). Paths are relative to the importing file, imports are transitive, and everything must stay under the markup root. Cycles are reported with the chain spelled out, and the same template name defined in two files is an error naming both sites — imports never shadow silently.
 
-Two build details to know as an app grows:
+The generated TypeScript app wiring handles both engine paths:
 
 - The runtime interpreter re-resolves imports from disk on hot reload, so `native dev` picks up edits to component files, not just the root view.
-- The compiled engine and the runtime share one embedded source set — add each component file to it once:
-
-```zig
-pub const app_markup_files = [_]canvas.ui_markup.SourceFile{
-    .{ .path = "app.native", .source = @embedFile("app.native") },
-    .{ .path = "components/stat-card.native", .source = @embedFile("components/stat-card.native") },
-};
-// runtime: .markup = .{ .source = app_markup, .sources = &app_markup_files, ... }
-// tests:   canvas.ui_markup.resolveImports(arena, "app.native", app_markup, loader, &diagnostic)
-```
-
-Zig components distribute the ordinary Zig way: a file per component (or a `components/` module), imported with `@import`.
+- Release and mobile builds embed every `.native` file under `src/` except the root. App code does not maintain an embed registry.
 
 ## Use, eject, or build
 
@@ -161,6 +122,6 @@ Three moves, in order of preference:
 
 **Theme it.** Every built-in reads the token register, and [theme packs, overrides, and full design systems](/docs/theming) reach every visual decision — colors, radii, control metrics, state washes, type. If your need is "the stepper, but in our palette," that is a token change, not a component.
 
-**Eject it.** When you need to own a composite's *shape* — reorder its parts, change its structure, grow it a feature — `native eject component <name>` writes the library composite's canonical source into `src/components/`, and from then on it is your code: edit freely, SDK updates never touch it. The ejectable set is exactly the library views that are honest compositions of primitives — today `stepper` and `timeline-item` (Zig view functions; their conditional structure and formatted text sit outside the markup grammar) and `timeline` (a markup template, since the container is pure composition). Each ejected file builds a widget tree identical to its library form at the moment of ejection — held by tests in the SDK — so ejecting changes ownership, never pixels. Ejected templates are reached through `<use template="timeline" ...>`, never a new element name, so the built-in element keeps working at unmigrated call sites; ejecting twice errors instead of overwriting your edits. Engine controls (buttons, text fields, tabs, ...) are deliberately not on the menu: their behavior lives in the runtime, and the way to change them is the token system, not a fork.
+**Eject it.** When you need to own a composite's *shape* — reorder its parts, change its structure, grow it a feature — `native eject component <name>` writes the library composite's canonical source into `src/components/`, and from then on it is your code: edit freely, SDK updates never touch it. Markup templates are reached through `<use template="...">`, never a new element name, so the built-in element keeps working at unmigrated call sites. Ejecting twice errors instead of overwriting your edits. Engine controls (buttons, text fields, tabs, ...) are deliberately not on the menu: their behavior lives in the runtime, and the way to change them is the token system, not a fork.
 
-**Build it.** When the library has no shape for it, compose one from primitives — the stat card and empty-state above, or a Zig view function when the shape needs Zig. Your component then themes, tests, and automates exactly like a built-in, because it is made of the same parts.
+**Build it.** When the library has no shape for it, compose one from markup primitives — the stat card and empty-state above. Your component then themes, tests, and automates exactly like a built-in, because it is made of the same parts.
diff --git a/docs/src/app/docs/native-ui/page.mdx b/docs/src/app/docs/native-ui/page.mdx
index 909baadb0..972c71167 100644
--- a/docs/src/app/docs/native-ui/page.mdx
+++ b/docs/src/app/docs/native-ui/page.mdx
@@ -161,15 +161,7 @@ Templates become shared components through `<import>`, which goes at the very to
 
 Paths resolve relative to the importing file, subdirectories and transitive imports included, and everything must stay under the markup root (the root view file's directory) — absolute paths and escapes are rejected. An imported file defines templates only: it is a component file, valid on its own for `native markup check`, and a view root inside one is an error. Importing splices the file's templates (and transitively its imports') before yours, in import order — exactly as if pasted at the import site — so the define-before-use rule is the only ordering rule to learn. Cycles are reported with the cycle path spelled out, and a template name defined twice is an error naming both definition sites: imports never shadow silently.
 
-Each engine resolves imports through its own source access. The runtime interpreter re-resolves from disk on hot reload, so `native dev` picks up edits to imported files too. The compiled engine takes an embedded source set — one `@embedFile` entry per file — which also feeds the app's markup options, so both engines see the same document:
-
-```zig
-pub const board_markup_files = [_]canvas.ui_markup.SourceFile{
-    .{ .path = "board.native", .source = @embedFile("board.native") },
-    .{ .path = "components/board-column.native", .source = @embedFile("components/board-column.native") },
-};
-pub const CompiledBoardView = canvas.CompiledMarkupImports(Model, Msg, "board.native", &board_markup_files);
-```
+In a default TypeScript app, `src/app.native` may import any component file under `src/`. The generated build discovers and embeds every other `.native` file for the runtime and compiled engines, including mobile builds. `native dev` re-resolves the imported closure from disk, so editing a component file refreshes the view without restarting. Secondary-window roots keep their narrower `src/windows/` import root.
 
 A template can also take markup children. The body marks the insertion point with a single `<slot/>`, and the use site's children build in the consumer's scope — they see the model paths and loop variables where the `<use>` is written — then land at the slot's position:
 
@@ -484,7 +476,7 @@ For timestamps, the facade owns the clocks (Zig 0.16 puts `std.time` behind `std
 
 ## Secondary windows
 
-In a default TypeScript app, export `windows(model): readonly WindowDescriptor[]` and put each possible window's markup at `src/windows/<label>.native`; the generated launcher compiles those files, maps descriptor labels to them, and includes shared components they import from nested paths under `src/windows/`. Construct descriptors with `windowDescriptor`. `closePolicy: "quit"` routes `onCloseCommand` through `commandMsg`; `"hide"` retains the window and dispatches no close command. `titlebar` includes `"chromeless"` for fully skinned windows. `examples/system-monitor-ts` is the complete default-path reference.
+In a default TypeScript app, export `windows(model): readonly WindowDescriptor[]` and put each possible window's markup at `src/windows/<label>.native`; the generated launcher compiles those files, maps descriptor labels to them, and includes components they import from nested paths under `src/windows/`. The main `src/app.native` view can import components anywhere under `src/`. Construct descriptors with `windowDescriptor`. `closePolicy: "quit"` routes `onCloseCommand` through `commandMsg`; `"hide"` retains the window and dispatches no close command. `titlebar` includes `"chromeless"` for fully skinned windows. `examples/system-monitor-ts` is the complete default-path reference.
 
 In Zig cores and custom wiring, windows are model-declared exactly like the tray: `Options.windows_fn` returns the window descriptors that should exist right now (presence IS liveness), and `Options.window_view` builds each declared window's whole canvas tree, keyed by the descriptor's window label. After every dispatched Msg the runtime reconciles: windows the model started declaring are created (a source-less native window wearing one `gpu_surface` view with the descriptor's `canvas_label`, inheriting the main canvas's gpu options), windows it stopped declaring close, and every open window's view rebuilds from the same model — a theme picked in the settings window restyles the main window on the same dispatch. There is no `visible` flag: transient visibility is host state changed through `hideWindow`/`showWindow` or a `.hide` close policy; stop declaring a window to really close it and release its retained views.
 
diff --git a/docs/src/app/docs/typescript/page.mdx b/docs/src/app/docs/typescript/page.mdx
index 43a2b2efe..406048088 100644
--- a/docs/src/app/docs/typescript/page.mdx
+++ b/docs/src/app/docs/typescript/page.mdx
@@ -480,6 +480,8 @@ Export `statusItems(model): readonly StatusItemDescriptor[]` when the app needs
 
 Export `windows(model): readonly WindowDescriptor[]` to derive the live secondary-window set from model state. Construct entries with `windowDescriptor` from `@native-sdk/core`, import `WindowDescriptor` from `@native-sdk/core/events`, and put each window's markup at `src/windows/<label>.native`. Spell the constructor label as a literal `label: asciiBytes("<label>")`; `native check` and every build reject dynamic labels or a label without that matching root. Window roots can import shared components nested under `src/windows/`; the generated launcher embeds and hot-reloads the complete import closure. Adding/removing descriptors creates/closes only those windows; all open windows rebuild from the same committed model.
 
+The main `src/app.native` view can import component files anywhere under `src/`, with `src/components/` as the convention. The generated launcher embeds every other `.native` source and watches the imported closure, so the same imports work in development, release builds, and mobile builds. Secondary-window roots remain narrower: they import within `src/windows/`.
+
 `closePolicy` accepts `"quit"` (the default) or `"hide"`. A `"quit"` user close routes `onCloseCommand` through `commandMsg`, where the app maps it to the Msg that clears its open flag. A `"hide"` close retains the same native window and view and dispatches no close command; `Cmd.showWindow(label)` reveals it. Model-declared secondary windows are desktop-only. See `examples/system-monitor-ts`.
 
 `titlebar` accepts `"standard"`, `"hidden_inset"`, `"hidden_inset_tall"`, or `"chromeless"`. Transparent Windows windows require `"chromeless"`; because that removes the system buttons, fully skinned windows must draw working close/minimize controls.
diff --git a/docs/src/app/docs/windows/page.mdx b/docs/src/app/docs/windows/page.mdx
index ae937321e..661ebebc0 100644
--- a/docs/src/app/docs/windows/page.mdx
+++ b/docs/src/app/docs/windows/page.mdx
@@ -174,7 +174,7 @@ Each window declares what the user's close affordance (the red traffic light, cm
 
 `UiApp.WindowDescriptor.close_policy` exposes the same enum for model-declared secondary windows. Descriptor presence means the window remains alive: a `.hide` user close retains its slot and views and does not dispatch `on_close`; `showWindow(label)` reveals that same window. Stopping the declaration still performs a real reconcile close.
 
-TypeScript cores expose the same contract as `windows(model): readonly WindowDescriptor[]`, with camel-case `closePolicy`. Each descriptor uses a literal `label: asciiBytes("<label>")` and the matching `src/windows/<label>.native`; check/build reject dynamic labels and missing roots. Those roots may import components nested under `src/windows/`. `titlebar` includes `"chromeless"`, including the transparent-Windows shape described above. Under `"quit"`, `onCloseCommand` routes through `commandMsg`; under `"hide"`, no close command fires because the window did not close.
+TypeScript cores expose the same contract as `windows(model): readonly WindowDescriptor[]`, with camel-case `closePolicy`. Each descriptor uses a literal `label: asciiBytes("<label>")` and the matching `src/windows/<label>.native`; check/build reject dynamic labels and missing roots. Those roots may import components nested under `src/windows/`; the main `src/app.native` view can import components anywhere under `src/`. `titlebar` includes `"chromeless"`, including the transparent-Windows shape described above. Under `"quit"`, `onCloseCommand` routes through `commandMsg`; under `"hide"`, no close command fires because the window did not close.
 
 `hide` is supported where the host can re-show a hidden window: macOS (`windowShouldClose` orders the window out) and Windows (`WM_CLOSE` hides via `SW_HIDE`; the tray icon is the ONLY re-show affordance, so on Windows `close_policy = "hide"` additionally requires the `"tray"` capability in app.zon — hiding removes the taskbar entry and Windows has no Dock-style reopen, so a declaration without the tray is refused at build time and at window create, exactly like Linux's refusal below; and if the declared tray fails to install at runtime, the first hide-close downgrades to a real close with a loud log rather than stranding an invisible process). On macOS the Dock reopen path exists only while `dock_visible = true`; an Accessory app has no Dock icon, so its status item must call `Cmd.showWindow(label)` to bring the window back. This is why `dock_visible = false` requires the `"tray"` capability. Linux has no status item in this toolkit yet, so nothing could bring a hidden window back — the declaration is refused loudly at build time (a compile error for manifest windows) and at window create (`error.UnsupportedWindowClosePolicy`), never a silent no-op. The hidden state is session-transient: it never persists to the window-state store, so every launch starts shown unless the manifest explicitly sets `initially_hidden = true`.
 
diff --git a/examples/kanban/README.md b/examples/kanban/README.md
index d34437943..adbd8693b 100644
--- a/examples/kanban/README.md
+++ b/examples/kanban/README.md
@@ -1,6 +1,6 @@
 # Native SDK Kanban (TypeScript)
 
-This three-column board is authored entirely in TypeScript + Native markup. `src/core.ts` is the model/update tier, `src/app.native` is the view, and `app.zon` is the desktop shell; no JavaScript runtime or app-owned Zig ships in the binary.
+This three-column board is authored entirely in TypeScript + Native markup. `src/core.ts` is the model/update tier, `src/app.native` is the root view, `src/components/board-column.native` holds its reusable column and card-list templates, and `app.zon` is the desktop shell; no JavaScript runtime or app-owned Zig ships in the binary.
 
 Drop one or more files anywhere on the board to add their basenames as Todo cards. The desktop host sends the native file-drop event through the runtime, and the core's `dropMsg` maps the full path list into one deterministic `files_dropped` message before `update` changes the board.
 
diff --git a/examples/kanban/src/app.native b/examples/kanban/src/app.native
index 86c784190..5b5dc0719 100644
--- a/examples/kanban/src/app.native
+++ b/examples/kanban/src/app.native
@@ -1,7 +1,6 @@
+<import src="components/board-column.native"/>
 <!-- The TypeScript Kanban view. Native file drops are handled by core.ts's
-     dropMsg channel; every dropped basename becomes a Todo card. Keep this
-     initial document self-contained: generated TS wiring embeds app.native
-     as the boot view, before the development disk watcher is armed. -->
+     dropMsg channel; every dropped basename becomes a Todo card. -->
 <column background="background">
   <!-- The header IS the titlebar (tall hidden-inset chrome). chromeMsg
        keeps its controls clear of the traffic lights. -->
@@ -11,77 +10,23 @@
     <button size="icon" variant="ghost" icon="plus" label="Add card" on-press="add"></button>
   </row>
   <row grow="1" gap="12" padding="16">
-    <column grow="1" gap="8" padding="10" label="Todo">
+    <use template="board-column" title="Todo">
       <text foreground="text_muted">Todo</text>
       <scroll grow="1" value="{todoScroll}" on-scroll="todo_scrolled" label="Todo cards">
-        <column gap="8">
-          <for each="todoCards" key="id" as="c">
-            <row global-key="{c.id}" on-drag="card_dropped:{c.id}" background="surface" radius="md" gap="8" padding="10" cross="center" role="listitem" label="{c.title}">
-              <column grow="1" gap="8">
-                <text>{c.title}</text>
-                <row height="24" gap="6" cross="center">
-                  <text size="sm" foreground="text_muted">NAT-{c.ticketNumber}</text>
-                  <spacer grow="1" />
-                  <if test="{c.assignee == 'openai'}">
-                    <avatar width="24" height="24" image="{c.avatarId}" label="OpenAI agent">OA</avatar>
-                  </if>
-                  <else>
-                    <avatar width="24" height="24" image="{c.avatarId}" label="Claude agent">CL</avatar>
-                  </else>
-                </row>
-              </column>
-            </row>
-          </for>
-        </column>
+        <use template="board-card-list" cards="{todoCards}" />
       </scroll>
-    </column>
-    <column grow="1" gap="8" padding="10" label="Doing">
+    </use>
+    <use template="board-column" title="Doing">
       <text foreground="text_muted">Doing</text>
       <scroll grow="1" value="{doingScroll}" on-scroll="doing_scrolled" label="Doing cards">
-        <column gap="8">
-          <for each="doingCards" key="id" as="c">
-            <row global-key="{c.id}" on-drag="card_dropped:{c.id}" background="surface" radius="md" gap="8" padding="10" cross="center" role="listitem" label="{c.title}">
-              <column grow="1" gap="8">
-                <text>{c.title}</text>
-                <row height="24" gap="6" cross="center">
-                  <text size="sm" foreground="text_muted">NAT-{c.ticketNumber}</text>
-                  <spacer grow="1" />
-                  <if test="{c.assignee == 'openai'}">
-                    <avatar width="24" height="24" image="{c.avatarId}" label="OpenAI agent">OA</avatar>
-                  </if>
-                  <else>
-                    <avatar width="24" height="24" image="{c.avatarId}" label="Claude agent">CL</avatar>
-                  </else>
-                </row>
-              </column>
-            </row>
-          </for>
-        </column>
+        <use template="board-card-list" cards="{doingCards}" />
       </scroll>
-    </column>
-    <column grow="1" gap="8" padding="10" label="Done">
+    </use>
+    <use template="board-column" title="Done">
       <text foreground="text_muted">Done</text>
       <scroll grow="1" value="{doneScroll}" on-scroll="done_scrolled" label="Done cards">
-        <column gap="8">
-          <for each="doneCards" key="id" as="c">
-            <row global-key="{c.id}" on-drag="card_dropped:{c.id}" background="surface" radius="md" gap="8" padding="10" cross="center" role="listitem" label="{c.title}">
-              <column grow="1" gap="8">
-                <text>{c.title}</text>
-                <row height="24" gap="6" cross="center">
-                  <text size="sm" foreground="text_muted">NAT-{c.ticketNumber}</text>
-                  <spacer grow="1" />
-                  <if test="{c.assignee == 'openai'}">
-                    <avatar width="24" height="24" image="{c.avatarId}" label="OpenAI agent">OA</avatar>
-                  </if>
-                  <else>
-                    <avatar width="24" height="24" image="{c.avatarId}" label="Claude agent">CL</avatar>
-                  </else>
-                </row>
-              </column>
-            </row>
-          </for>
-        </column>
+        <use template="board-card-list" cards="{doneCards}" />
       </scroll>
-    </column>
+    </use>
   </row>
 </column>
diff --git a/examples/kanban/src/components/board-column.native b/examples/kanban/src/components/board-column.native
new file mode 100644
index 000000000..c7aad2331
--- /dev/null
+++ b/examples/kanban/src/components/board-column.native
@@ -0,0 +1,26 @@
+<template name="board-card-list" args="cards">
+  <column gap="8">
+    <for each="cards" key="id" as="c">
+      <row global-key="{c.id}" on-drag="card_dropped:{c.id}" background="surface" radius="md" gap="8" padding="10" cross="center" role="listitem" label="{c.title}">
+        <column grow="1" gap="8">
+          <text>{c.title}</text>
+          <row height="24" gap="6" cross="center">
+            <text size="sm" foreground="text_muted">NAT-{c.ticketNumber}</text>
+            <spacer grow="1" />
+            <if test="{c.assignee == 'openai'}">
+              <avatar width="24" height="24" image="{c.avatarId}" label="OpenAI agent">OA</avatar>
+            </if>
+            <else>
+              <avatar width="24" height="24" image="{c.avatarId}" label="Claude agent">CL</avatar>
+            </else>
+          </row>
+        </column>
+      </row>
+    </for>
+  </column>
+</template>
+<template name="board-column" args="title">
+  <column grow="1" gap="8" padding="10" label="{title}">
+    <slot/>
+  </column>
+</template>
diff --git a/skill-data/native-ui/SKILL.md b/skill-data/native-ui/SKILL.md
index 4995de293..a40c24784 100644
--- a/skill-data/native-ui/SKILL.md
+++ b/skill-data/native-ui/SKILL.md
@@ -1058,7 +1058,7 @@ Rules and semantics:
 - SLOTS: a template body may contain one `<slot/>` (attribute-less, childless; named slots do not exist). The `<use>` site's children build IN THE CONSUMER'S SCOPE — they see the model paths and loop variables where the use is written — and land at the slot's position; ids hash as if inlined. A use with no children renders the slot empty; children on a slotless template are an error; a `<slot/>` inside use-site children (forwarding) is an error.
 - IMPORTS: `<import src="components/cards.native"/>` lines go at the very top of a file, before its templates. Paths are relative to the importing file (subdirectories and transitive imports fine, always under the root view file's directory — absolute paths and escapes are errors). An imported file defines templates ONLY (a component file; a view root inside one is an error, and a component file checks standalone). Importing splices the file's templates (transitively) BEFORE yours, in import order — as if pasted at the import site — so define-before-use stays the only ordering rule. Cycles are reported with the cycle path; duplicate template names are an error naming both definition sites.
 
-Both engines implement templates, defaults, slots, and imports: the interpreter expands at build time (hot reload re-resolves imports from disk, so edits to imported files reload), and the compiled engine inlines at comptime with the identical result. A document with imports compiles through `canvas.CompiledMarkupImports(Model, Msg, "root.native", &sources)` where `sources` is a `canvas.ui_markup.SourceFile` set (`.{ .path = "components/cards.native", .source = @embedFile("components/cards.native") }`, paths relative to the root file's directory); pass the same set on `MarkupOptions.sources` for the runtime engine. See `examples/kanban/src/board.native` + `examples/kanban/src/components/board-column.native`.
+Both engines implement templates, defaults, slots, and imports: the interpreter expands at build time (hot reload re-resolves imports from disk, so edits to imported files reload), and the compiled engine inlines at comptime with the identical result. A default TypeScript app's generated launcher discovers every component `.native` file under `src/`, embeds the same source set for both engines, and wires it on desktop and mobile. The main view can import anywhere under `src/`; secondary-window roots remain under `src/windows/`. Lower-level wiring compiles an imported document through `canvas.CompiledMarkupImports(Model, Msg, "root.native", &sources)` and passes the same `canvas.ui_markup.SourceFile` set on `MarkupOptions.sources`. See `examples/kanban/src/app.native` + `examples/kanban/src/components/board-column.native`.
 
 ## Code in markup: `<code>`
 
diff --git a/skill-data/ts-core/SKILL.md b/skill-data/ts-core/SKILL.md
index 5add87121..680981f7a 100644
--- a/skill-data/ts-core/SKILL.md
+++ b/skill-data/ts-core/SKILL.md
@@ -217,7 +217,7 @@ Commands are constructed inline in the return path and nowhere else (NS1017): ne
 
 Export `windows(model): readonly WindowDescriptor[]` to derive the secondary windows that should exist from committed model state. Import `WindowDescriptor` from `@native-sdk/core/events`, and construct entries with `windowDescriptor` from `@native-sdk/core` so omitted fields receive the canonical defaults. Presence is liveness: adding a descriptor creates the window, removing it closes the window and releases its retained view.
 
-Each possible label has a statically compiled Native markup view at `src/windows/<label>.native`; for example descriptor label `settings` uses `src/windows/settings.native`. Spell that identity directly inside the canonical constructor as `label: asciiBytes("settings")`: window labels are static declarations, and `native check`/every build reject a dynamic label or one whose root file is missing. Window roots may import shared components nested under `src/windows/` with the ordinary `<import>` syntax; the generated launcher embeds and hot-reloads the full import closure. The descriptor's `canvasLabel` must be unique across the whole app. Both the main view and every open window view rebuild from the same model after a Msg.
+Each possible label has a statically compiled Native markup view at `src/windows/<label>.native`; for example descriptor label `settings` uses `src/windows/settings.native`. Spell that identity directly inside the canonical constructor as `label: asciiBytes("settings")`: window labels are static declarations, and `native check`/every build reject a dynamic label or one whose root file is missing. Window roots may import components nested under `src/windows/` with the ordinary `<import>` syntax. The main `src/app.native` view can import component files anywhere under `src/`; the generated launcher embeds both source sets and hot-reloads each imported closure. The descriptor's `canvasLabel` must be unique across the whole app. Both the main view and every open window view rebuild from the same model after a Msg.
 
 ```ts
 import { asciiBytes, windowDescriptor } from "@native-sdk/core";
diff --git a/src/app_runner/ts_core_main.zig b/src/app_runner/ts_core_main.zig
index 3cf67f507..ad9ae3245 100644
--- a/src/app_runner/ts_core_main.zig
+++ b/src/app_runner/ts_core_main.zig
@@ -65,6 +65,7 @@ pub const core = @import("core.zig");
 const services = @import("services.zig");
 const service_carrier = @import("service_carrier.zig");
 const relational_migrations = @import("migrations.zig");
+const app_sources = @import("app_sources.zig");
 const window_views = @import("window_views.zig");
 
 pub const panic = std.debug.FullPanic(native_sdk.debug.capturePanic);
@@ -90,7 +91,7 @@ pub fn main(init: std.process.Init) !void {
         .name = manifest.name,
         .scene = shell_scene,
         .canvas_label = canvas_label,
-        .markup = .{ .source = app_markup, .watch_path = "src/app.native", .io = init.io },
+        .markup = .{ .source = app_markup, .sources = &app_sources.sources, .watch_path = "src/app.native", .io = init.io },
         // app.zon's theme pack; unthemed manifests get the house register.
         // The stock tokens compose the pack with the LIVE system
         // appearance, so TS apps follow the OS light/dark flip with no
diff --git a/src/app_runner/ts_core_mobile.zig b/src/app_runner/ts_core_mobile.zig
index d86cc7bbe..6083e4f72 100644
--- a/src/app_runner/ts_core_mobile.zig
+++ b/src/app_runner/ts_core_mobile.zig
@@ -38,6 +38,7 @@ const manifest = @import("app_manifest_zon");
 pub const core = @import("core.zig");
 const services = @import("services.zig");
 const service_carrier = @import("service_carrier.zig");
+const app_sources = @import("app_sources.zig");
 
 const Adapter = native_sdk.TsUiApp(core);
 
@@ -97,7 +98,7 @@ pub fn mobileOptions() Adapter.Options {
         .name = manifest.name,
         .scene = mobile_scene,
         .canvas_label = native_sdk.embed.mobile_gpu_surface_label,
-        .markup = .{ .source = app_markup },
+        .markup = .{ .source = app_markup, .sources = &app_sources.sources },
         // app.zon's theme pack and one-accent override, same as desktop.
         .theme = comptime manifestThemePack(),
         .theme_accent = comptime manifestThemeAccent(),
diff --git a/src/runtime/ui_app_tests.zig b/src/runtime/ui_app_tests.zig
index 2e0097bfa..282b3601d 100644
--- a/src/runtime/ui_app_tests.zig
+++ b/src/runtime/ui_app_tests.zig
@@ -2235,6 +2235,14 @@ const watch_import_parts_markup_v2 =
     \\</template>
 ;
 
+const watch_nested_import_root_markup =
+    \\<import src="components/actions.native"/>
+    \\<column gap="8" padding="12">
+    \\  <text>Count {count}</text>
+    \\  <use template="actions" />
+    \\</column>
+;
+
 test "the markup watch reloads when an IMPORTED file changes on disk" {
     const io = std.testing.io;
     const watch_path = ".zig-cache/ui-app-markup-watch-import-test.native";
@@ -2309,26 +2317,27 @@ test "the markup watch reloads when an IMPORTED file changes on disk" {
 }
 
 const watch_import_sources = [_]canvas.ui_markup.SourceFile{
-    .{ .path = "ui-app-markup-watch-import-baseline.native", .source = watch_import_root_markup },
-    .{ .path = "ui-app-markup-watch-parts.native", .source = watch_import_parts_markup },
+    .{ .path = "app.native", .source = watch_nested_import_root_markup },
+    .{ .path = "components/actions.native", .source = watch_import_parts_markup },
 };
 
 const CompiledImportCounterView = canvas.CompiledMarkupImports(
     CounterModel,
     CounterMsg,
-    "ui-app-markup-watch-import-baseline.native",
+    "app.native",
     &watch_import_sources,
 );
 
 test "with imports the compiled view stays the baseline until the watched closure changes" {
     const io = std.testing.io;
-    const watch_path = ".zig-cache/ui-app-markup-watch-import-baseline.native";
-    const parts_path = ".zig-cache/ui-app-markup-watch-parts.native";
+    const watch_root = ".zig-cache/ui-app-markup-watch-root";
+    const watch_path = watch_root ++ "/app.native";
+    const parts_path = watch_root ++ "/components/actions.native";
     const cwd = std.Io.Dir.cwd();
-    try cwd.writeFile(io, .{ .sub_path = watch_path, .data = watch_import_root_markup });
-    defer cwd.deleteFile(io, watch_path) catch {};
+    try cwd.createDirPath(io, watch_root ++ "/components");
+    defer cwd.deleteTree(io, watch_root) catch {};
+    try cwd.writeFile(io, .{ .sub_path = watch_path, .data = watch_nested_import_root_markup });
     try cwd.writeFile(io, .{ .sub_path = parts_path, .data = watch_import_parts_markup });
-    defer cwd.deleteFile(io, parts_path) catch {};
 
     const harness = try core.TestHarness().create(std.testing.allocator, .{ .size = geometry.SizeF.init(400, 300) });
     defer harness.destroy(std.testing.allocator);
@@ -2337,7 +2346,7 @@ test "with imports the compiled view stays the baseline until the watched closur
     var options = markupCounterOptions();
     options.view = CompiledImportCounterView.build;
     options.markup = .{
-        .source = watch_import_root_markup,
+        .source = watch_nested_import_root_markup,
         .sources = &watch_import_sources,
         .watch_path = watch_path,
         .io = io,
diff --git a/tests/ts-core/components/actions.native b/tests/ts-core/components/actions.native
new file mode 100644
index 000000000..e907a70c8
--- /dev/null
+++ b/tests/ts-core/components/actions.native
@@ -0,0 +1,10 @@
+<template name="board-actions">
+  <row gap="4">
+    <stack>
+      <button on-press="add">Add</button>
+      <tooltip anchor="above" tooltip-delay="200">Add a task</tooltip>
+    </stack>
+    <button on-press="cycle">Cycle</button>
+    <button on-press="clear">Clear</button>
+  </row>
+</template>
diff --git a/tests/ts-core/kanban_e2e_tests.zig b/tests/ts-core/kanban_e2e_tests.zig
index 80c672665..8787347c9 100644
--- a/tests/ts-core/kanban_e2e_tests.zig
+++ b/tests/ts-core/kanban_e2e_tests.zig
@@ -1,5 +1,5 @@
 //! End-to-end proof for examples/kanban: the real TypeScript core and
-//! shipping self-contained markup driven through TsUiApp. Native file drops
+//! shipping component-file markup driven through TsUiApp. Native file drops
 //! cross the platform/runtime/adapter boundary, add every basename to Todo, and
 //! the resulting cards keep their global-key identity while a live
 //! blank insertion slot reflows either column with retained drag motion and
@@ -16,7 +16,11 @@ const App = Adapter.App;
 const Bridge = Adapter.Host;
 
 const app_markup = @embedFile("app.native");
-const CompiledAppView = canvas.CompiledMarkupView(core.Model, core.Msg, app_markup);
+const app_markup_sources = [_]canvas.ui_markup.SourceFile{
+    .{ .path = "app.native", .source = app_markup },
+    .{ .path = "components/board-column.native", .source = @embedFile("components/board-column.native") },
+};
+const CompiledAppView = canvas.CompiledMarkupImports(core.Model, core.Msg, "app.native", &app_markup_sources);
 
 const canvas_label = "kanban-canvas";
 const app_views = [_]native_sdk.ShellView{
@@ -37,6 +41,14 @@ const Harness = struct {
     app: native_sdk.App,
 
     fn create() !*Harness {
+        return createConfigured(null);
+    }
+
+    fn createAutomated(directory: []const u8) !*Harness {
+        return createConfigured(directory);
+    }
+
+    fn createConfigured(automation_directory: ?[]const u8) !*Harness {
         const self = try std.testing.allocator.create(Harness);
         errdefer std.testing.allocator.destroy(self);
         self.harness = try native_sdk.TestHarness().create(std.testing.allocator, .{
@@ -44,6 +56,9 @@ const Harness = struct {
         });
         errdefer self.harness.destroy(std.testing.allocator);
         self.harness.null_platform.gpu_surfaces = true;
+        if (automation_directory) |directory| {
+            self.harness.runtime.options.automation = native_sdk.automation.Server.init(std.testing.io, directory, "Kanban");
+        }
         self.app_state = try std.testing.allocator.create(App);
         errdefer std.testing.allocator.destroy(self.app_state);
         self.app_state.* = Adapter.init(std.heap.page_allocator, .{}, .{
@@ -51,6 +66,7 @@ const Harness = struct {
             .scene = app_scene,
             .canvas_label = canvas_label,
             .view = CompiledAppView.build,
+            .markup = .{ .source = app_markup, .sources = &app_markup_sources },
         });
         self.app = self.app_state.app();
         try self.harness.start(self.app);
@@ -137,6 +153,21 @@ const Harness = struct {
     }
 };
 
+test "automation force reload resolves the root component source set" {
+    const directory = ".zig-cache/tmp/kanban-component-automation";
+    std.Io.Dir.cwd().deleteTree(std.testing.io, directory) catch {};
+    defer std.Io.Dir.cwd().deleteTree(std.testing.io, directory) catch {};
+
+    const h = try Harness.createAutomated(directory);
+    defer h.destroy();
+
+    // Automation asks UiApp to take the interpreter path on the first build.
+    // The imported board templates must resolve from the same embedded set
+    // the release-compiled view uses.
+    try std.testing.expect(h.app_state.markup_view != null);
+    try std.testing.expect(h.hasText("Retry failed agent runs"));
+}
+
 fn findTextIn(widget: canvas.Widget, text: []const u8) bool {
     if (std.mem.indexOf(u8, widget.text, text) != null) return true;
     for (widget.children) |child| {
diff --git a/tests/ts-core/markup_e2e_tests.zig b/tests/ts-core/markup_e2e_tests.zig
index 0ae211b70..de2f46d1f 100644
--- a/tests/ts-core/markup_e2e_tests.zig
+++ b/tests/ts-core/markup_e2e_tests.zig
@@ -34,7 +34,11 @@ const App = Adapter.App;
 const Bridge = Adapter.Host;
 
 const board_markup = @embedFile("markup_view.native");
-const CompiledBoardView = canvas.CompiledMarkupView(board.Model, board.Msg, board_markup);
+const board_markup_sources = [_]canvas.ui_markup.SourceFile{
+    .{ .path = "markup_view.native", .source = board_markup },
+    .{ .path = "components/actions.native", .source = @embedFile("components/actions.native") },
+};
+const CompiledBoardView = canvas.CompiledMarkupImports(board.Model, board.Msg, "markup_view.native", &board_markup_sources);
 
 const canvas_label = "ts-markup-canvas";
 
@@ -66,6 +70,7 @@ fn boardOptions() App.Options {
         // The comptime-compiled engine over the EMITTED model — markup
         // is the whole view tier of this app.
         .view = CompiledBoardView.build,
+        .markup = .{ .source = board_markup, .sources = &board_markup_sources },
         .on_command = boardCommand,
     };
 }
@@ -355,7 +360,10 @@ test "the runtime markup interpreter builds the emitted model exactly like the c
     };
 
     const BoardUi = canvas.Ui(board.Msg);
-    var interpreter_view = try canvas.MarkupView(board.Model, board.Msg).init(arena, board_markup);
+    var source_loader = canvas.ui_markup.SourceSetLoader{ .set = &board_markup_sources };
+    var diagnostic: canvas.ui_markup.MarkupErrorInfo = .{};
+    const document = try canvas.ui_markup.resolveImports(arena, "markup_view.native", board_markup, source_loader.loader(), &diagnostic);
+    var interpreter_view = canvas.MarkupView(board.Model, board.Msg).fromDocument(document);
     var interpreter_ui = BoardUi.init(arena);
     const interpreted = try interpreter_ui.finalize(try interpreter_view.build(&interpreter_ui, &model));
     var compiled_ui = BoardUi.init(arena);
diff --git a/tests/ts-core/markup_view.native b/tests/ts-core/markup_view.native
index 292899499..e5c88deab 100644
--- a/tests/ts-core/markup_view.native
+++ b/tests/ts-core/markup_view.native
@@ -1,3 +1,4 @@
+<import src="components/actions.native"/>
 <column gap="6" padding="10">
   <text>{banner} filter {filter} next {nextId}</text>
   <text>done {doneCount} hover {hoveredId}</text>
@@ -9,14 +10,7 @@
     <text>draft [{draft}]</text>
   </row>
   <media-surface surface="{previewSurface}" width="160" height="40" label="Preview" />
-  <row gap="4">
-    <stack>
-      <button on-press="add">Add</button>
-      <tooltip anchor="above" tooltip-delay="200">Add a task</tooltip>
-    </stack>
-    <button on-press="cycle">Cycle</button>
-    <button on-press="clear">Clear</button>
-  </row>
+  <use template="board-actions" />
   <for each="tasks" as="t" key="id">
     <row key="{t.id}" gap="4" cross="center" on-hover-enter="hover_row:{t.id}" on-hover-leave="hover_off:{t.id}">
       <text grow="1">{t.title} #{t.id}</text>

From 3a3fe142e3766d8fd980309daea789502c8ab41c Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Mon, 17 Aug 2026 15:08:39 -0500
Subject: [PATCH 2/6] fix(ts): compile root markup imports

---
 build.zig                                     | 22 +++++++++++++++++
 .../src/app/docs/building-components/page.mdx |  6 ++---
 src/app_runner/ts_core_main.zig               | 17 +++++++++----
 src/app_runner/ts_core_mobile.zig             | 11 ++++++---
 src/root.zig                                  |  1 +
 src/runtime/root.zig                          |  1 +
 src/runtime/ts_ui_app.zig                     | 13 +++++++++-
 tests/ts-core/invalid_import_compile.zig      | 24 +++++++++++++++++++
 8 files changed, 83 insertions(+), 12 deletions(-)
 create mode 100644 tests/ts-core/invalid_import_compile.zig

diff --git a/build.zig b/build.zig
index 6b270b3db..19b557fcf 100644
--- a/build.zig
+++ b/build.zig
@@ -111,6 +111,19 @@ test "root TypeScript markup discovery classification and resolver budgets" {
     try std.testing.expect(!app_build.markupSourcePathWithinBudget("a" ** 201));
 }
 
+test "generated TypeScript runners install the compiled root markup view" {
+    const desktop = @embedFile("src/app_runner/ts_core_main.zig");
+    try std.testing.expect(std.mem.indexOf(u8, desktop, "TsUiAppWithFeatures(core, .{ .runtime_markup = dev })") != null);
+    try std.testing.expect(std.mem.indexOf(u8, desktop, "CompiledMarkupImports(core.Model, core.Msg, \"app.native\", &app_markup_sources)") != null);
+    try std.testing.expect(std.mem.indexOf(u8, desktop, ".view = CompiledAppView.build") != null);
+
+    const mobile = @embedFile("src/app_runner/ts_core_mobile.zig");
+    try std.testing.expect(std.mem.indexOf(u8, mobile, "TsUiAppWithFeatures(core, .{ .runtime_markup = false })") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, "CompiledMarkupImports(core.Model, core.Msg, \"app.native\", &app_markup_sources)") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, ".view = CompiledAppView.build") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, ".markup =") == null);
+}
+
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const host_target = b.graph.host;
@@ -404,6 +417,13 @@ pub fn build(b: *std.Build) void {
     const evals_cmdview_mod = module(b, target, optimize, "evals/harness-lib/cmdview.zig");
     const evals_cmdview_tests = testArtifact(b, evals_cmdview_mod);
     const build_graph_tests = testArtifact(b, module(b, host_target, optimize, "build.zig"));
+    const invalid_import_compile_mod = module(b, target, optimize, "tests/ts-core/invalid_import_compile.zig");
+    invalid_import_compile_mod.addImport("canvas", canvas_mod);
+    const invalid_import_compile = b.addObject(.{
+        .name = "ts-invalid-import-compile",
+        .root_module = invalid_import_compile_mod,
+    });
+    invalid_import_compile.expect_errors = .{ .contains = "imported files define templates only - this file has a view root element; move the view to its own file and import just the templates" };
 
     // `native version` names the commit the binary was built from, so
     // binary/framework skew ("your native binary may be stale") is a
@@ -628,6 +648,7 @@ pub fn build(b: *std.Build) void {
     };
 
     const test_step = b.step("test", "Run package and framework tests");
+    test_step.dependOn(&invalid_import_compile.step);
     test_step.dependOn(&b.addRunArtifact(build_graph_tests).step);
     test_step.dependOn(&b.addRunArtifact(geometry_tests).step);
     test_step.dependOn(&b.addRunArtifact(assets_tests).step);
@@ -675,6 +696,7 @@ pub fn build(b: *std.Build) void {
         const markup_components_e2e_step = b.step("test-ts-markup-components-e2e", "Run root component-file compiled, interpreter, automation, and replay coverage");
         markup_components_e2e_step.dependOn(&markup_e2e_run.step);
         markup_components_e2e_step.dependOn(&kanban_e2e_run.step);
+        markup_components_e2e_step.dependOn(&invalid_import_compile.step);
         ts_services_e2e_step.dependOn(&feed_reader_e2e_run.step);
         ts_services_e2e_step.dependOn(&services_e2e_run.step);
         // The same fixture through the in-process carrier (ServicePool over
diff --git a/docs/src/app/docs/building-components/page.mdx b/docs/src/app/docs/building-components/page.mdx
index 0e4425840..56dc70fef 100644
--- a/docs/src/app/docs/building-components/page.mdx
+++ b/docs/src/app/docs/building-components/page.mdx
@@ -95,7 +95,7 @@ This is the container-component pattern: the template owns the frame, the caller
 
 Templates own structure, not state. Keep state transitions in `update`, expose reusable derived values as exported TypeScript helpers, and bind those values into the component. A component never runs an app callback while the view builds.
 
-When the closed markup vocabulary does not expose a lower-level engine capability yet, there is no app-side escape element or required Zig file. Use the nearest built-in composition and track the missing grammar admission. Toolkit extensions remain an SDK implementation concern.
+When the closed markup vocabulary does not expose a lower-level engine capability, keep the TypeScript core and extend only the view tier with a Zig view function over `canvas.Ui`. This is the app-side escape hatch for shapes such as `data_grid` cell renderers or lower-level floating surfaces; it is toolkit-extension work, not a reason to migrate the app's core. Prefer markup while its grammar covers the component, because templates keep `native check` and hot reload automatic.
 
 ## Theming your component
 
@@ -103,7 +103,7 @@ Your component themes the same way the built-ins do: through the token system, n
 
 In markup, the style attributes (`background`, `foreground`, `border-color`, `radius`, ...) are token **references** — the stat card above says `background="surface"`, not a hex value. References resolve against the app's live tokens on every rebuild, so the card follows dark mode, a theme-pack switch, and every override with zero component code. Unknown token names are check/compile errors.
 
-State washes follow the built-in controls' behavior. Markup components customize their token references and compose the appropriate control kinds; app components do not add a second per-state styling channel.
+State washes follow the built-in controls' behavior. Markup components customize their token references and compose the appropriate control kinds. A Zig view extension may use `ElementOptions.style` for a state-specific visual the token vocabulary does not expose; keep that exception local to the extension.
 
 And the parts of your component that are built-in controls stay themed for free: the `<button>` inside the empty-state template wears `controls.button_primary` from the active theme, the `text` leaves read the typography rungs, the focus ring follows the token geometry. A template composes primitives, so it inherits the whole register through them — retheme the app and your components move with it. That inheritance is the reason to reach for tokens before props: a component that takes a `color` arg has opted out of every future theme.
 
@@ -124,4 +124,4 @@ Three moves, in order of preference:
 
 **Eject it.** When you need to own a composite's *shape* — reorder its parts, change its structure, grow it a feature — `native eject component <name>` writes the library composite's canonical source into `src/components/`, and from then on it is your code: edit freely, SDK updates never touch it. Markup templates are reached through `<use template="...">`, never a new element name, so the built-in element keeps working at unmigrated call sites. Ejecting twice errors instead of overwriting your edits. Engine controls (buttons, text fields, tabs, ...) are deliberately not on the menu: their behavior lives in the runtime, and the way to change them is the token system, not a fork.
 
-**Build it.** When the library has no shape for it, compose one from markup primitives — the stat card and empty-state above. Your component then themes, tests, and automates exactly like a built-in, because it is made of the same parts.
+**Build it.** When the library has no shape for it, compose one from markup primitives — the stat card and empty-state above — or use a Zig view function when the closed markup grammar cannot express the shape. Your component then themes, tests, and automates through the same widget tree as a built-in.
diff --git a/src/app_runner/ts_core_main.zig b/src/app_runner/ts_core_main.zig
index ad9ae3245..aee3597cf 100644
--- a/src/app_runner/ts_core_main.zig
+++ b/src/app_runner/ts_core_main.zig
@@ -20,9 +20,9 @@
 //!                    path with no `cachePath` in the core.
 //!   update loop      the transpiled core through `TsUiApp(core)` — the
 //!                    committed TS model IS the app model.
-//!   view             app.native over the model's own field names (the
-//!                    emitted Zig keeps the TS spellings), hot-reloaded
-//!                    from src/app.native in Debug.
+//!   view             app.native and its imported component closure,
+//!                    compiled at comptime over the model's own field
+//!                    names; Debug also hot-reloads from src/app.native.
 //!   menus/shortcuts  a core exporting `commandMsg(name): Msg | null`
 //!                    receives command events (menus, shortcuts, chrome
 //!                    tabs, status-item rows) as ordinary Msgs; without
@@ -58,6 +58,7 @@
 //! regenerates from the SDK on every build.
 
 const std = @import("std");
+const builtin = @import("builtin");
 const runner = @import("runner");
 const native_sdk = @import("native_sdk");
 const manifest = @import("app_manifest_zon");
@@ -75,12 +76,17 @@ pub const panic = std.debug.FullPanic(native_sdk.debug.capturePanic);
 pub const Model = core.Model;
 pub const Msg = core.Msg;
 
-const Adapter = native_sdk.TsUiApp(core);
+const dev = builtin.mode == .Debug;
+const Adapter = native_sdk.TsUiAppWithFeatures(core, .{ .runtime_markup = dev });
 const App = Adapter.App;
 
 const shell_scene = native_sdk.app_manifest.shellConfigFrom(manifest);
 const canvas_label = native_sdk.app_manifest.firstGpuSurfaceLabel(shell_scene);
 pub const app_markup = @embedFile("app.native");
+const app_markup_sources = [_]native_sdk.canvas.ui_markup.SourceFile{
+    .{ .path = "app.native", .source = app_markup },
+} ++ app_sources.sources;
+const CompiledAppView = native_sdk.canvas.CompiledMarkupImports(core.Model, core.Msg, "app.native", &app_markup_sources);
 
 const app_permissions = manifestStringList(manifest, "permissions");
 const allowed_origins = manifestAllowedOrigins();
@@ -91,7 +97,8 @@ pub fn main(init: std.process.Init) !void {
         .name = manifest.name,
         .scene = shell_scene,
         .canvas_label = canvas_label,
-        .markup = .{ .source = app_markup, .sources = &app_sources.sources, .watch_path = "src/app.native", .io = init.io },
+        .view = CompiledAppView.build,
+        .markup = if (dev) .{ .source = app_markup, .sources = &app_markup_sources, .watch_path = "src/app.native", .io = init.io } else null,
         // app.zon's theme pack; unthemed manifests get the house register.
         // The stock tokens compose the pack with the LIVE system
         // appearance, so TS apps follow the OS light/dark flip with no
diff --git a/src/app_runner/ts_core_mobile.zig b/src/app_runner/ts_core_mobile.zig
index 6083e4f72..edfa45eeb 100644
--- a/src/app_runner/ts_core_mobile.zig
+++ b/src/app_runner/ts_core_mobile.zig
@@ -5,7 +5,8 @@
 //! embed host's AppDef contract (`Model`, `Msg`, `initModel`,
 //! `mobileOptions` — see `src/embed/ui_host.zig`) over the same staged
 //! mirror (core.zig), markup (app.native), service registry (services.zig),
-//! and carrier constant (service_carrier.zig) the desktop wiring uses.
+//! carrier constant (service_carrier.zig), and comptime-compiled root
+//! markup closure the desktop wiring uses.
 //!
 //! What differs from ts_core_main.zig is only the shell:
 //!
@@ -40,7 +41,7 @@ const services = @import("services.zig");
 const service_carrier = @import("service_carrier.zig");
 const app_sources = @import("app_sources.zig");
 
-const Adapter = native_sdk.TsUiApp(core);
+const Adapter = native_sdk.TsUiAppWithFeatures(core, .{ .runtime_markup = false });
 
 /// Re-exported for the embed host's AppDef contract (and any test that
 /// reflects the core's real surface).
@@ -48,6 +49,10 @@ pub const Model = core.Model;
 pub const Msg = core.Msg;
 
 pub const app_markup = @embedFile("app.native");
+const app_markup_sources = [_]native_sdk.canvas.ui_markup.SourceFile{
+    .{ .path = "app.native", .source = app_markup },
+} ++ app_sources.sources;
+const CompiledAppView = native_sdk.canvas.CompiledMarkupImports(core.Model, core.Msg, "app.native", &app_markup_sources);
 
 comptime {
     // The build graph resolves the carrier before staging this file; a
@@ -98,7 +103,7 @@ pub fn mobileOptions() Adapter.Options {
         .name = manifest.name,
         .scene = mobile_scene,
         .canvas_label = native_sdk.embed.mobile_gpu_surface_label,
-        .markup = .{ .source = app_markup, .sources = &app_sources.sources },
+        .view = CompiledAppView.build,
         // app.zon's theme pack and one-accent override, same as desktop.
         .theme = comptime manifestThemePack(),
         .theme_accent = comptime manifestThemeAccent(),
diff --git a/src/root.zig b/src/root.zig
index 1e68d4ee9..83851186c 100644
--- a/src/root.zig
+++ b/src/root.zig
@@ -159,6 +159,7 @@ pub const max_effect_host_payload_bytes = runtime.max_effect_host_payload_bytes;
 pub const max_effect_host_result_bytes = runtime.max_effect_host_result_bytes;
 pub const TsCoreHost = runtime.TsCoreHost;
 pub const TsUiApp = runtime.TsUiApp;
+pub const TsUiAppWithFeatures = runtime.TsUiAppWithFeatures;
 pub const Clock = runtime.Clock;
 pub const TestClock = runtime.TestClock;
 pub const nowMs = runtime.nowMs;
diff --git a/src/runtime/root.zig b/src/runtime/root.zig
index d6a79e930..fa7da80c8 100644
--- a/src/runtime/root.zig
+++ b/src/runtime/root.zig
@@ -194,6 +194,7 @@ pub const ts_core_file_stream_key_base = runtime_ts_core_host.file_stream_key_ba
 
 const runtime_ts_ui_app = @import("ts_ui_app.zig");
 pub const TsUiApp = runtime_ts_ui_app.TsUiApp;
+pub const TsUiAppWithFeatures = runtime_ts_ui_app.TsUiAppWithFeatures;
 
 const runtime_session_journal = @import("session_journal.zig");
 const runtime_session_record = @import("session_record.zig");
diff --git a/src/runtime/ts_ui_app.zig b/src/runtime/ts_ui_app.zig
index 7dc06b340..4209fca05 100644
--- a/src/runtime/ts_ui_app.zig
+++ b/src/runtime/ts_ui_app.zig
@@ -69,6 +69,10 @@
 //! process contract is the bridge's: one live app per core module (two
 //! apps over one core would share a committed root), and one compiled
 //! archive per process (the fixed-prefix C ABI symbol set).
+//!
+//! Generated launchers use `TsUiAppWithFeatures` to compile the runtime
+//! markup interpreter out of release and mobile artifacts while preserving
+//! `TsUiApp` as the full-featured default for hand wiring and tests.
 
 const std = @import("std");
 const canvas = @import("canvas");
@@ -103,6 +107,13 @@ fn scaledTypeScanQuota(comptime T: type, comptime scans: usize) u32 {
 }
 
 pub fn TsUiApp(comptime core: type) type {
+    return TsUiAppWithFeatures(core, .{});
+}
+
+/// Feature-selectable counterpart used by generated wiring: Debug desktop
+/// apps keep the runtime markup interpreter for hot reload, while release and
+/// mobile apps compile it out after installing the same comptime view.
+pub fn TsUiAppWithFeatures(comptime core: type, comptime features: ui_app.UiAppFeatures) type {
     return struct {
         /// The effect bridge — shared with any direct `TsCoreHost(core)`
         /// instantiation (comptime memoization), so harnesses can read
@@ -110,7 +121,7 @@ pub fn TsUiApp(comptime core: type) type {
         pub const Host = ts_core_host.TsCoreHost(core);
         pub const Model = core.Model;
         pub const Msg = core.Msg;
-        pub const App = ui_app.UiApp(Model, Msg);
+        pub const App = ui_app.UiAppWithFeatures(Model, Msg, features);
         pub const Options = App.Options;
         pub const Effects = App.Effects;
         pub const Ui = App.Ui;
diff --git a/tests/ts-core/invalid_import_compile.zig b/tests/ts-core/invalid_import_compile.zig
new file mode 100644
index 000000000..d83c44bb9
--- /dev/null
+++ b/tests/ts-core/invalid_import_compile.zig
@@ -0,0 +1,24 @@
+const canvas = @import("canvas");
+
+const Model = struct {};
+const Msg = union(enum) { one, two };
+
+const sources = [_]canvas.ui_markup.SourceFile{
+    .{
+        .path = "app.native",
+        .source =
+        \\<import src="components/broken.native"/>
+        \\<use template="broken" />
+        ,
+    },
+    .{
+        .path = "components/broken.native",
+        .source = "<column><text>component files cannot define a view root</text></column>",
+    },
+};
+
+const View = canvas.CompiledMarkupImports(Model, Msg, "app.native", &sources);
+
+comptime {
+    _ = View.document;
+}

From 61c652d5a2baa84c6aa6f8e360bfb37e212e6fc4 Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Mon, 17 Aug 2026 15:26:30 -0500
Subject: [PATCH 3/6] docs: correct TypeScript component extension guidance

---
 docs/src/app/docs/building-components/page.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/app/docs/building-components/page.mdx b/docs/src/app/docs/building-components/page.mdx
index 56dc70fef..5f66cb360 100644
--- a/docs/src/app/docs/building-components/page.mdx
+++ b/docs/src/app/docs/building-components/page.mdx
@@ -95,7 +95,7 @@ This is the container-component pattern: the template owns the frame, the caller
 
 Templates own structure, not state. Keep state transitions in `update`, expose reusable derived values as exported TypeScript helpers, and bind those values into the component. A component never runs an app callback while the view builds.
 
-When the closed markup vocabulary does not expose a lower-level engine capability, keep the TypeScript core and extend only the view tier with a Zig view function over `canvas.Ui`. This is the app-side escape hatch for shapes such as `data_grid` cell renderers or lower-level floating surfaces; it is toolkit-extension work, not a reason to migrate the app's core. Prefer markup while its grammar covers the component, because templates keep `native check` and hot reload automatic.
+When the closed markup vocabulary does not expose a lower-level engine capability yet, there is no app-side escape element or required Zig file. Use the nearest built-in composition and track the missing grammar admission. Toolkit extensions remain an SDK implementation concern.
 
 ## Theming your component
 
@@ -124,4 +124,4 @@ Three moves, in order of preference:
 
 **Eject it.** When you need to own a composite's *shape* — reorder its parts, change its structure, grow it a feature — `native eject component <name>` writes the library composite's canonical source into `src/components/`, and from then on it is your code: edit freely, SDK updates never touch it. Markup templates are reached through `<use template="...">`, never a new element name, so the built-in element keeps working at unmigrated call sites. Ejecting twice errors instead of overwriting your edits. Engine controls (buttons, text fields, tabs, ...) are deliberately not on the menu: their behavior lives in the runtime, and the way to change them is the token system, not a fork.
 
-**Build it.** When the library has no shape for it, compose one from markup primitives — the stat card and empty-state above — or use a Zig view function when the closed markup grammar cannot express the shape. Your component then themes, tests, and automates through the same widget tree as a built-in.
+**Build it.** When the library has no shape for it, compose one from markup primitives — the stat card and empty-state above. Your component then themes, tests, and automates exactly like a built-in, because it is made of the same parts.

From 84502e8aed563e6d8f8ef07b15dfe2f23b302f42 Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Mon, 17 Aug 2026 15:41:39 -0500
Subject: [PATCH 4/6] fix(ts): align mobile markup features

---
 build.zig                         | 3 ++-
 src/app_runner/ts_core_mobile.zig | 5 ++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/build.zig b/build.zig
index 19b557fcf..ed5967067 100644
--- a/build.zig
+++ b/build.zig
@@ -118,7 +118,8 @@ test "generated TypeScript runners install the compiled root markup view" {
     try std.testing.expect(std.mem.indexOf(u8, desktop, ".view = CompiledAppView.build") != null);
 
     const mobile = @embedFile("src/app_runner/ts_core_mobile.zig");
-    try std.testing.expect(std.mem.indexOf(u8, mobile, "TsUiAppWithFeatures(core, .{ .runtime_markup = false })") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, "pub const features: native_sdk.UiAppFeatures = .{ .runtime_markup = false }") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, "TsUiAppWithFeatures(core, features)") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, "CompiledMarkupImports(core.Model, core.Msg, \"app.native\", &app_markup_sources)") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, ".view = CompiledAppView.build") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, ".markup =") == null);
diff --git a/src/app_runner/ts_core_mobile.zig b/src/app_runner/ts_core_mobile.zig
index edfa45eeb..a3d5b1484 100644
--- a/src/app_runner/ts_core_mobile.zig
+++ b/src/app_runner/ts_core_mobile.zig
@@ -41,7 +41,10 @@ const services = @import("services.zig");
 const service_carrier = @import("service_carrier.zig");
 const app_sources = @import("app_sources.zig");
 
-const Adapter = native_sdk.TsUiAppWithFeatures(core, .{ .runtime_markup = false });
+/// Shared with the embed host: its UiApp type must use the same feature set
+/// as this module's TypeScript adapter or their Options types are distinct.
+pub const features: native_sdk.UiAppFeatures = .{ .runtime_markup = false };
+const Adapter = native_sdk.TsUiAppWithFeatures(core, features);
 
 /// Re-exported for the embed host's AppDef contract (and any test that
 /// reflects the core's real surface).

From 7c90ebcc509e5992a1ac376cc4d16532a610f21d Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Mon, 17 Aug 2026 16:03:51 -0500
Subject: [PATCH 5/6] fix(ts): align markup source path budgets

---
 build.zig     | 13 +++++++++----
 build/app.zig | 13 ++++++++++---
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/build.zig b/build.zig
index ed5967067..7db204ef2 100644
--- a/build.zig
+++ b/build.zig
@@ -105,10 +105,15 @@ test "root TypeScript markup discovery classification and resolver budgets" {
     try std.testing.expect(!app_build.isRootMarkupSourcePath("windows/settings.native"));
     try std.testing.expect(!app_build.isRootMarkupSourcePath("components/card.ts"));
 
-    try std.testing.expect(app_build.markupSourcePathWithinBudget("a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a"));
-    try std.testing.expect(!app_build.markupSourcePathWithinBudget("a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a/a"));
-    try std.testing.expect(app_build.markupSourcePathWithinBudget("a" ** 200));
-    try std.testing.expect(!app_build.markupSourcePathWithinBudget("a" ** 201));
+    // The authored paths are relative to src/, while native check and the
+    // desktop hot-reload resolver see the leading `src/` too. Pin the exact
+    // source-relative boundaries that keep those full paths within 24
+    // segments and 200 bytes.
+    const max_segments_path = "a/" ** 22 ++ "a";
+    try std.testing.expect(app_build.markupSourcePathWithinBudget(max_segments_path));
+    try std.testing.expect(!app_build.markupSourcePathWithinBudget(max_segments_path ++ "/a"));
+    try std.testing.expect(app_build.markupSourcePathWithinBudget("a" ** 196));
+    try std.testing.expect(!app_build.markupSourcePathWithinBudget("a" ** 197));
 }
 
 test "generated TypeScript runners install the compiled root markup view" {
diff --git a/build/app.zig b/build/app.zig
index 396de2ed7..7bd59d3d6 100644
--- a/build/app.zig
+++ b/build/app.zig
@@ -105,18 +105,25 @@ const TsAppMarkupSources = struct {
 
 const max_markup_source_path_len = 200;
 const max_markup_source_path_segments = 24;
+const root_markup_source_prefix = "src/";
 
+/// Whether a path relative to `src/` fits the markup resolver once the
+/// generated desktop watch and `native check` address it as `src/<path>`.
+/// The compiled source set drops that prefix, but accepting a path only the
+/// compiled resolver can represent would make development and release
+/// disagree at the boundary.
 pub fn markupSourcePathWithinBudget(path: []const u8) bool {
-    var segments: usize = 0;
+    var segments: usize = 1; // the disk resolver's leading `src` segment
     var it = std.mem.tokenizeScalar(u8, path, '/');
     while (it.next() != null) segments += 1;
-    return path.len <= max_markup_source_path_len and segments <= max_markup_source_path_segments;
+    return root_markup_source_prefix.len + path.len <= max_markup_source_path_len and
+        segments <= max_markup_source_path_segments;
 }
 
 fn validateMarkupSourcePath(path: []const u8) void {
     if (!markupSourcePathWithinBudget(path)) {
         std.debug.panic(
-            "\nTypeScript markup source path `{s}` exceeds the import resolver budget: keep every src/-relative .native path at most {d} bytes and {d} segments\n",
+            "\nTypeScript markup source path `src/{s}` exceeds the import resolver budget: the full app-relative path, including `src/`, must be at most {d} bytes and {d} segments\n",
             .{ path, max_markup_source_path_len, max_markup_source_path_segments },
         );
     }

From 38e7cec09811b081e3927c35babc96da4c3fff09 Mon Sep 17 00:00:00 2001
From: Chris Tate <chris@ctate.dev>
Date: Wed, 19 Aug 2026 15:32:43 -0500
Subject: [PATCH 6/6] fix(ts): preserve component import build parity

---
 build.zig                                 | 26 ++++++++++
 build/app.zig                             | 43 +++++++++++++---
 src/app_runner/ts_core_main.zig           |  5 +-
 src/app_runner/ts_core_mobile.zig         |  4 +-
 src/primitives/canvas/ui_markup.zig       | 19 ++++++-
 src/primitives/canvas/ui_markup_tests.zig | 37 +++++++++++++
 tools/native-sdk/main.zig                 |  2 +-
 tools/native-sdk/markup.zig               | 63 ++++++++++++++++++++---
 8 files changed, 179 insertions(+), 20 deletions(-)

diff --git a/build.zig b/build.zig
index 8b79613d4..109ccb572 100644
--- a/build.zig
+++ b/build.zig
@@ -126,17 +126,43 @@ test "root TypeScript markup discovery classification and resolver budgets" {
 test "generated TypeScript runners install the compiled root markup view" {
     const desktop = @embedFile("src/app_runner/ts_core_main.zig");
     try std.testing.expect(std.mem.indexOf(u8, desktop, "TsUiAppWithFeatures(core, .{ .runtime_markup = dev })") != null);
+    try std.testing.expect(std.mem.indexOf(u8, desktop, "if (dev) void else @import(\"app_markup_root\")") != null);
     try std.testing.expect(std.mem.indexOf(u8, desktop, "CompiledMarkupImports(core.Model, core.Msg, \"app.native\", &app_markup_sources)") != null);
     try std.testing.expect(std.mem.indexOf(u8, desktop, ".view = CompiledAppView.build") != null);
 
     const mobile = @embedFile("src/app_runner/ts_core_mobile.zig");
     try std.testing.expect(std.mem.indexOf(u8, mobile, "pub const features: native_sdk.UiAppFeatures = .{ .runtime_markup = false }") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, "TsUiAppWithFeatures(core, features)") != null);
+    try std.testing.expect(std.mem.indexOf(u8, mobile, "const app_markup_root = @import(\"app_markup_root\")") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, "CompiledMarkupImports(core.Model, core.Msg, \"app.native\", &app_markup_sources)") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, ".view = CompiledAppView.build") != null);
     try std.testing.expect(std.mem.indexOf(u8, mobile, ".markup =") == null);
 }
 
+test "Debug TypeScript root markup stays outside the staged app module" {
+    const source = @embedFile("build/app.zig");
+    try std.testing.expect(std.mem.indexOf(
+        u8,
+        source,
+        "_ = staged.addCopyFile(b.path(appPath(b, app_root, \"src/app.native\")), \"app.native\");",
+    ) == null);
+    try std.testing.expect(std.mem.indexOf(
+        u8,
+        source,
+        "_ = release_markup.addCopyFile(b.path(appPath(b, app_root, \"src/app.native\")), \"app.native\");",
+    ) != null);
+    try std.testing.expect(std.mem.indexOf(u8, source, "if (optimize != .Debug)") != null);
+}
+
+test "native check preserves the app markup root for component files" {
+    const source = @embedFile("tools/native-sdk/main.zig");
+    try std.testing.expect(std.mem.indexOf(
+        u8,
+        source,
+        "checkFiles(allocator, io, markup_files.items, .{ .import_root = \"src\" })",
+    ) != null);
+}
+
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const host_target = b.graph.host;
diff --git a/build/app.zig b/build/app.zig
index bb55b8c64..ee1fad910 100644
--- a/build/app.zig
+++ b/build/app.zig
@@ -483,6 +483,10 @@ const TsCoreStage = struct {
     /// mirror/registry files): the embed static library's `app`
     /// module roots here on iOS/Android targets.
     mobile_root: std.Build.LazyPath,
+    /// Release/mobile-only module embedding src/app.native. It lives in a
+    /// separate generated directory so a Debug app-code module never gains
+    /// the root markup as a transitive file input; Debug links markup_c.
+    app_markup_root: std.Build.LazyPath,
     /// The compiled-core archive: the app module links it (with libc,
     /// for the toolchain's runtime) beside the staged mirror.
     archive: std.Build.LazyPath,
@@ -1310,12 +1314,12 @@ fn tsCoreStage(
         \\
     , .{ service_carrier, service_pool_workers }));
     _ = staged.addCopyFile(migrations_zig, "migrations.zig");
-    // Release desktop and mobile compile the complete root markup closure at
-    // comptime, so stage the root and every non-window import beside the
-    // generated runner. Debug desktop still reads the root through the small
-    // linked C data object below, preserving link-only rebuilds for ordinary
-    // edits while using these staged imports for the runtime resolver.
-    _ = staged.addCopyFile(b.path(appPath(b, app_root, "src/app.native")), "app.native");
+    // Every imported file is an input to Debug's embedded source resolver and
+    // the release/mobile compiled view, so stage those beside the runner.
+    // Keep the ROOT out of this directory: changing any file in one WriteFiles
+    // output changes its directory identity, and the runner lives here. Root
+    // markup gets a separate release-only module below; Debug keeps the small
+    // linked C data object, preserving its link-only edit path.
     for (app_markup_sources.files) |source| {
         _ = staged.addCopyFile(b.path(appPath(b, app_root, source.source_path)), source.staged_path);
     }
@@ -1338,9 +1342,17 @@ fn tsCoreStage(
     // registry, same carrier constant — only the shell differs (the embed
     // host's AppDef contract instead of a process `main`).
     const mobile_root = staged.addCopyFile(dep.path("src/app_runner/ts_core_mobile.zig"), "mobile.zig");
+    const release_markup = b.addWriteFiles();
+    _ = release_markup.addCopyFile(b.path(appPath(b, app_root, "src/app.native")), "app.native");
+    const app_markup_root = release_markup.add("app_markup_root.zig",
+        \\//! Generated release/mobile embedding for the TypeScript root view.
+        \\pub const source = @embedFile("app.native");
+        \\
+    );
     return .{
         .main_root = main_root,
         .mobile_root = mobile_root,
+        .app_markup_root = app_markup_root,
         .archive = archive,
         .service_exe = service_exe,
         .service_archive = service_archive,
@@ -1579,6 +1591,8 @@ pub const MobileLibOptions = struct {
 pub const MobileTsCore = struct {
     /// The staged mobile wiring (mobile.zig beside the generated mirror).
     main_root: std.Build.LazyPath,
+    /// Separate root-markup module consumed by the compiled mobile view.
+    app_markup_root: std.Build.LazyPath,
     /// The compiled-core archive; merged into the embed library.
     archive: std.Build.LazyPath,
     /// The in-process service archive, when src/services exists.
@@ -1647,6 +1661,11 @@ fn addMobileLibWithTarget(b: *std.Build, dep: *std.Build.Dependency, target: std
                 .optimize = optimize,
             });
             mod.addImport("app_manifest_zon", ts.manifest_mod);
+            mod.addImport("app_markup_root", b.createModule(.{
+                .root_source_file = ts.app_markup_root,
+                .target = target,
+                .optimize = optimize,
+            }));
             break :ts_app mod;
         } else localModule(b, target, optimize, options.main);
         app_mod.addImport("native_sdk", native_sdk_mod);
@@ -1836,6 +1855,7 @@ pub fn addAppArtifacts(b: *std.Build, dep: *std.Build.Dependency, app_options: A
             .max_image_pixel_bytes = app_config.max_image_pixel_bytes,
             .ts_core = if (ts_stage) |stage| .{
                 .main_root = stage.mobile_root,
+                .app_markup_root = stage.app_markup_root,
                 .archive = stage.archive,
                 .service_archive = stage.service_archive,
                 .manifest_mod = appManifestModule(b, app_options.app_root, manifest_name),
@@ -2184,6 +2204,17 @@ fn appModule(b: *std.Build, dep: *std.Build.Dependency, target: std.Build.Resolv
         // toolchain's runtime needs libc.
         app_mod.link_libc = true;
         app_mod.addObjectFile(stage.archive);
+        // Debug reads src/app.native only through the separately linked C
+        // data object. Supplying this generated module in Debug would put
+        // the authored root back into the app-code dependency graph even
+        // though the runner's comptime branch never imports it.
+        if (optimize != .Debug) {
+            app_mod.addImport("app_markup_root", b.createModule(.{
+                .root_source_file = stage.app_markup_root,
+                .target = target,
+                .optimize = optimize,
+            }));
+        }
         // The in-process service archive links beside it (distinct symbol
         // prefix; its runtime internals are localized).
         if (stage.service_archive) |service_archive| app_mod.addObjectFile(service_archive);
diff --git a/src/app_runner/ts_core_main.zig b/src/app_runner/ts_core_main.zig
index 9c2dd3426..9f3593f06 100644
--- a/src/app_runner/ts_core_main.zig
+++ b/src/app_runner/ts_core_main.zig
@@ -95,8 +95,9 @@ pub fn appMarkup() []const u8 {
 // Debug keeps root markup in the separately linked data object above, so an
 // edit is a C-data compile + relink and the runtime interpreter owns imports.
 // Release embeds the same closure and compiles it to direct view code.
-const app_markup_sources = [_]native_sdk.canvas.ui_markup.SourceFile{
-    .{ .path = "app.native", .source = @embedFile("app.native") },
+const app_markup_root = if (dev) void else @import("app_markup_root");
+const app_markup_sources = if (dev) void else [_]native_sdk.canvas.ui_markup.SourceFile{
+    .{ .path = "app.native", .source = app_markup_root.source },
 } ++ app_sources.sources;
 const CompiledAppView = if (dev)
     void
diff --git a/src/app_runner/ts_core_mobile.zig b/src/app_runner/ts_core_mobile.zig
index a3d5b1484..cebf6ddc3 100644
--- a/src/app_runner/ts_core_mobile.zig
+++ b/src/app_runner/ts_core_mobile.zig
@@ -40,6 +40,7 @@ pub const core = @import("core.zig");
 const services = @import("services.zig");
 const service_carrier = @import("service_carrier.zig");
 const app_sources = @import("app_sources.zig");
+const app_markup_root = @import("app_markup_root");
 
 /// Shared with the embed host: its UiApp type must use the same feature set
 /// as this module's TypeScript adapter or their Options types are distinct.
@@ -51,9 +52,8 @@ const Adapter = native_sdk.TsUiAppWithFeatures(core, features);
 pub const Model = core.Model;
 pub const Msg = core.Msg;
 
-pub const app_markup = @embedFile("app.native");
 const app_markup_sources = [_]native_sdk.canvas.ui_markup.SourceFile{
-    .{ .path = "app.native", .source = app_markup },
+    .{ .path = "app.native", .source = app_markup_root.source },
 } ++ app_sources.sources;
 const CompiledAppView = native_sdk.canvas.CompiledMarkupImports(core.Model, core.Msg, "app.native", &app_markup_sources);
 
diff --git a/src/primitives/canvas/ui_markup.zig b/src/primitives/canvas/ui_markup.zig
index 7d0e3547e..69dd05631 100644
--- a/src/primitives/canvas/ui_markup.zig
+++ b/src/primitives/canvas/ui_markup.zig
@@ -3899,10 +3899,27 @@ pub fn resolveImports(
     root_source: []const u8,
     loader: ImportLoader,
     diagnostic: *MarkupErrorInfo,
+) ResolveError!MarkupDocument {
+    return resolveImportsFromRoot(arena, dirnamePath(root_name), root_name, root_source, loader, diagnostic);
+}
+
+/// Resolve an import closure against an explicit markup root. App-wide
+/// tooling uses this form while checking component files independently:
+/// every file under `src/` keeps the app root, so a component may import a
+/// sibling directory exactly as it does when reached from `src/app.native`.
+/// Direct `native markup check <file>` continues through `resolveImports`
+/// above, where the checked file's own directory is the root.
+pub fn resolveImportsFromRoot(
+    arena: std.mem.Allocator,
+    root_dir: []const u8,
+    root_name: []const u8,
+    root_source: []const u8,
+    loader: ImportLoader,
+    diagnostic: *MarkupErrorInfo,
 ) ResolveError!MarkupDocument {
     var resolver = ImportResolver{
         .arena = arena,
-        .root_dir = dirnamePath(root_name),
+        .root_dir = root_dir,
         .loader = loader,
         .diagnostic = diagnostic,
     };
diff --git a/src/primitives/canvas/ui_markup_tests.zig b/src/primitives/canvas/ui_markup_tests.zig
index d7e5999bb..390118e83 100644
--- a/src/primitives/canvas/ui_markup_tests.zig
+++ b/src/primitives/canvas/ui_markup_tests.zig
@@ -1450,6 +1450,43 @@ test "an absolute root path resolves imports the same as a relative one" {
     try testing.expectEqualStrings(markup.import_src_escape_message, escaped.message);
 }
 
+test "an explicit app root lets an independently checked component import a sibling directory" {
+    var arena_state = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+
+    const set = [_]markup.SourceFile{
+        .{
+            .path = "src/components/card.native",
+            .source = "<import src=\"../shared/base.native\"/>\n<template name=\"card\"><use template=\"base\" /></template>",
+        },
+        .{
+            .path = "src/shared/base.native",
+            .source = "<template name=\"base\"><text>shared</text></template>",
+        },
+    };
+    var loader = markup.SourceSetLoader{ .set = &set };
+    var diagnostic: markup.MarkupErrorInfo = .{};
+    const document = try markup.resolveImportsFromRoot(
+        arena,
+        "src",
+        set[0].path,
+        set[0].source,
+        loader.loader(),
+        &diagnostic,
+    );
+    try testing.expectEqual(@as(usize, 2), document.templates.len);
+    try testing.expectEqualStrings("base", document.templates[0].attr("name").?);
+    try testing.expectEqualStrings("card", document.templates[1].attr("name").?);
+
+    // The direct-file resolver deliberately retains its narrower boundary.
+    try testing.expectError(
+        error.MarkupImport,
+        markup.resolveImports(arena, set[0].path, set[0].source, loader.loader(), &diagnostic),
+    );
+    try testing.expectEqualStrings(markup.import_src_escape_message, diagnostic.message);
+}
+
 test ".native is the one markup extension" {
     try testing.expect(markup.hasMarkupExtension("view.native"));
     try testing.expect(!markup.hasMarkupExtension("view.html"));
diff --git a/tools/native-sdk/main.zig b/tools/native-sdk/main.zig
index b74a80c63..7d611d818 100644
--- a/tools/native-sdk/main.zig
+++ b/tools/native-sdk/main.zig
@@ -715,7 +715,7 @@ fn runCheck(allocator: std.mem.Allocator, io: std.Io, env_map: *std.process.Envi
     try collectMarkupFiles(allocator, io, "src", &markup_files);
     var outcome = markup_cli.CheckOutcome{};
     if (markup_files.items.len > 0) {
-        outcome = try markup_cli.checkFiles(allocator, io, markup_files.items);
+        outcome = try markup_cli.checkFiles(allocator, io, markup_files.items, .{ .import_root = "src" });
         if (outcome.failures > 0) return error.MarkupCheckFailed;
     }
 
diff --git a/tools/native-sdk/markup.zig b/tools/native-sdk/markup.zig
index 7404094a1..e4d60a754 100644
--- a/tools/native-sdk/markup.zig
+++ b/tools/native-sdk/markup.zig
@@ -36,7 +36,7 @@ pub fn run(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !
         return error.MarkupCommandFailed;
     }
 
-    const outcome = try checkFiles(allocator, io, files.items);
+    const outcome = try checkFiles(allocator, io, files.items, .{});
     // Exit directly: the diagnostics above are the whole story, and a
     // returned error would bury them under the CLI's own return trace.
     if (outcome.failures > 0) std.process.exit(1);
@@ -55,13 +55,21 @@ pub const CheckOutcome = struct {
     contract_checked: bool = false,
 };
 
+pub const CheckOptions = struct {
+    /// Shared import boundary for every checked file. `native check` sets
+    /// this to `src`, matching the generated app resolver; the standalone
+    /// markup command leaves it null so each explicitly named file remains
+    /// rooted at its own directory.
+    import_root: ?[]const u8 = null,
+};
+
 /// The `check` body shared by `native markup check` and `native check`:
 /// structural validation of every file, plus — when the working directory
 /// is an app with a FRESH model-contract artifact — the model-aware
 /// contract pass and the dead-state lint. A missing, stale, or unreadable
 /// artifact degrades to structural checking with a note, never a false
 /// pass.
-pub fn checkFiles(allocator: std.mem.Allocator, io: std.Io, files: []const []const u8) !CheckOutcome {
+pub fn checkFiles(allocator: std.mem.Allocator, io: std.Io, files: []const []const u8, options: CheckOptions) !CheckOutcome {
     var arena_state = std.heap.ArenaAllocator.init(allocator);
     defer arena_state.deinit();
     const arena = arena_state.allocator();
@@ -104,6 +112,7 @@ pub fn checkFiles(allocator: std.mem.Allocator, io: std.Io, files: []const []con
             .contract = if (contract_value) |*parsed| parsed else null,
             .usage = if (usage_state) |*live_usage| live_usage else null,
             .arena = arena,
+            .import_root = options.import_root,
         }) catch {
             outcome.failures += 1;
             printOrphanHint(arena, io, file_path, &embedded_basenames);
@@ -194,6 +203,41 @@ test "orphanNote: Zig track hints only for unembedded files" {
     try std.testing.expect(std.mem.indexOf(u8, note, "@embedFile") != null);
 }
 
+test "app-wide checking preserves src as the component import root" {
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const io = std.testing.io;
+    try tmp.dir.createDirPath(io, "src/components");
+    try tmp.dir.createDirPath(io, "src/shared");
+    try tmp.dir.writeFile(io, .{
+        .sub_path = "src/components/card.native",
+        .data =
+        \\<import src="../shared/base.native"/>
+        \\<template name="card"><column><use template="base" /></column></template>
+        ,
+    });
+    try tmp.dir.writeFile(io, .{
+        .sub_path = "src/shared/base.native",
+        .data = "<template name=\"base\"><text>shared</text></template>\n",
+    });
+
+    var root_buffer: [256]u8 = undefined;
+    const root = try std.fmt.bufPrint(&root_buffer, ".zig-cache/tmp/{s}/src", .{tmp.sub_path[0..]});
+    var path_buffer: [320]u8 = undefined;
+    const component_path = try std.fmt.bufPrint(&path_buffer, "{s}/components/card.native", .{root});
+    const checked = try checkFile(std.testing.allocator, io, component_path, .{
+        .arena = std.testing.allocator,
+        .import_root = root,
+    });
+    try std.testing.expect(!checked.had_view);
+
+    // An explicitly named standalone component keeps its own directory as
+    // the root; reaching a sibling remains an escape in that narrower mode.
+    try std.testing.expectError(error.MarkupImport, checkFile(std.testing.allocator, io, component_path, .{
+        .arena = std.testing.allocator,
+    }));
+}
+
 /// The basename of every `@embedFile("...")` argument across the .zig
 /// sources under src/, each file read once.
 fn collectEmbeddedBasenames(arena: std.mem.Allocator, io: std.Io) ![]const []const u8 {
@@ -339,6 +383,7 @@ const FileCheckContext = struct {
     /// Session arena for contract-check messages, which outlive the
     /// per-file arena (the dead-state summary prints after all files).
     arena: std.mem.Allocator,
+    import_root: ?[]const u8 = null,
 };
 
 const FileCheckResult = struct {
@@ -356,14 +401,16 @@ fn checkFile(allocator: std.mem.Allocator, io: std.Io, file_path: []const u8, co
     var arena_state = std.heap.ArenaAllocator.init(allocator);
     defer arena_state.deinit();
 
-    // Resolve the import closure from disk, rooted at the checked file's
-    // directory (the markup root): checking a view checks its imports, and
-    // a broken import reports at the importing file's position. A file
-    // that is all templates (no view root) is a valid component file —
-    // it checks standalone and as an import target.
+    // Resolve the import closure from disk. Standalone checks root at the
+    // checked file's directory; app-wide `native check` supplies the app's
+    // shared `src/` root so independently checked component files preserve
+    // the same sibling-import boundary as src/app.native.
     var disk_loader = DiskLoader{ .io = io };
     var diagnostic: ui_markup.MarkupErrorInfo = .{};
-    const document = ui_markup.resolveImports(arena_state.allocator(), file_path, source, disk_loader.loader(), &diagnostic) catch |err| {
+    const document = (if (context.import_root) |root|
+        ui_markup.resolveImportsFromRoot(arena_state.allocator(), root, file_path, source, disk_loader.loader(), &diagnostic)
+    else
+        ui_markup.resolveImports(arena_state.allocator(), file_path, source, disk_loader.loader(), &diagnostic)) catch |err| {
         const path = if (diagnostic.path.len > 0) diagnostic.path else file_path;
         std.debug.print("{s}:{d}:{d}: error: {s}\n", .{ path, diagnostic.line, diagnostic.column, diagnostic.message });
         printStaleBinaryHint(diagnostic.message);