@sylwellsoftware/fray 0.6.0 → 1.0.0

package/README.md

@@ -27,10 +27,12 @@ Presentation should be equally direct. Native HTML already defines buttons,
 inputs, tables, lists, progress, dialogs, and landmarks, so Fray uses those
 elements when their semantics match. Components that need another boundary use
 readable light-DOM host names rather than framework identity classes.
-Application classes remain available for meaningful reusable traits and
-consumer styling, while Fray's current structural implementation uses explicit
-host and part metadata for its own layout and documented exceptional theme
-rules.
+Within a component host, Fray uses classes for owned parts, purely visual
+states with no semantic equivalent, and meaningful reusable traits; those
+classes do not identify components. Native and ARIA state attributes remain the
+sole semantic state source and are targeted directly by CSS. Renderer markers,
+diagnostics, interoperability, and actual data use `data-*`; Fray does not use
+`data-*` as its routine component-CSS hook.
 
 ## Design model
 
@@ -85,21 +87,24 @@ Responsibility stays at the narrowest layer that understands it:
 | Domain state, service implementations/providers, endpoint configuration, page composition, theme availability and selection policy | Application |
 | DOM structure, native events, accessibility, component lifetime, service-scope propagation, visual async states | Fray components/runtime |
 | Mutable/computed values, query timing/results, fetch state, optional causality | Glue |
-| URL/wire serialization and retrieval mechanism | Injected Glue query handler/application adapter |
+| Remote wire serialization and retrieval mechanism | Injected Glue query handler/application adapter |
+| Browser navigation placement, restoration, and routed component integration | Caller-owned Fray router with an injected navigation adapter |
 | Layout/flow CSS and stable component/part hooks | Fray structural styling |
 | Look-and-feel treatment and palette | Separately loaded Fray-compatible theme/color CSS |
 
 ## Set up a browser application
 
-Fray ships ESM, TypeScript declarations, automatic/classic JSX runtimes, one
-generated structural stylesheet, replaceable theme treatments, and replaceable
-color palettes. Glue is a peer dependency.
+Fray ships ESM, TypeScript declarations, automatic/classic JSX runtimes,
+variable defaults, replaceable theme treatments, and replaceable color
+palettes. Glue is a peer dependency. Applications collect structural CSS from
+the component classes they actually declare.
 
 ```ts
 import {Emitter} from '@sylwellsoftware/glue'
 import {
     Button,
     Component,
+    Header,
     Panel,
     Sidebar,
     Textbox,
@@ -107,7 +112,7 @@ import {
     createFrayRuntime,
     h,
 } from '@sylwellsoftware/fray'
-import '@sylwellsoftware/fray/styles/structural.css'
+import '@sylwellsoftware/fray/themes/base.css'
 import '@sylwellsoftware/fray/colors/iceblue/colors.css'
 import '@sylwellsoftware/fray/themes/minimal/theme.css'
 
@@ -117,7 +122,10 @@ class App extends Component {
     static dependencies = [Button, Panel, Textbox, Toolbar]
 
     render() {
-        return h(Panel, {header: 'Profile'},
+        return h(Panel, {
+            className: 'fray-fill-horizontal fray-fill-vertical',
+            header: 'Profile',
+        },
             h(Textbox, {label: 'Name', valueEmitter: name}),
             h(Toolbar, {label: 'Profile actions'},
                 h(Button, {label: 'Save', onClick: () => save(name.get())})))
@@ -125,6 +133,7 @@ class App extends Component {
 }
 
 const runtime = createFrayRuntime()
+runtime.registerStyles(App).injectStyles(document)
 runtime.mount(runtime.create(App), document.querySelector('#app')!)
 
 function save(value: string) {
@@ -132,6 +141,14 @@ function save(value: string) {
 }
 ```
 
+Root sizing is application-owned. Add `fray-fill-horizontal` to a rendered
+application root to claim exactly `100vw`, `fray-fill-vertical` to claim
+exactly `100vh`, or both for a fullscreen application. Each axis supplies its
+own root overflow fallback and zero minimum; descendant islands are bounded
+and scroll on only the opted-in axes. Other components retain their intrinsic
+minimums and their own structural overflow contracts. A root with neither
+modifier keeps its ordinary embedded/content-sized behavior.
+
 The prebuilt structural file targets Fray's default `fray-` hosts. Applications
 with custom components or configured host names may instead register their root
 dependencies and call `runtime.injectStyles(document)`; collection remains
@@ -214,6 +231,164 @@ query state comes from caller-owned endpoint results. Function components stay
 presentation-oriented and receive rendered values or emitters from a nearby
 lifecycle-owning class component.
 
+## Hierarchical browser routing
+
+Routing is optional and application-scoped. Route descriptors name immutable
+relative segments; the mounted component hierarchy supplies their parentage.
+This lets a `TabPanel` discover immediate routes from ordinary `Tab`
+annotations without requiring a duplicate central route tree:
+
+```tsx
+import {Emitter} from '@sylwellsoftware/glue'
+import {
+    Component,
+    RouteLink,
+    RouteQuery,
+    RouteUnavailableError,
+    RouteValue,
+    Tab,
+    TabPanel,
+    createBrowserRouter,
+    createHashNavigation,
+    createFrayRuntime,
+    defineRoute,
+    defineRouteParameter,
+    routeTarget,
+    stringRouteCodec,
+    waitForRouteValue,
+} from '@sylwellsoftware/fray'
+
+const routes = {
+    changes: defineRoute('changes'),
+    security: defineRoute('security'),
+    overview: defineRoute('security-overview', 'overview'),
+    projects: defineRoute('security-projects', 'projects'),
+}
+const activeApplication = new Emitter('changes')
+const activeSecurityView = new Emitter('overview')
+
+class SecurityApplication extends Component {
+    render() {
+        return <TabPanel valueEmitter={activeSecurityView} label="Security views">
+            <Tab id="overview" label="Overview" route={routes.overview}>Summary</Tab>
+            <Tab id="projects" label="Projects" route={routes.projects}>Projects</Tab>
+        </TabPanel>
+    }
+
+    static dependencies = [Tab, TabPanel]
+}
+
+class App extends Component {
+    render() {
+        return <>
+            <nav aria-label="Applications">
+                <RouteLink to={routeTarget(routes.security, routes.projects)}>
+                    Security projects
+                </RouteLink>
+            </nav>
+            <TabPanel valueEmitter={activeApplication} label="Applications">
+                <Tab id="changes" label="Changes" route={routes.changes}>Changes</Tab>
+                <Tab id="security" label="Security" route={routes.security}>
+                    <SecurityApplication />
+                </Tab>
+            </TabPanel>
+        </>
+    }
+
+    static dependencies = [RouteLink, SecurityApplication, Tab, TabPanel]
+}
+
+const router = createBrowserRouter({adapter: createHashNavigation(window)})
+const runtime = createFrayRuntime({router})
+const app = runtime.mount(runtime.create(App), document.querySelector('#app')!)
+
+addEventListener('pagehide', () => {
+    app.destroy()
+    router.dispose()
+}, {once: true})
+```
+
+The runtime opens the root scope. A selected routed tab opens its own scope for
+nested components, so `/security/projects` restores the outer tab first and
+then discovers and restores the inner tab. Every scope declares when its
+immediate registrations are complete; this distinguishes an unknown child
+from one whose parent has not mounted yet. Duplicate IDs or literal paths and
+multiple parameter routes in one scope fail at completion. Literal routes take
+precedence over the optional parameter route.
+
+`RouteLink` is a native anchor. A descriptor resolves against the current
+lineage, which is convenient for sibling destinations. A link outside the
+destination's mounted lineage uses `routeTarget(...)` with the full chain from
+the root. Modified clicks, downloads, and non-`_self` targets retain native
+browser behavior. `router.navigate(target)` pushes by default;
+`router.redirect(target)` and `navigate(target, {history: 'replace'})` replace.
+`router.href(target)`, `router.resolve(descriptor, context)`, and
+`router.isActive(target, exact)` support advanced composition.
+
+Dynamic path values use a typed codec and an application-owned nullable
+emitter:
+
+```tsx
+const projectRoute = defineRouteParameter('project', stringRouteCodec, 'project-id')
+const selectedProjectId = new Emitter<string | null>(null)
+
+<RouteValue
+    route={projectRoute}
+    valueEmitter={selectedProjectId}
+    resolve={async (projectId, _context, signal) => {
+        const projects = await waitForRouteValue(
+            projectResults,
+            (items) => items.length > 0,
+            signal,
+        )
+        if (!projects.some(({id}) => id === projectId)) {
+            throw new RouteUnavailableError(`Unknown project "${projectId}"`)
+        }
+        return projectId
+    }}
+>
+    <ProjectView />
+</RouteValue>
+```
+
+Resolvers run in path order, may normalize the decoded value, and receive the
+settled ancestor values plus an `AbortSignal`. A newer navigation or router
+disposal aborts outstanding work. `waitForRouteValue` is a convenience for a
+Glue readable; fetching, authorization, retries, and domain validation remain
+application-owned. Set `scopeChildren` on `RouteValue` only when further route
+levels live beneath the dynamic value. Leaving it off avoids remounting an
+otherwise stable leaf view when selection changes.
+
+Explicit query bindings make selected shareable view state routable without
+coupling the originating control to the router:
+
+```tsx
+<RouteQuery
+    name="range"
+    valueEmitter={historyRange}
+    codec={historyRangeCodec}
+    defaultValue="12m"
+>
+    <HistoryView />
+</RouteQuery>
+```
+
+Defaults are omitted, owned names sort deterministically, foreign query keys
+are preserved, and passive emitter changes replace the current URL. Invalid
+owned values reset to the default and produce a structured `router.issue`.
+Path failures similarly fall back to the deepest resolved parent and replace
+the failed entry. Applications observe `router.transition` for pending/idle
+state and render `router.issue` as localized, accessible feedback. An explicit
+navigation clears the issue.
+
+Choose `createHashNavigation(window)` for static hosting; it reserves the URL
+fragment. Choose `createHistoryNavigation(window, {basePath: '/app/'})` for
+ordinary paths; the deployment must serve the application entry point for
+direct requests below that base. `MemoryNavigationAdapter` supplies
+deterministic tests and does not imply server rendering. The application owns
+and disposes the router; destroying a runtime root removes mounted route
+registrations but does not dispose the caller-owned router.
+
 ## Component host elements
 
 Fray components with a wrapper render a standards-valid custom host element,
@@ -221,11 +396,11 @@ not a framework identity class. The default application runtime therefore
 produces DOM such as:
 
 ```html
-<fray-panel class="panellike" data-fray-component="panel">
-    <fray-textbox data-fray-component="textbox">
-        <input type="text">
+<fray-panel data-fray class="island" data-fray-component="panel">
+    <fray-textbox data-fray data-fray-component="textbox">
+        <input data-fray type="text">
     </fray-textbox>
-    <button data-fray-component="button">Save</button>
+    <button data-fray data-fray-component="button">Save</button>
 </fray-panel>
 ```
 
@@ -234,48 +409,38 @@ Native semantics remain native: `Button` renders `button`, `Toggle` renders
 `thead`/`th`. `Tab` is a declarative child consumed by `TabPanel` and has no
 independent root. The
 `data-fray-component` keeps diagnostics unambiguous. It is not a structural or
-theme selector. Fray may merge public presentation traits such as `panellike`
+theme selector. Fray may merge public presentation traits such as `island`
 with an application-supplied `class`/`className`; those traits describe a
 reusable capability, not component identity.
 
-Element naming is an immutable application-runtime setting:
-
-```ts
-const defaultNames = createFrayRuntime()
-// <fray-panel>, <fray-list-view>, ...
-
-const productNames = createFrayRuntime({
-    elementNames: {prefix: 'acme'},
-})
-// <acme-panel>, <acme-list-view>, ...
-
-const prefixlessNames = createFrayRuntime({
-    elementNames: {prefix: null},
-})
-// <layout-panel>, <list-view>, <text-box>, ...
-
-const selectedOverrides = createFrayRuntime({
-    elementNames: {
-        prefix: null,
-        overrides: {'panel': 'change-panel'},
-    },
-})
-// <change-panel>, with standalone names for the other components
-```
-
-HTML custom-element names must contain a hyphen, so prefixless mode uses each
-component's standards-valid standalone name rather than invalid names such as
-`<panel>` or `<listview>`. Prefixes and overrides must be lowercase kebab-case;
-an exact override must itself be a non-reserved custom-element name.
+Pass `island` to a fixed-host component when that surface should be visually
+separated from the page. Fray adds the reusable `island` class to its host;
+applications may use the same class on deliberate native surface boundaries.
+The component-owned rule consumes `--island-*` variables, so an island theme
+can add gutters, an edge, and elevation while a flat theme can leave the
+modifier visually neutral. Islands are one surface layer: nesting an `island`
+component below another island is rejected. Application-authored native island
+classes must follow the same no-nesting invariant. A surface island never
+creates a nested theme or palette scope.
+
+Built-in host names are fixed public DOM: Fray adds its one required custom
+element hyphen and removes internal word separators from the component stem.
+For example, `Panel`, `ListView`, and `ThemePicker` render as `<fray-panel>`,
+`<fray-listview>`, and `<fray-themepicker>`. They cannot be prefixed, renamed,
+or made prefix-free at runtime. This lets distributed stylesheets target hosts
+directly and predictably.
+
+Every element created by Fray's renderer also receives the boolean `data-fray`
+attribute. Themes can therefore target native Fray output without affecting
+other UI libraries: `button[data-fray]`, `input[data-fray]`, and
+`dialog[data-fray]`. The marker is renderer-owned and cannot be removed through
+component props. `data-fray-component` remains diagnostic metadata, not an
+ordinary styling selector.
 
-Each runtime owns its element-name mapping and structural-style registry.
 Create the runtime once at application startup, then create and mount the root
-through that runtime. Nested components inherit it automatically. A separate
-compiled Fray build is unnecessary. Two runtimes with different mappings can
-coexist in one document without their component-host selectors colliding.
-Styles still live in the document's global cascade because these hosts are
-deliberately unregistered light-DOM elements, not Web Components or Shadow DOM
-boundaries.
+through that runtime. Styles live in the document's global cascade because the
+hosts are deliberately unregistered light-DOM elements, not Web Components or
+Shadow DOM boundaries.
 
 ## Reactive templates
 
@@ -290,8 +455,8 @@ canonical vnode operation, but it is not the built-in component authoring
 format. The workspace lint gate rejects new `h()` templates under
 `packages/fray/src/Components`.
 
-Configured custom hosts are also available inside a TSX component through its
-protected `Host` template component:
+Custom hosts are available inside a TSX component through its protected `Host`
+template component:
 
 ```tsx
 interface BadgeProps extends ComponentProps {
@@ -307,12 +472,11 @@ class Badge extends Component<BadgeProps> {
     }
 
     static override hostName = 'badge'
-    static override standaloneHostName = 'ui-badge'
 }
 ```
 
-At runtime that template produces `<fray-badge>` by default,
-`<acme-badge>` under an `acme` prefix, or `<ui-badge>` in prefixless mode.
+At runtime that template produces `<fray-badge>`. `hostName` is a stable
+lowercase kebab-case component identity; Fray derives the fixed host spelling.
 Native-root components such as `Button` use their native tag directly in TSX
 instead of `Host`.
 
@@ -322,7 +486,7 @@ Glue values have explicit behavior at each template boundary:
 | --- | --- |
 | `{emitter}` | Render the current value and patch only that child range on emission. |
 | `<Child source={emitter} />` | Pass the emitter object unchanged; the child owns how it consumes it. |
-| `prop={live(emitter)}` | Subscribe a scalar DOM or component prop one way to the emitter's current value. |
+| `prop={live(emitter)}` | Subscribe a DOM property or a component-declared live prop one way to the emitter's current value. |
 | `<input bind:value={emitter} />` | Bind a writable string emitter and native `value` two ways. |
 | `<input bind:checked={emitter} />` | Bind a writable boolean emitter and native `checked` two ways. |
 | `this.read(emitter)` | Read during `render()` and rerender the component while that dependency is used. |
@@ -335,6 +499,16 @@ The component still owns and disposes emitters it creates. Direct rendering
 uses only an emitter's value; use `snapshot()` when loading and error state
 must affect the markup.
 
+Component props do not implicitly unwrap emitters. A raw emitter prop passes
+the emitter object to the component, while `live(emitter)` passes its current
+value and subscribes at the renderer boundary. Every class component has an
+explicit live-prop contract and rejects `live()` outside its allowlist in both
+typed templates and at runtime. `live()` is reserved for small render-time
+state such as availability, validation, and busy/pressed state. Identity,
+callbacks, initial values, structural collections, and emitter ownership are
+ordinary props. A data prop documented as accepting a readable emitter is a
+separate input-source contract, not a `live()` prop.
+
 This complete example uses mutable and derived emitters, direct emitter
 children, raw emitter props, native two-way bindings, a one-way live property,
 conditional tracked state, and a `LiveQuery` passed to a child:
@@ -460,7 +634,7 @@ class ChangeApp extends Component {
     static dependencies = [Button, Panel, Preview, Results, Textbox]
 }
 
-const runtime = createFrayRuntime({elementNames: {prefix: 'acme'}})
+const runtime = createFrayRuntime()
 runtime.registerStyles(ChangeApp).injectStyles(document)
 runtime.mount(runtime.create(ChangeApp), document.querySelector('#app')!)
 ```
@@ -531,8 +705,10 @@ or `defaultValue` in new code.
 
 ## Stable component reference
 
-All components also accept `children`, `className` (`class` is an alias), and a
-sibling-local `key` through the common component props.
+All components also accept `children`, `className` (`class` is an alias), an
+`island` surface modifier, and a sibling-local `key` through the common
+component props. The modifier is static presentation input, not a `live()`
+property.
 
 | Component | Important props | User callback | State/emitter behavior |
 | --- | --- | --- | --- |
@@ -540,20 +716,54 @@ sibling-local `key` through the common component props.
 | `Toolbar` | `label`, `orientation`, `id`, `children` | None | Stateless named toolbar; orientation is horizontal or vertical. |
 | `Textbox` | `label` or `ariaLabel`, value props, `disabled`, `required`, `readOnly`, `error`, native text constraints, `inputRef` | `onInput(value, event)`, `onChange(value, event)` | String `valueEmitter`; external emitter changes patch the native input without replacing it. |
 | `Dropdown<T>` | `options`, `label` or `ariaLabel`, value props, `disabled`, `required`, `error`, `placeholder`, `name` | `onChange(value, event)` | Typed string/number `valueEmitter`; `options` may be an array or readable emitter. |
-| `Toggle<T>` | `options`, `label` or `ariaLabel`, value props, `disabled`, `required` | `onChange(value, event)` | One selected value; arrow keys, Home, and End move and select within the radio group. |
-| `Checkbox<T>` | `symbols`, `label`, value props, `disabled`, `required`, `name` | `onChange(value, event)` | Two-state semantic value by default; click/Space advances and arrow keys move in either direction. |
+| `RadioButton` | `label`, `name`, `value`, `checked`, `disabled`, `required`, `error` | `onChange(checked, event)` | Native radio input with a labelled fixed shell; `checked`, `disabled`, `required`, and `error` support `live()`. |
+| `RadioGroup<T>` | Plain-array `options`, `label` or `ariaLabel`, value props, `name`, `disabled`, `required`, `error` | `onChange(value, event)` | Native radio inputs with one selected `valueEmitter`; `disabled`, `required`, and `error` support `live()`. |
+| `Toggle<T>` | `options`, `label` or `ariaLabel`, value props, `disabled`, `required`, `error` | `onChange(value, event)` | One selected value; `disabled`, `required`, and `error` support `live()`. |
+| `Checkbox<T>` | `symbols`, `label`, value props, `disabled`, `required`, `error`, `name` | `onChange(value, event)` | Two-state semantic value by default; `disabled`, `required`, and `error` support `live()`. |
 | `TriCheckbox` | Checkbox props except `symbols` | `onChange(value, event)` | Cycles deny → neutral → prefer using `FilterMode`. |
 | `QuadCheckbox` | Checkbox props except `symbols` | `onChange(value, event)` | Cycles deny → neutral → prefer → require using `FilterMode`. |
-| `Panel` | `header`, `toolbar`, `orientation`, `disabled`, `id`, `children` | None | Stateless labelled section when a header exists; `disabled` describes the region but does not mutate descendant controls. |
-| `Sidebar` | `header`, `toolbar`, `ariaLabel`, `id`, `children` | None | Native complementary region with fixed header/toolbar parts and independently scrolling content. |
-| `SplitView` | `primary`, `secondary`, `direction`, `primarySize`, pane labels | None | Stateless, non-resizable two-pane layout with explicit overflow ownership. |
+| `Header` | `id`, `headingId`, `level`, `children` | None | Styled heading surface using a native `h1`–`h6`; level defaults to `2`. |
+| `Panel` | `header`, `toolbar`, `orientation`, `disabled`, `id`, `children` | None | Stateless labelled section that composes Header when header content exists; `disabled` describes the region but does not mutate descendant controls. |
+| `Sidebar` | `header`, `toolbar`, `ariaLabel`, `id`, `children` | None | Fixed `fray-sidebar` host containing a native complementary region with fixed header/toolbar parts and independently scrolling content. |
+| `SplitView` | `primary`, `secondary`, `direction`, `primarySize`, pane labels | None | Stateless, non-resizable two-pane flex layout with explicit overflow ownership and keyboard-focusable panes; `primarySize` is a flex-basis value. |
 | `DescriptionList` / `DescriptionItem` | list `label`; item `term`, `value` or children | None | Native `dl`/`dt`/`dd` record summary with responsive term/value wrapping. |
-| `ProgressBar` | `label`, `value` or `valueEmitter`, `max`, `valueText` | None | Labelled native progress; a null value is indeterminate. |
+| `ProgressBar` | `label`, `value` or `valueEmitter`, `max`, `valueText` | None | Native progress semantics with a clipped-label visual surface; a null value is indeterminate. |
 | `ThemePicker` | `label` or `ariaLabel`, theme `options`, value props, `targetDocument`, `disabled` | `onChange(value, option, event)` | String `valueEmitter`; replaces only the theme stylesheet link. |
 | `ColorPicker` | `label` or `ariaLabel`, color `options`, value props, `targetDocument`, `disabled` | `onChange(value, option, event)` | String `valueEmitter`; replaces only the color stylesheet link. |
-| `Tab` | `id`, `label`, `disabled`, `children` | None | Declarative content marker consumed by `TabPanel`; not rendered as a tab by itself. |
+| `Tab` | `id`, `label`, `disabled`, optional literal `route`, `children` | None | Declarative content marker consumed by `TabPanel`; a route annotation binds tab activation to the current route scope. |
 | `TabLine` | `tabs`, `label`, `baseId`, value props | `onChange(id, event)` | Active-tab `valueEmitter`; arrow keys skip disabled tabs, with Home/End support. |
-| `TabPanel` | `tabs` or `Tab` children, `label`, `id`, value props | `onChange(id, event)` | Owns or consumes the active-tab emitter and wires the selected tab to its tabpanel. |
+| `TabPanel` | `tabs` or `Tab` children, `label`, `id`, value props | `onChange(id, event)` | Owns or consumes the active-tab emitter, wires the selected tabpanel, and contextually registers annotated tabs when a router is present. |
+
+### Live binding and data-source contracts
+
+Use `live()` only for the props listed here. All other component props reject
+`live()` in TSX, `h()`, and at runtime. Form-control errors render an alert,
+set invalid state, and associate the control or group with that message.
+
+| Component | `live()` props | Dedicated reactive input/state props |
+| --- | --- | --- |
+| `Button` | `disabled`, `pressed`, `busy` | None |
+| `Textbox` | `disabled`, `required`, `readOnly`, `error` | `valueEmitter` |
+| `Dropdown` | `disabled`, `required`, `error` | `options` may be an array or readable emitter; `valueEmitter` |
+| `RadioButton` | `checked`, `disabled`, `required`, `error` | None |
+| `RadioGroup` | `disabled`, `required`, `error` | `valueEmitter`; `options` is always an ordinary array |
+| `Toggle` | `disabled`, `required`, `error` | `valueEmitter`; `options` is always an ordinary array |
+| `Checkbox`, `TriCheckbox`, `QuadCheckbox` | `disabled`, `required`, `error` | `valueEmitter` |
+| `ThemePicker`, `ColorPicker` | `disabled` | `valueEmitter` |
+| `Dialog` | `showCloseButton` | `valueEmitter` controls open state |
+| `Panel` | `disabled` | None |
+| `ProgressBar` | None | `valueEmitter` |
+| `ListView` | None | `items` may be an array or readable emitter; selection emitters are outputs |
+| `TreeView` | None | `nodes` may be an array or readable emitter; selected/expanded emitters are outputs |
+| `DataTable` | None | `data` may be an array or readable emitter; `dataSource`/`rest` and selection emitters are explicit source/state contracts |
+| `FilterPanel` | None | `options` may be an array or readable emitter |
+| Layout, tab, description, toolbar, placeholder, and routing components | None | Their ordinary structural/configuration props require an owner rerender when changed |
+
+Readable data sources carry their own fetch state and error through Glue's
+`getFetchState()` and `getError()` APIs. `ListView`, `DataTable`, `FilterPanel`,
+and `TreeView` surface those source failures as data-loading errors. This is
+separate from a control's `error` prop, which represents validation or other
+application-level input feedback.
 
 Invalid option arrays, duplicate tab IDs, unsupported orientations, malformed
 emitters, and non-function callbacks fail with descriptive errors.
@@ -609,6 +819,80 @@ h(Toggle, {
 })
 ```
 
+### RadioGroup
+
+`RadioGroup` deliberately has a narrow reactive contract. Its selectable
+`options` are ordinary structural input, its `valueEmitter` is a stable raw
+writable state channel, and only `disabled`, `required`, and `error` accept one-way
+`live()` bindings.
+
+| Prop | Role | `live()` support |
+| --- | --- | --- |
+| `options` | Selectable value/label tuples supplied by the owner | No |
+| `disabled` | Current availability state | Yes, with a readable boolean emitter |
+| `required` | Current form-requirement state | Yes, with a readable boolean emitter |
+| `error` | Current validation message and invalid state | Yes, with a readable error emitter |
+| `valueEmitter` | Stable writable selected-value channel | Pass the emitter raw; do not wrap it |
+| `value`, `defaultValue`, `initialValue` | Initial value when no `valueEmitter` is supplied | No |
+| `id`, `label`, `ariaLabel`, `name` | Ordinary identity and presentation input | No `live()` binding |
+| `onChange` | Action callback | No |
+
+Static and live availability state can be combined without changing the option
+contract:
+
+```tsx
+const selectedView = new Emitter<'list' | 'grid'>('list')
+const unavailable = new Emitter(false)
+const mustChoose = new Emitter(true)
+
+<RadioGroup
+    label="View"
+    options={[
+        ['list', 'List'],
+        ['grid', 'Grid'],
+    ]}
+    valueEmitter={selectedView}
+    disabled={live(unavailable)}
+    required={live(mustChoose)}
+/>
+```
+
+`live(optionsEmitter)` and a raw options emitter are both unsupported. When an
+application genuinely owns a changing option vocabulary, its owning class
+component must make that structural rerender explicit:
+
+```tsx
+interface ViewChooserProps extends ComponentProps {
+    options: ReadableEmitter<readonly RadioOption[]>
+}
+
+class ViewChooser extends Component<ViewChooserProps> {
+    render() {
+        return <RadioGroup
+            label="View"
+            options={this.read(this.props.options)}
+        />
+    }
+}
+```
+
+Calling `optionsEmitter.get()` directly in `render()` only reads a snapshot and
+does not subscribe. `this.read(optionsEmitter)` rerenders the owner when the
+array changes; normal vnode reconciliation then supplies the new ordinary
+array prop to `RadioGroup`. The owner remains responsible for deciding what an
+option removal means for its selected-value emitter. Fray does not silently
+select, clear, or otherwise rewrite that state.
+
+`label` is a `FrayChild`, so it may still contain an emitter that is rendered
+and subscribed as child content. That fine-grained child behavior is distinct
+from making the `label` property itself a `live()` binding. The same is true of
+an individual `RadioOption` label: its rendered content may be reactive without
+making the option array or its selectable values live.
+
+Because `live()` subscriptions belong to a parent render record, pass live
+props through JSX or `h()`. Direct `new RadioGroup(...)` construction accepts
+resolved booleans and ordinary arrays only.
+
 ### Checkbox variants
 
 ```ts
@@ -620,6 +904,18 @@ h(QuadCheckbox, {label: 'Required tags', defaultValue: FilterMode.Require})
 `FilterMode` values are `Deny`, `Neutral`, `Prefer`, and `Require`. The basic
 checkbox uses neutral/prefer, while the variants expose the additional states.
 
+### Header
+
+```tsx
+<Header id="portfolio-header" headingId="portfolio-title" level={2}>
+    Portfolio summary
+</Header>
+```
+
+`level` is an integer from `1` through `6` and defaults to `2`. Header children
+must be valid native heading content. The custom host owns presentation while
+the nested native heading owns document semantics.
+
 ### Panel
 
 ```ts
@@ -642,10 +938,10 @@ h(Sidebar, {
 }, h('ul', null, h('li', null, 'Release automation')))
 ```
 
-The surrounding grid or flex layout must bound the Sidebar's height. Its
-header and toolbar remain fixed while the dedicated content part owns vertical
-scrolling and is keyboard-focusable. Supply `ariaLabel` when there is no visible
-`header`.
+The surrounding grid or flex layout must bound the Sidebar's height. Its native
+complementary region is inside the fixed Sidebar host; Header and toolbar remain
+fixed while the dedicated content part owns vertical scrolling and is keyboard-
+focusable. Supply `ariaLabel` when there is no visible `header`.
 
 ### Declarative tabs
 
@@ -676,149 +972,74 @@ content and IDs.
 
 ## Styling and accessibility
 
-Fray's styling system has three physically and conceptually separate layers:
+A Fray application loads four ordered styling inputs:
+
+| Order | Input | Responsibility |
+| --- | --- | --- |
+| 1 | `themes/base.css` | Default palette anchors, palette-ramp derivation, and semantic custom-property defaults only |
+| 2 | Runtime-collected component CSS | Rules from the `static css` declarations of the component classes the application declares |
+| 3 | `colors/<name>/colors.css` | Palette anchors and endpoints only |
+| 4 | `themes/<name>/theme.css` | Intentional custom-property overrides; `color-scheme` is the only ordinary declaration allowed |
+
+Application layout remains in application-owned CSS and is not a fifth Fray
+layer. Named color and theme files never import the base file; load order is
+explicit at the application entry point.
+
+Component classes own every selector and every declaration that consumes a
+Fray variable. Shared rules live in meaningful abstract component classes when
+those components share DOM or behavior. For example, `Dropdown` inherits the
+labeled-input contract and then the select-shell contract. The collector walks
+that class chain base-to-derived, resolves each class's own `&` selectors
+against the concrete host, and then traverses dependencies declared at every
+level. The older named `baseStyles` recipe system has been removed.
+
+A component's `static css` should contain the absolute minimum needed for its
+contract. Every selector, declaration, pseudo-element, and variable must have a
+specific purpose that cannot be expressed more simply. A base-class edit must
+be reviewed against all descendants because its CSS is compiled into each
+concrete descendant that is used.
+
+The checked-in `styles/structural.css` is a complete generated artifact for
+non-tree-shaken/diagnostic use. Normal applications should register their root
+component and inject the resulting usage-specific stylesheet:
 
-| Layer | Shipped path | Responsibility | Runtime behavior |
-| --- | --- | --- | --- |
-| Structure | `styles/structural.css` | Generated component layout, flow, sizing, positioning, accessibility mechanics, stable hooks, and variable consumption | Loaded once; remains stable during presentation changes |
-| Theme | `themes/<name>/theme.css` | Typography, spacing, geometry, depth, surface treatment, semantic family mappings, and exceptional pseudo/native rendering | Loaded separately and independently replaceable |
-| Colors | `colors/<name>/colors.css` | Primary, secondary, and neutral ramps plus contrast/color primitives; no UI-semantic roles | Loaded separately and independently replaceable |
-
-Component authors place only structure and mechanics in `static css`: display,
-flow, sizing, positioning, overflow, stable state hooks, and consumption of
-semantic variables. Reusable `static baseStyles` mappings apply named
-structural rules to component selectors, while `static dependencies` let the
-collector traverse a complete application tree, deduplicate definitions, and
-generate one artifact. Literal palettes and treatment-specific shadows,
-gradients, radii, and decoration do not belong in component CSS.
-
-The initial supported treatments are `shiny`, `java`, and `minimal`. The color
-catalog contains `iceblue`, `ocean`, `green`, `gray`, `orange`, `purple`, `red`,
-and `yellow`. The older top-level `themes/light.css` and `themes/dark.css`
-remain compatibility bundles; new applications should use the separated
-contract.
-
-These three treatments adapt the useful intent of earlier styling experiments
-rather than preserving their CSS literally. Application-specific selectors,
-duplicated declarations, and mixed structural/presentation rules were removed;
-the characteristic restrained Minimal, classic raised Java, and layered glossy
-Shiny treatments were rebuilt on the current component hooks and variables.
-
-### Hierarchical custom properties
-
-CSS custom properties are Fray's primary theme integration protocol:
-
-```text
-colors.css
-  --palette-primary-* / --palette-secondary-* / --palette-neutral-*
-                  │
-                  ▼
-theme.css
-  global UI roles (font, spacing, shape, surface)
-                  │
-                  ▼
-  generic families (header, button, input, panel, selection)
-                  │
-                  ▼
-  optional variants (table header, tab button, toggle button,
-                     dropdown trigger, dialog header)
-                  │
-                  ▼
-structural CSS and custom components
+```ts
+const runtime = createFrayRuntime()
+runtime.registerStyles(App).injectStyles(document)
+runtime.mount(runtime.create(App), root)
 ```
 
-Components request the narrowest useful variable and explicitly fall back
-toward its generic family. A theme can therefore change all header-like or
-button-like elements with a few assignments, then override only the variants
-that should look different. `frayThemeVariableCatalog` exports this contract in
-machine-readable form, including every variable's layer, family, value kind,
-purpose, and optional fallback.
+### Custom properties
 
-A custom component can apply the public trait matching the treatment it needs
-and optionally consume the same variable hierarchy:
+`base.css` derives full primary, secondary, and neutral ramps from each
+palette's `500` anchor plus light/dark mix endpoints. A color file therefore
+sets anchors and endpoints, while a theme maps or overrides semantic families
+such as `--button-*`, `--input-*`, `--panel-*`, and `--selection-*`.
+`frayThemeVariableCatalog` exposes the supported vocabulary.
 
-```css
-acme-grid.datacomponentlike > header {
-  color: var(--table-header-color, var(--header-color));
-  background: var(--table-header-background, var(--header-background));
-}
-```
+`--application-background` owns the canvas behind an axis-filling application
+root and its islands. Its base value is the white palette endpoint, which
+Shiny and Minimal both retain.
 
-Complete traits use the `like` suffix. A component whose outer and content
-regions are distinct uses `shell` and `inner`, for example `buttonshell` with
-`buttoninner`, or `datacomponentshell` with `datacomponentinner`. Other public
-families include `inputlike`, `headerlike`, `coloredlike`, `panellike`, and
-`toolbarlike`; the panel and toolbar families also expose
-`panelshell`/`panelinner` and `toolbarshell`/`toolbarinner`. Wrappers are not
-introduced solely to carry a split trait.
-
-Themes directly target native elements, public traits, native pseudo-parts,
-and native/ARIA state. They never target `data-fray-component` or `data-part`.
-Every theme seeds inherited variables with a zero-specificity
-`:root`/`[data-theme]` boundary rule. Presentation selectors use `@scope` with
-nested theme roots and `[data-theme-exclude]` limits, a named cascade layer,
-and low-specificity `:where()` selectors. Shiny's highlights and
-select/progress decoration follow that contract and yield to native
-representation under forced colors.
-
-`coloredlike` defaults to the primary palette. Components can provide
-`--colored-base`, `--colored-light`, `--colored-dark`, and
-`--colored-contrast`; the active theme decides whether those inputs become a
-flat color, gradient, other polish, or no special treatment.
+The explicit `island` modifier consumes `--island-margin`,
+`--island-padding`, `--island-background`, `--island-border`,
+`--island-radius`, and `--island-shadow`. Base and Minimal keep its layout and
+elevation neutral; Shiny uses it for Bank2-style separated surfaces. Themes do
+not infer island boundaries from component type or nesting, and islands cannot
+contain other islands.
 
 ### Runtime selection
 
 `replaceFrayStylesheet` maintains one
 `link[data-fray-stylesheet="theme"]` and one
 `link[data-fray-stylesheet="colors"]`. Replacing either link also sets the
-corresponding `data-theme` or `data-color` root attribute. The
-`ThemePicker` and `ColorPicker` controls expose the same operation through the
-normal Fray value-control contract.
-
-The default option catalogs resolve URLs against Fray's published package
-layout for direct ESM/CDN use. A bundled application should ask its bundler to
-emit each selectable CSS file as an asset and supply those resulting URLs:
-
-```tsx
-import {ColorPicker, Component, ThemePicker} from '@sylwellsoftware/fray'
-import iceblueHref from '@sylwellsoftware/fray/colors/iceblue/colors.css?url'
-import purpleHref from '@sylwellsoftware/fray/colors/purple/colors.css?url'
-import minimalHref from '@sylwellsoftware/fray/themes/minimal/theme.css?url'
-import shinyHref from '@sylwellsoftware/fray/themes/shiny/theme.css?url'
-
-const themes = [
-    {value: 'shiny', label: 'Shiny', href: shinyHref},
-    {value: 'minimal', label: 'Minimal', href: minimalHref},
-]
-const colors = [
-    {value: 'iceblue', label: 'Ice blue', href: iceblueHref},
-    {value: 'purple', label: 'Purple', href: purpleHref},
-]
-
-class AppearanceControls extends Component {
-    render() {
-        return <aside aria-label="Appearance">
-            <ThemePicker label="Theme" options={themes} defaultValue="shiny" />
-            <ColorPicker label="Colors" options={colors} defaultValue="iceblue" />
-        </aside>
-    }
-
-    static dependencies = [ColorPicker, ThemePicker]
-}
-```
-
-The `?url` syntax above is supported by Vite; use the equivalent emitted-asset
-mechanism for another bundler. The structural stylesheet is not replaced.
-
-See [`themes/README.md`](themes/README.md) for the complete architecture and
-variable families, and [`colors/README.md`](colors/README.md) for the palette
-contract.
+corresponding root data attribute. `ThemePicker` and `ColorPicker` expose the
+same operation through the normal value-control contract. The base file and
+runtime-injected structural stylesheet stay loaded while those two links are
+replaced.
 
-Stable examples are tested with axe in Chromium, Firefox, and WebKit and have
-no serious or critical automated violations. Browser tests also cover keyboard
-operation, labelled roles, reduced motion, 200% configured text sizing, and
-forced-colors focus visibility. A formal manual screen-reader pass is still a
-release-candidate requirement; automated checks are not a substitute for it.
+See [the theme contract](themes/README.md) and
+[the palette contract](colors/README.md) for authoring details.
 
 ## Data workflows
 
@@ -882,8 +1103,8 @@ For a tree derived from domain state, a callback updates that real source; the
 tree derivation then rebuilds and `deriveTreeNode` resolves the fresh node.
 `updateTreeNode` is the equivalent pure path-copy operation.
 
-Generic `FilterState` keeps `neutral`, `prefer`, `require`, and `deny` semantic
-values separate from glyphs and transport. `filterByState`,
+Generic `FilterState` keeps `neutral`, `prefer`, `require`, and `deny`
+semantic values separate from glyphs and transport. `filterByState`,
 `deriveFilterPredicate`, and `deriveFilteredItems` consume caller-supplied
 dimension matchers. `serializeFilterState`/`parseFilterState` round-trip
 validated version-1 plain data without owning URL or storage access. Unknown
@@ -902,5 +1123,5 @@ React/Vue adapters, a broad design system, a virtualized production data grid,
 legacy-browser support, or a stable `1.0` API. See the [workspace
 overview](../../README.md), [API surface](../../docs/API_SURFACE.md),
 [architecture overview](../../docs/architecture.md),
-[changelog](../../CHANGELOG.md), [contribution guide](../../CONTRIBUTING.md),
+[changelog](CHANGELOG.md), [contribution guide](../../CONTRIBUTING.md),
 and [security policy](../../SECURITY.md).