# Theme Switchboard overview

## Audience and promise

Switchboard is for teams selling CLI products, developer tools, technical references, recipe libraries, and public changelogs. Its defining mechanic is a command bar that replaces conventional header navigation while retaining ordinary links for mouse, touch, assistive-technology, and no-JavaScript use.

Marketplace summary:

> Your whole site behind Cmd+K — a permanent command bar as the header, man-page heroes, and an index-card home for mouse users.

## Runtime architecture

`SwitchboardHeader` asks `BuildSwitchboardChromeDataAction` for a view model. The Action reads the prepared `NavigationRenderData` stored by `NavigationFrontendRuntimeManifestContributor`; it never queries navigation models. A layout navigation payload is accepted only as the layout-native demo/legacy fallback, and the visible result list, hidden index template, no-JavaScript index, and go-shortcuts are all projected from that one resolved collection.

When Search is available, `SearchAvailability` resolves `capell-frontend.search` for the GET form and `capell-frontend.search.autocomplete` for live JSON results. Without both named routes, Switchboard renders no decoy query form or endpoint attribute.

The package-local module is registered through Theme Foundation's active-theme frontend-script contract. It has no dependencies and no per-request data. The three storage keys are fixed and guarded.

## Content and widgets

Switchboard registers ten package-owned widget types:

- command-board feature
- index-card grid
- keycap legend
- man-page hero
- command reference table
- changelog ticker
- query recipes
- status strip
- prompt CTA
- transcript FAQ

One dispatcher resolves each enum-backed key to its package view. Standard hero, listing, and CTA content can also opt into the `man-page`, `ledger`, and `prompt` sidecars.

Demo content stores portable paragraph copy in Page content and keeps presentation structure in Layout Builder widgets and package Blade views.

## Optional integrations

- Search adds a real GET form and live Content group.
- Bookings becomes the first Contact action when its public request route is available.
- Form Builder becomes the second Contact path when a form handle is supplied.
- The final Contact fallback is a styled `mailto:` link.
- Newsletter adds a real subscribe form only when its CSRF-exempt named public endpoint is available.
- Blog can contribute already-prepared article rows through the package-owned public index-provider boundary. No Blog model or class is imported by public views.
- Comments and Widget Countdown are declared supported extension points; missing packages do not change core rendering.

## Cache and authoring safety

Public views contain no database calls, lazy relationship access, model identifiers, permissions, authoring selectors, signed editor URLs, or inline scripts. Trail chips are generated from guarded `sessionStorage` after load and never enter cached HTML.

## Verification

Run the package test directory, then the repository preflight. The CSS budget test enforces one stylesheet and a 2,100-line hard cap. The frontend build check enforces the committed Vite-style manifest and hashed module.