@sylwellsoftware/fray 0.7.0 → 1.1.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
 
@@ -92,15 +94,17 @@ Responsibility stays at the narrowest layer that understands it:
 
 ## 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,
@@ -108,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'
 
@@ -118,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())})))
@@ -126,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) {
@@ -133,6 +141,17 @@ 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. Either modifier also
+establishes the theme's `--font-family`, `--font-size`, and `--line-height` on
+the application root so native content and Fray controls inherit the published
+typography without application CSS. A root with neither modifier keeps its
+ordinary embedded/content-sized behavior, including its host page's typography.
+
 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
@@ -380,11 +399,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>
 ```
 
@@ -393,48 +412,44 @@ 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`
-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>, ...
+theme selector. Fray may merge public presentation traits such as `island`
+and `colored` with an application-supplied `class`/`className`; those traits
+describe a reusable capability, not component identity.
+
+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.
+
+Apply `colored` only to an element that supplies an ordered dark/base/light
+triplet through `--c1`, `--c2`, and `--c3`. The shared component rule paints
+that triplet as a gradient; named themes can add depth through
+`--colored-shadow`. Shiny supplies its glossy shadow while the base and other
+themes remain flat.
+
+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.
 
-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.
-
-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
 
@@ -449,8 +464,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 {
@@ -466,12 +481,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`.
 
@@ -481,7 +495,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. |
@@ -494,6 +508,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:
@@ -619,7 +643,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')!)
 ```
@@ -690,8 +714,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 |
 | --- | --- | --- | --- |
@@ -699,23 +725,56 @@ 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. |
-| `RadioButton` | `label`, `name`, `value`, `checked`, `disabled`, `required` | `onChange(checked, event)` | Native radio input with a label; use a shared `name` to associate standalone buttons. |
-| `RadioGroup<T>` | `options`, `label` or `ariaLabel`, value props, `name`, `disabled`, `required` | `onChange(value, event)` | Native radio inputs with one selected `valueEmitter` option. |
-| `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`. |
+| `GroupPanel` | `header`, `id`, `children` | None | Labelled bordered control group with a full-height vertical Header. |
+| `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`, 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, 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; `itemLabelClassName` and `itemLabelStyle` decorate each block label beside its expander |
+| `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.
 
@@ -770,6 +829,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
@@ -781,6 +914,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
@@ -803,10 +948,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
 
@@ -837,149 +982,79 @@ content and IDs.
 
 ## Styling and accessibility
 
-Fray's styling system has three physically and conceptually separate layers:
-
-| 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:
+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:
 
-```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.
+
+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.
 
-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 reusable `colored` trait consumes a required `--c1`/`--c2`/`--c3`
+dark/base/light triplet and `--colored-shadow`. Its base treatment is the
+shared three-stop gradient; Shiny adds depth without changing the
+application-owned triplet.
 
 ### 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
 
@@ -1043,8 +1118,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
@@ -1063,5 +1138,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).