Menu
Build app shells with AST-driven OOB updates for sidebar, breadcrumbs, and title. Use when building Chirp + ChirpUI apps with HTMX navigation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | chirp-app-shell-oob |
| description | Build app shells with AST-driven OOB updates for sidebar, breadcrumbs, and title. Use when building Chirp + ChirpUI apps with HTMX navigation. |
Pattern for building HTMX-navigable apps where sidebar active state, breadcrumbs, and document title update automatically on boosted navigation — driven by Kida's AST metadata, not hard-coded logic.
breadcrumbs_oob, sidebar_oob, title_oob) alongside the full app shellcurrent_path, page_title, and breadcrumb_items in their contexttemplate_metadata() to discover OOB regions at build timehx-boost), Chirp renders the page fragment AND the OOB regions as hx-swap-oob updatesKida's {% region %} construct compiles to BOTH a block (for render_block) AND a callable (for {{ name(args) }}). Use regions instead of separate blocks + defs:
render_block(){% region sidebar_oob(current_path="/") %}...{% end %}{{ sidebar_oob(current_path=current_path | default("/")) }} in app shell slotsrender_block("sidebar_oob", current_path=...) for OOB updates{# target: body #}
<!DOCTYPE html>
<html lang="en">
<head>
<!-- ... head content ... -->
<title id="chirpui-document-title">{{ page_title | default("My App") }}</title>
</head>
<body>
{% from "chirpui/app_shell.html" import app_shell %}
{% from "chirpui/sidebar.html" import sidebar, sidebar_section, sidebar_link %}
{% from "chirpui/breadcrumbs.html" import breadcrumbs %}
{% from "chirpui/theme_toggle.html" import theme_toggle %}
{# Regions: one definition for both app shell slots AND OOB render_block #}
{% region breadcrumbs_oob(breadcrumb_items=[{"label":"Home","href":"/"}]) %}
{{ breadcrumbs(breadcrumb_items) }}
{% end %}
{% region title_oob(page_title="My App") %}
<title id="chirpui-document-title" hx-swap-oob="true">{{ page_title }}</title>
{% end %}
{% region sidebar_oob(current_path="/") %}
{% call sidebar() %}
{% call sidebar_section("Pages") %}
{{ sidebar_link("/", "Home", icon="home", active=current_path == "/") }}
{{ sidebar_link("/settings", "Settings", icon="settings", active=current_path.startswith("/settings")) }}
{% end %}
{% end %}
{% end %}
{% call app_shell(brand="My App", sidebar_collapsible=true) %}
{% slot topbar %}
{{ breadcrumbs_oob(breadcrumb_items=breadcrumb_items | default([{"label":"Home","href":"/"}])) }}
{% end %}
{% slot topbar_end %}
{{ theme_toggle() }}
{% end %}
{% slot sidebar %}
{{ sidebar_oob(current_path=current_path | default("/")) }}
{% end %}
{% block content %}{% end %}
{% end %}
</body>
</html>
{# target: body #}?The target annotation tells Chirp where HTMX should swap content. With body, the entire <body> is the swap target for full page loads, and the OOB regions update specific DOM areas during fragment navigation. Using main would skip OOB region rendering entirely.
{# outlet: main #} with app_shell_layoutIf the root layout {% extends "chirpui/app_shell_layout.html" %} (filesystem mount_pages), add {# outlet: main #} below {# target: body #}. Chirp’s LayoutChain matches outlet so HX-Target: #main resolves to this layout and render_with_layouts returns full shell HTML including #page-content (required for hx-select on boosted nav). Without outlet, boosted responses can be bare page HTML and shell swaps break silently.
Every handler must provide three context keys for OOB updates to work:
from chirp import Request
from chirp.templating.composition import PageComposition
def get(request: Request) -> PageComposition:
return PageComposition(
template="settings/page.html",
context={
"current_path": request.path,
"page_title": "Settings",
"breadcrumb_items": [
{"label": "Home", "href": "/"},
{"label": "Settings"},
],
# ... page-specific context ...
},
)
With ChirpUI, fragment_block and page_block are optional — the FragmentTargetRegistry resolves from HX-Target (#main, #page-root, #page-content-inner).
| Key | Purpose | Used by |
|---|---|---|
current_path | Sidebar active state detection | sidebar_oob block |
page_title | Document <title> update | title_oob block |
breadcrumb_items | Breadcrumb trail | breadcrumbs_oob block |
For dynamic pages, use the entity name:
def get(request: Request, skill: Skill) -> PageComposition:
return PageComposition(
template="skill/{name}/page.html",
context={
"current_path": request.path,
"page_title": skill.name,
"breadcrumb_items": [
{"label": "Home", "href": "/"},
{"label": "Skills", "href": "/skills"},
{"label": skill.name},
],
},
)
Page templates define two nested blocks and must render id="page-root" on a wrapper element. app_shell_layout sets hx-select="#page-content" on #main, and custom app_shell layouts should wrap routed content with shell_outlet() to create the same #page-content boundary. page_root remains the broader page-level fragment target inside that shell outlet. A block named page_root does not create the id by itself — HTMX #page-root swaps would match nothing.
{% block page_root %}
<div id="page-root">
{% block page_content %}
<div style="padding: 2rem;">
<h1>Settings</h1>
<p>Page content here.</p>
</div>
{% end %}
</div>
{% end %}
page_root — outer block for full page composition and sidebar nav (hx-target="#main")page_root_inner — inner block for tab clicks (hx-target="#page-root")page_content — narrow block for content-only swaps (hx-target="#page-content-inner")ChirpUI registers these via use_chirp_ui(). main and page-root have triggers_shell_update=True so shell_actions (topbar, breadcrumbs, title) update on sidebar and tab clicks; page-content-inner has triggers_shell_update=False so narrow swaps don't update the shell. Custom targets: app.register_fragment_target("id", fragment_block="...", triggers_shell_update=True).
Use _context.py files for section-level shared context:
# pages/settings/_context.py
def context() -> dict:
return {
"page_title": "Settings",
"breadcrumb_items": [
{"label": "Home", "href": "/"},
{"label": "Settings"},
],
}
Child pages override by providing the same keys in their handler context.
Chirp does not hard-code which blocks to render as OOB. Instead, it uses Kida's template_metadata():
build_layout_contract() calls template_metadata() on the root layout*_oob are identified as OOB candidatescache_scope and depends_on metadata (from Kida's AST) determines rendering behavior:
cache_scope: "site" → skip (static, doesn't change per page)depends_on: {"page_title"} → skip if page_title not in contextLayoutContract is cached per template for efficiencyThis means adding new OOB regions requires only:
{% region new_region_oob(params) %}...{% end %} to the layout_OOB_TARGET_MAP{# target: body #} (not main)app_shell_layout via mount_pages: also {# outlet: main #} for boosted #main / #page-content{% region name_oob(params) %}...{% end %} for OOB regions (zero duplication){{ name_oob(param=value | default(...)) }}{% from %} imports are at template top level (compile-time, works everywhere)current_path, page_title, breadcrumb_itemspage_root / page_content two-block patterncurrent_path) are used directly in the region body