snice 7.0.2 → 7.1.0

package/docs/ai/components/radio.md

@@ -103,3 +103,10 @@ Only the newly selected radio emits. The old member is silently unchecked. Direc
 Slot: `suffix`.
 
 CSS parts: `input`, `radio`, `dot`, `spinner`, `content`, `label`, `description`.
+
+## Accessibility
+
+- Native radio input drives keyboard and AT behavior; one roving tab stop per named group
+- Visible label text associated with the native control; external `<label for>` supports association, focus, activation, cancellation
+- Required group validity and native labels exposed through `ElementInternals`
+- Visible keyboard focus indicator; `aria-invalid` reflects explicit or calculated group invalidity

package/docs/ai/components/rating.md

@@ -7,7 +7,7 @@ Interactive star rating input with full/half precision, custom icons, and keyboa
 ```typescript
 value: number = 0;
 max: number = 5;
-icon: string = '★';
+icon: string = 'star';   // catalogue name, emoji, URL, or image file
 emptyIcon: string = ''; // attr empty-icon; empty falls back to icon
 size: 'small'|'medium'|'large' = 'medium';
 readonly: boolean = false;
@@ -20,8 +20,8 @@ precision: 'full'|'half' = 'full';
 
 ## CSS Custom Properties
 
-- `--rating-color` - Filled star color (`var(--snice-color-warning)`)
-- `--rating-color-empty` - Empty star color (`var(--snice-color-border)`)
+- `--rating-color` - Filled star color (`rgb(245 158 11)`; not theme-derived)
+- `--rating-color-empty` - Empty star color (`var(--snice-color-text-tertiary)`)
 - `--rating-size` - Star size (auto-set by `size`: small=1rem, medium=1.5rem, large=2rem)
 
 ## CSS Parts

package/docs/ai/components/select.md

@@ -14,14 +14,8 @@ Customizable dropdown selection with single/multiple, search, editable input, an
 ```typescript
 value: string = '';                 // Live; comma-separated for multiple
 defaultValue: string = '';          // attr: value; authored/reset default
-disabled: boolean = false;
-required: boolean = false;
-invalid: boolean = false;
-readonly: boolean = false;
-loading: boolean = false;
-multiple: boolean = false;
-searchable: boolean = false;
-clearable: boolean = false;
+disabled | required | invalid | readonly | loading: boolean = false;
+multiple | searchable | clearable: boolean = false;
 editable: boolean = false;          // Text input trigger instead of button
 allowFreeText: boolean = false;     // attr: allow-free-text
 remote: boolean = false;            // Remote search via @request('select/search')
@@ -37,11 +31,8 @@ placeholder: string = 'Select an option';
 maxHeight: string = '200px';        // attr: max-height
 options: SelectOption[] = [];       // JS only, works alongside <snice-option> children
 readonly labels: NodeList | null;   // Current explicit/wrapping external labels
-readonly type: 'select-one' | 'select-multiple';
-readonly form: HTMLFormElement | null;
-readonly validity: ValidityState;
-readonly validationMessage: string;
-readonly willValidate: boolean;
+readonly type: 'select-one' | 'select-multiple'; form: HTMLFormElement | null;
+readonly validity: ValidityState; validationMessage: string; willValidate: boolean;
 ```
 
 ### snice-option

package/docs/ai/components/spotlight.md

@@ -29,6 +29,7 @@ interface SpotlightStep {
 - `spotlight-step` → `{ index, step }`
 - `spotlight-end` → `void`
 - `spotlight-skip` → `{ index }`
+- `spotlight-target-missing` → `{ index, step }` — step target gone (e.g. route change); popover stops instead of pointing at nothing
 
 ## CSS Custom Properties
 
@@ -55,6 +56,7 @@ spotlight.start();
 
 spotlight.addEventListener('spotlight-end', () => console.log('Tour completed'));
 spotlight.addEventListener('spotlight-skip', (e) => console.log(`Skipped at ${e.detail.index}`));
+spotlight.addEventListener('spotlight-target-missing', (e) => console.warn('Missing target', e.detail.step.target));
 ```
 
 ## CSS Parts

package/docs/ai/components/table.md

@@ -124,10 +124,7 @@ type CellStyle={backgroundColor?:string;color?:string;fontWeight?:'normal'|'bold
 
 ## CSS Parts
 
-- `body` - Table body
-- `filter-button` - Column filter trigger
-- `sort-indicator` - Column sort direction indicator
-- `<snice-table>`: `superheader`, `controls`, `toolbar`, `pagination` (no native header/body/cell parts); `<snice-row>`: `container`, `checkbox-cell`, `cell`; cells: `content`; actions: `action-button`; JSON: `toggle`; tag: `tag`; link/email/phone/location: `link`
+- `<snice-table>`: `body`, `superheader`, `controls`, `toolbar`, `pagination`, `filter-button` (column filter trigger), `sort-indicator` (sort direction); `<snice-row>`: `container`, `checkbox-cell`, `cell`; cells: `content`; actions: `action-button`; JSON: `toggle`; tag: `tag`; link/email/phone/location: `link`
 
 ## CSS Custom Properties
 

package/docs/ai/components/tag-input.md

@@ -87,3 +87,9 @@ tagInput.addEventListener('tag-change', (e) => {
   console.log('Tags:', e.detail.value);
 });
 ```
+
+## Accessibility
+
+- `label` supplies the input's accessible name
+- Adding, removing, and selecting tags are all reachable by keyboard (see Keyboard Navigation)
+- Focus returns to the input after a tag is added or removed

package/docs/ai/components/terminal.md

@@ -23,6 +23,12 @@ showTimestamps: boolean = false; // attr: show-timestamps
 - `getHistory()` - Get command history
 - `clearHistory()` - Clear command history
 
+Streaming API — feed raw chunks without splitting on newlines; a trailing partial line stays live and grows until a newline commits it:
+
+- `appendChunk(chunk, type?)` - Append a raw chunk
+- `pipeFrom(source, type?)` - Stream an `AsyncIterable<string>` or `ReadableStream<string|Uint8Array>`; returns `Promise<void>`
+- `commitLiveLine()` - Force the live buffer to become a finished line
+
 ## Events
 
 - `terminal-command` -> `{ command, args }` - Command entered

package/docs/ai/components/tooltip.md

@@ -90,19 +90,13 @@ Observer for `tooltip` attribute on any element. No wrapper element -- safe insi
 
 ### CSS Variable API
 
-| Variable | Default | Description |
-|---|---|---|
-| `--tooltip-position` | `top` | top/bottom/left/right + -start/-end |
-| `--tooltip-trigger` | `hover` | hover, click, focus |
-| `--tooltip-delay` | `0` | Show delay (ms) |
-| `--tooltip-hide-delay` | `0` | Hide delay (ms) |
-| `--tooltip-offset` | `12` | Distance from trigger (px) |
-| `--tooltip-arrow` | (shown) | `none` to hide |
-| `--tooltip-max-width` | `250` | Max width (px) |
-| `--tooltip-z-index` | `10000` | Z-index |
-| `--tooltip-strict-positioning` | (false) | `true` to disable auto-flip |
-| `--tooltip-bg` | `hsl(0 0% 20%)` | Background color |
-| `--tooltip-color` | `white` | Text color |
-| `--tooltip-padding` | `8px 12px` | Content padding |
-| `--tooltip-radius` | `6px` | Border radius |
-| `--tooltip-font-size` | `14px` | Font size |
+- `--tooltip-position` (`top`) — top/bottom/left/right + `-start`/`-end`
+- `--tooltip-trigger` (`hover`) — hover, click, focus
+- `--tooltip-delay` (`0`) / `--tooltip-hide-delay` (`0`) — show / hide delay (ms)
+- `--tooltip-offset` (`12`) — distance from trigger (px)
+- `--tooltip-arrow` (shown) — `none` to hide; `--tooltip-arrow-size` (`6px`) sizes it
+- `--tooltip-max-width` (`250`) — max width (px)
+- `--tooltip-z-index` (`10000`)
+- `--tooltip-strict-positioning` (false) — `true` disables auto-flip
+- `--tooltip-bg` (`hsl(0 0% 20%)`) background / `--tooltip-color` (`white`) text color
+- `--tooltip-padding` (`8px 12px`) content padding, `--tooltip-radius` (`6px`), `--tooltip-font-size` (`14px`)

package/docs/ai/components/tree.md

@@ -11,8 +11,8 @@ showCheckboxes: boolean = false;  // attr: show-checkboxes
 showIcons: boolean = true;        // attr: show-icons
 expandOnClick: boolean = false;   // attr: expand-on-click
 nodes: TreeNode[] = [];
-selectedNodes: string[] = [];     // attr: selected-nodes
-checkedNodes: string[] = [];      // attr: checked-nodes
+selectedNodes: string[] = [];     // JS-only; no attribute
+checkedNodes: string[] = [];      // JS-only; no attribute
 
 interface TreeNode {
   id: string;

package/docs/ai/components/video-player.md

@@ -78,6 +78,11 @@ duration: number;               // read-only
 - ArrowRight/ArrowLeft: Seek forward/backward 5s
 - ArrowUp/ArrowDown: Volume up/down 10%
 
+## Accessibility
+
+- Controls carry ARIA labels; current time, duration, and playback state are exposed to AT
+- Transitions respect `prefers-reduced-motion`
+
 ## Basic Usage
 
 ```html

package/docs/ai/components/waterfall.md

@@ -58,3 +58,10 @@ chart.addEventListener('bar-click', (e) => {
   console.log(`Clicked: ${e.detail.item.label} (${e.detail.item.value})`);
 });
 ```
+
+## Accessibility
+
+- Bars carry data-visualization roles, are focusable, and activate by keyboard
+- `showValues` exposes value labels as screen-reader text
+- Bar types distinguishable by color *and* value label, not color alone
+- Animations respect `prefers-reduced-motion`

package/docs/ai/daemons.md

@@ -0,0 +1,80 @@
+# Daemons
+
+Human reference: `docs/daemons.md`.
+
+Ordinary explicitly constructed stateful objects with app-owned lifecycles.
+`@daemon` adds per-instance Snice communication; it never constructs, caches,
+globally registers, starts, or stops an instance.
+
+```typescript
+@daemon
+class SessionDaemon {
+  session: Session | null = null;
+
+  @respond('get-session')
+  getSession() { return this.session; }
+
+  @on('set-session')
+  setSession(e: CustomEvent<Session>) {
+    this.session = e.detail;
+    this.changed();
+  }
+
+  @dispatch('session-changed')
+  changed() { return this.session; }
+}
+
+const session = new SessionDaemon();
+const release = provideContext(appRoot, { daemons: { session } });
+```
+
+Context contract:
+
+```typescript
+type DaemonMap = Readonly<Record<string, object>>;
+
+interface AppContext {
+  readonly daemons?: DaemonMap;
+  [key: string]: unknown;
+}
+```
+
+Extend `AppContext` to type application-specific fields; Snice assigns meaning
+only to `daemons`.
+
+Router automatically provides its `context` beneath `target`. Non-router apps
+call `provideContext(root, context)`. `getContext(elementOrController)` returns
+the raw visible app context.
+
+Consumer; no daemon implementation import:
+
+```typescript
+@request<Session | null>('get-session', { daemon: 'session' })
+async *load(): Response<Session | null> { return yield {}; }
+
+@dispatch('set-session', { daemon: 'session' })
+set(session: Session) { return session; }
+
+@on('session-changed', { daemon: 'session' })
+changed(e: CustomEvent<Session | null>) {}
+
+@respond('confirm-logout', { daemon: 'session' })
+confirm() { return true; }
+```
+
+Daemon methods without `{ daemon }` use that instance's private target.
+Controllers resolve through their attached host.
+
+Resolution: participant -> nearest provided app context ->
+`context.daemons[name]` -> instance target. No globals, implicit construction,
+fallback, scanning, or late binding.
+
+Rules:
+- Provide before element connect/controller attach (`@on`/`@respond` bind then).
+- `@request`/`@dispatch` resolve at invocation.
+- `daemon` and `scope` are mutually exclusive.
+- No selector delegation on daemon targets.
+- Release function is idempotent and makes daemon traffic inert.
+- Multiple instances of the same class and same address under different roots
+  are independent.
+- Missing/undecorated/inactive entries fail explicitly.

package/docs/ai/decorators.md

@@ -4,6 +4,7 @@
 - `@element('tag-name', options?)` - Custom element. Options: `{ formAssociated?, renderRoot?: 'shadow'|'light', shadow?: 'open'|'closed'|false, delegatesFocus? }`
 - `@page({ tag, routes, guards?, placard? })` - Routable page
 - `@controller('name')` - Swappable behavior. Required on every controller class. Attach by class (preferred): `controller=${MyController}` in templates, `attachController(el, MyController)`, or `el.controller = MyController`; by string in raw HTML: `controller="name"`
+- `@daemon` - Marks an explicitly constructed app-context daemon. No name argument; context key is address. Never constructs/registers globally.
 - `@layout('tag-name')` - Page wrapper for routing system
 
 ## Rendering
@@ -30,8 +31,8 @@
 - `@queryAll('selector', { light? })` - NodeList
 
 ## Events
-- `@on('event', 'selector?', options?)` - Delegation, auto-bound. Options: `{ capture?, once?, passive?, preventDefault?, stopPropagation?, debounce?, throttle?, scope? }`
-- `@dispatch('event-name', options?)` - Emit CustomEvent, detail = return value. Supports async. Options: `{ debounce?, throttle?, dispatchOnUndefined?, scope?, ...EventInit }`
+- `@on('event', 'selector?', options?)` - Delegation, auto-bound. Options: `{ capture?, once?, passive?, preventDefault?, stopPropagation?, debounce?, throttle?, scope?, daemon? }`
+- `@dispatch('event-name', options?)` - Emit CustomEvent, detail = return value. Supports async. Options: `{ debounce?, throttle?, dispatchOnUndefined?, scope?, daemon?, ...EventInit }`
 
 ### scope (on both `@on` and `@dispatch`)
 
@@ -63,9 +64,10 @@ Unresolved scope → `console.warn`, listener not attached / event not dispatche
 Resolver re-runs on reconnect — listeners track DOM moves.
 
 ## Communication
-- `@request(channel, options?)` - Async generator request pattern
-- `@respond(channel, options?)` - Handle requests from `@request`
+- `@request(channel, options?)` - Async generator request pattern; `{ daemon: 'name' }` targets an app-context daemon
+- `@respond(channel, options?)` - Handle requests from `@request`; `{ daemon: 'name' }` installs on that daemon target
 - `@context(options?)` - Receive router navigation context updates
+- `provideContext(root, context)` / `getContext(participant)` - Explicit raw app-context provisioning and lookup
 
 ## Observers
 - `@observe(target, selector?, options?)` - Watch intersection, resize, media query, mutation

package/docs/ai/events.md

@@ -342,6 +342,41 @@ changeColor(color: string) { this.color = color; return { color }; }
 confirm() { return { color: this.color }; }
 ```
 
+## Event bus
+
+No bus object, no singleton. Bus = `@dispatch` publishing upward + `@on` subscribing at a chosen ancestor. Scope is a DOM node, so it lives and dies with the DOM.
+
+Two publish paths — the choice decides who can hear it:
+- **Bubble from host** — `@dispatch` defaults to `bubbles: true, composed: true`, so it crosses shadow boundaries and passes every ancestor up to `document`. For "this element did something".
+- **Dispatch on a scope** — `@dispatch` takes the same `scope` option as `@on`, firing *on* that target instead of bubbling. For subscribers that are not ancestors (sibling subtree, or a detached host).
+
+```typescript
+@dispatch('bus:cart-added')                     // bubbles from host
+@dispatch('bus:cart-added', { scope: 'global' })  // dispatched on document
+
+@on('bus:cart-added', { scope: 'global' })      // document — app-wide
+@on('bus:cart-added', { scope: 'cart-shell' })  // nearest <cart-shell> — per-instance
+```
+
+Match the halves: a bubbling publish only reaches subscribers on the host's ancestor chain. Sibling subtree → scope the dispatch too, so both meet on the same node. See [scope on @dispatch](#scope-dispatch-target).
+
+Scope choice:
+- `'global'` — genuinely app-wide (auth expiry, theme change, save shortcut)
+- selector string — feature subtree; a second shell elsewhere keeps its own traffic
+- `EventTarget` / resolver — you hold the node, or it moves and must re-resolve
+
+Prefer the narrowest scope that works; `'global'` means every instance hears every message.
+
+`bus:` is a naming convention, not a framework feature. Teardown is automatic — removed on disconnect from the resolved target, re-resolved on reconnect. Unresolvable selector → listener skipped + `console.warn`, never bound to the wrong node. Full table: [scope](#scope-listener-attachment-target).
+
+Need a reply rather than a broadcast → [@request / @respond](./request-response.md).
+
+For stateful objects explicitly supplied by an application context, use
+`{ daemon: 'name' }`. Both halves must target the same daemon address; daemon
+methods themselves default to their own private target. See
+[daemons](./daemons.md). Daemon targets are not DOM scopes: `scope` and
+`daemon` cannot be combined, and selector delegation is unavailable.
+
 ## Custom events
 
 Dispatching manually:

package/docs/ai/patterns.md

@@ -94,6 +94,50 @@ Enabled automatically when Snice loads — no setup needed.
 // <table controller="table-loader"></table>
 ```
 
+## Daemon
+
+Ordinary state/lifecycle object owned by the application. Construction and
+teardown stay explicit; consumers use a context address instead of importing
+the implementation class.
+
+```typescript
+@daemon
+class SessionDaemon {
+  session: Session | null = null;
+
+  @respond('session/get')
+  getSession() { return this.session; }
+
+  @on('session/set')
+  setSession(event: CustomEvent<Session>) {
+    this.session = event.detail;
+    this.changed();
+  }
+
+  @dispatch('session/changed')
+  changed() { return this.session; }
+}
+
+const session = new SessionDaemon();
+const release = provideContext(appRoot, { daemons: { session } });
+
+@request('session/get', { daemon: 'session' })
+async *getSession(): Response<Session | null> { return yield {}; }
+
+@dispatch('session/set', { daemon: 'session' })
+setSession(session: Session) { return session; }
+
+@on('session/changed', { daemon: 'session' })
+sessionChanged(event: CustomEvent<Session | null>) {}
+```
+
+- Provide before element connection/controller attachment.
+- Router `context.daemons` uses the same provider automatically.
+- `@request`/`@respond` = one reply; `@dispatch`/`@on` = notifications.
+- `daemon` cannot be combined with DOM `scope`; daemon listeners cannot delegate selectors.
+- Call `release()` during app/test teardown.
+- See `docs/ai/daemons.md`.
+
 ## Page + Router
 
 **Module Structure (avoids circular imports):**
@@ -185,7 +229,7 @@ class API {
 @element('user-profile')
 class UserProfile extends HTMLElement {
   @request('fetch-user')
-  async *fetchUser(id: string): any {
+  async *fetchUser(id: string): Response<User> {
     const user = await (yield { id });  // yield = send request, await = get response
     return user;
   }

package/docs/ai/request-response.md

@@ -2,7 +2,7 @@
 
 Mirrors `docs/request-response.md`.
 
-Request/response communication between elements and controllers using async generators.
+Request/response communication between elements, controllers, and provided daemons using async generators.
 
 ## Why
 
@@ -27,6 +27,7 @@ function request(requestName: string, options?: RequestOptions): MethodDecorator
 function respond(requestName: string, options?: RespondOptions): MethodDecorator
 
 interface RequestOptions extends EventInit {
+  daemon?: string;          // named daemon from nearest provided app context
   timeout?: number;          // response timeout ms, default 120000 (2 min)
   discoveryTimeout?: number; // handler discovery timeout ms, default 50
   debounce?: number;
@@ -36,14 +37,20 @@ interface RequestOptions extends EventInit {
 }
 
 interface RespondOptions {
+  daemon?: string;          // install responder on named daemon target
   debounce?: number;
   throttle?: number;
 }
 
-// Recommended type helper for request generator return types (define in your project):
-type RequestResult<T> = AsyncGenerator<any, T, any> | Promise<T>;
+// Public return type for methods decorated with @request:
+type Response<T = any> = T | any;
 ```
 
+TypeScript cannot model a method decorator changing an async generator into a
+promise-returning method. This is a deliberate pragmatic annotation: it keeps
+strict consumers usable and documents `T`; the decorated runtime method
+returns a promise for `T`.
+
 ### Response debounce/throttle
 
 ```typescript
@@ -65,6 +72,16 @@ class ProcessingController implements IController {
 }
 ```
 
+Daemon communication uses the same protocol without DOM bubbling:
+
+```typescript
+@request('get-session', { daemon: 'session' })
+async *getSession() { return yield {}; }
+```
+
+The daemon's plain `@respond('get-session')` handles it. See
+[daemons](./daemons.md).
+
 ## Element-Side Requests
 
 ```typescript
@@ -75,7 +92,7 @@ class ProductCard extends HTMLElement {
   @property() price = '';
 
   @request('fetch-product')
-  async *loadProduct(): RequestResult<void> {
+  async *loadProduct(): Response<void> {
     const product = await (yield { id: this.productId });
     this.name = product.name;
     this.price = product.price;
@@ -121,17 +138,17 @@ Elements never call `fetch()` or manage data directly — they yield requests up
 
 ```typescript
 @request('heavy-computation', { discoveryTimeout: 50, timeout: 30000 })
-async *compute(): RequestResult<any> { return await (yield data); }
+async *compute(): Response<any> { return await (yield data); }
 ```
 
 ### Debounce/Throttle
 
 ```typescript
 @request('search', { debounce: 300 })
-async *search(): RequestResult<any[]> { return await (yield { query: this.searchTerm }); }
+async *search(): Response<any[]> { return await (yield { query: this.searchTerm }); }
 
 @request('track', { throttle: 1000 })
-async *trackEvent(): RequestResult<void> { await (yield { event: 'scroll', position: window.scrollY }); }
+async *trackEvent(): Response<void> { await (yield { event: 'scroll', position: window.scrollY }); }
 ```
 
 ## Error Handling
@@ -140,7 +157,7 @@ async *trackEvent(): RequestResult<void> { await (yield { event: 'scroll', posit
 
 ```typescript
 @request('load-data', { timeout: 5000 })
-async *loadData(): RequestResult<void> {
+async *loadData(): Response<void> {
   try {
     this.data = await (yield { id: this.dataId });
     this.error = '';
@@ -201,7 +218,7 @@ class LiveTicker extends HTMLElement {
   @property() symbol = 'BTC';
 
   @request('subscribe-ticker')
-  async *subscribe(): RequestResult<void> { await (yield { symbol: this.symbol }); }
+  async *subscribe(): Response<void> { await (yield { symbol: this.symbol }); }
 
   @on('ticker-update')
   onUpdate(e: CustomEvent) { this.price = e.detail.price; }

package/docs/ai/routing.md

@@ -25,7 +25,7 @@ interface RouterOptions {
   document?: Document;               // override document object (testing)
   transition?: Transition;           // global transition config
   layout?: string;                   // default layout tag for all pages
-  context?: any;                     // shared context object across pages/layouts
+  context?: any;                     // app context; may expose daemons
   fetcher?: Fetcher;                 // optional fetch middleware — see docs/ai/fetcher.md
 }
 ```
@@ -45,6 +45,19 @@ class AppContext {
 const { page, initialize } = Router({ target: '#app', type: 'hash', context: new AppContext() });
 ```
 
+Router also provides the raw app context beneath `target`, using the same
+`provideContext()` mechanism available to non-router applications. Explicitly
+constructed `@daemon` instances may be addressed through `context.daemons`:
+
+```typescript
+const session = new SessionDaemon();
+Router({
+  target: '#app',
+  type: 'hash',
+  context: { daemons: { session } }
+});
+```
+
 ### Module structure (avoids circular imports)
 
 ```typescript
@@ -176,4 +189,6 @@ function Router(options: RouterOptions): {
 
 - `navigate(path: string): Promise<void>` — navigates to `path`; uses hash or pushstate depending on router `type`.
 - `initialize(): void` — starts listening for route changes; must be called after all pages are defined.
+- Do not add `@element` to an `@page` class. The Router-returned page decorator
+  already registers the custom element and applies Snice element behavior.
 - `register(route: string, tag: string, transition?: Transition, guards?: Guard | Guard[], layout?: string | false, placard?: Placard | ((ctx: AppContext) => Placard)): void` — manually registers a route without the `@page` decorator. Note: the return-type shape above lists `register` with 4 params; this fuller 6-param signature (adding `layout`, `placard`) is documented separately in the source.

package/docs/cli.md

@@ -50,6 +50,13 @@ npx snice validate    # source analyzer only
 
 - an `@element`-decorated class that does not extend `HTMLElement` (or a Snice element subclass) — Snice registers and renders only element subclasses
 - deep imports that were never released package paths, such as `snice/decorators`
+- a Router without `target`, `type`, or a project-wide `initialize()` call
+- a routed class combining `@page` with redundant `@element`
+
+It also gives non-blocking architecture suggestions: keep `@page`, `@element`,
+`@controller`, and `@daemon` classes under `src/pages`, `src/components`,
+`src/controllers`, and `src/daemons`; extract clearly service-heavy or repeated
+page logic into a controller. Small route orchestration remains valid page code.
 
 Both accept `--json` for CI.
 

package/docs/components/breadcrumbs.md

@@ -32,9 +32,10 @@ Individual breadcrumb item (data element, no shadow DOM).
 | Property | Attribute | Type | Default | Description |
 |----------|-----------|------|---------|-------------|
 | `items` | -- | `BreadcrumbItem[]` | `[]` | Array of breadcrumb items (JS property only) |
-| `separator` | `separator` | `'/' \| '>' \| '>>' \| '.' \| '\|'` | `'/'` | Separator between items |
+| `separator` | `separator` | `'/' \| '>' \| '»' \| '•' \| '\|'` | `'/'` | Separator between items |
 | `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Breadcrumb size |
 | `maxItems` | `max-items` | `number` | `0` | Max items to show (0 = show all). Collapsed items show an ellipsis. |
+| `collapsed` | `collapsed` | `boolean` | `true` | Whether the trail is collapsed behind the ellipsis. Clicking the ellipsis sets it `false`; it resets to `true` when `items`, `separator`, or `maxItems` change. Only has an effect once `maxItems` is exceeded. |
 
 ### BreadcrumbItem Interface
 

package/docs/components/calendar.md

@@ -23,7 +23,7 @@ Display and select dates with event support, date restrictions, and locale-aware
 | `events` | `CalendarEvent[]` | `[]` | Calendar events |
 | `minDate` (attr: `min-date`) | `Date \| string` | `''` | Minimum selectable date |
 | `maxDate` (attr: `max-date`) | `Date \| string` | `''` | Maximum selectable date |
-| `disabledDates` (attr: `disabled-dates`) | `(Date \| string)[]` | `[]` | Disabled dates |
+| `disabledDates` | `(Date \| string)[]` | `[]` | Disabled dates (JS-only; no attribute) |
 | `highlightToday` (attr: `highlight-today`) | `boolean` | `true` | Highlight today's date |
 | `showWeekNumbers` (attr: `show-week-numbers`) | `boolean` | `false` | Show week numbers |
 | `firstDayOfWeek` (attr: `first-day-of-week`) | `number` | `0` | First day of week (0=Sun, 1=Mon) |

package/docs/components/camera.md

@@ -19,7 +19,7 @@ Live camera feed with built-in mobile-style controls, flexible positioning, aspe
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `autoStart` (attr: `auto-start`) | `boolean` | `true` | Auto-start camera on load |
+| `autoStart` (attr: `auto-start`) | `boolean` | `false` | Auto-start camera on load |
 | `facingMode` (attr: `facing-mode`) | `'user' \| 'environment'` | `'user'` | Front or back camera |
 | `mirror` | `boolean` | `true` | Mirror video for front camera |
 | `controlsPosition` (attr: `controls-position`) | `ControlsPosition` | `'auto'` | Control button positioning |

package/docs/components/chart.md

@@ -19,7 +19,7 @@ General-purpose charting component supporting 10 chart types with animations, in
 | `type` | `ChartType` | `'line'` | Chart type: `'line'`, `'bar'`, `'horizontal-bar'`, `'area'`, `'pie'`, `'donut'`, `'scatter'`, `'bubble'`, `'radar'`, `'mixed'` |
 | `datasets` | `ChartDataset[]` | `[]` | Chart datasets (property only) |
 | `labels` | `string[]` | `[]` | X-axis labels (property only) |
-| `options` | `ChartOptions` | `{}` | Chart options (property only) |
+| `options` | `ChartOptions` | see description | Chart options (property only). Defaults: responsive, no fixed aspect ratio, clickable legend on top, hover tooltip, 500ms ease-out animation, x/y grids on |
 | `width` | `number` | `0` | Chart width (0 = auto) |
 | `height` | `number` | `0` | Chart height (0 = auto) |
 

package/docs/components/code-block.md

@@ -13,6 +13,10 @@ Display code with syntax highlighting, line numbers, and copy functionality. Use
 - [Basic Usage](#basic-usage)
 - [Examples](#examples)
 - [Accessibility](#accessibility)
+- [Fetch Mode](#fetch-mode)
+- [Grammar System](#grammar-system)
+- [Highlighter API](#highlighter-api)
+- [Token CSS Classes](#token-css-classes)
 
 ## Properties
 
@@ -20,10 +24,10 @@ Display code with syntax highlighting, line numbers, and copy functionality. Use
 |----------|------|---------|-------------|
 | `code` | `string` | `''` | Code content (set via slot or property) |
 | `language` | `CodeLanguage` | `'plaintext'` | Programming language |
-| `grammar` | `Grammar \| string \| null` | `null` | Grammar object or URL to grammar JSON |
+| `grammar` | `Grammar \| string \| null` | `''` | Grammar object or URL to grammar JSON |
 | `showLineNumbers` (attr: `show-line-numbers`) | `boolean` | `false` | Show line numbers |
 | `startLine` (attr: `start-line`) | `number` | `1` | Starting line number |
-| `highlightLines` (attr: `highlight-lines`) | `number[]` | `[]` | Lines to highlight |
+| `highlightLines` | `number[]` | `[]` | Lines to highlight (JS-only; no attribute) |
 | `copyable` | `boolean` | `true` | Show copy button |
 | `filename` | `string` | `''` | File name to display in header |
 | `format` | `string` | `''` | Formatter name from grammar (e.g. `"pretty"`), or any truthy string with `setFormatter()` |
@@ -104,10 +108,11 @@ console.log(greeting);
 
 ### Highlight Specific Lines
 
-Use `highlight-lines` to draw attention to specific lines.
+Set `highlightLines` in JavaScript to draw attention to specific lines. There is no
+`highlight-lines` attribute -- the property is JS-only.
 
 ```html
-<snice-code-block grammar="grammars/python.json" language="python" highlight-lines="[2,3,4]">
+<snice-code-block id="snippet" grammar="grammars/python.json" language="python">
 def hello():
     name = "World"
     greeting = f"Hello {name}"
@@ -115,6 +120,10 @@ def hello():
 </snice-code-block>
 ```
 
+```typescript
+document.getElementById('snippet').highlightLines = [2, 3, 4];
+```
+
 ### Programmatic Code
 
 Set code via the `code` property for dynamic content.