snice 7.2.0 → 7.4.0

package/docs/ai/bindings.md

@@ -48,7 +48,7 @@ Ordinary attributes/comments support multiple expressions. Property, boolean, ev
 - Direct JS assignment; preserves type and identity.
 - null/undefined/false assigned unchanged; `nothing` assigns undefined; `noChange` skips.
 - Same committed value skips write.
-- `live(value)` compares value to the current DOM property instead of last commit; use only in property bindings when controlled native state must be reasserted after DOM/user mutation.
+- `live(value)` compares value to the current DOM property instead of last commit; use only in property bindings when controlled native or custom-element state must be reasserted after the user or element mutates it.
 - `live()` does not observe DOM mutations or schedule a render. It reasserts only when the owning template renders. A modal open-state change can supply that render when reopening should restore an unchanged seed value.
 
 ```typescript

package/docs/ai/cli.md

@@ -52,10 +52,35 @@ Non-blocking architecture suggestions:
 - `@element` -> `src/components/`
 - `@controller` -> `src/controllers/`
 - `@daemon` -> `src/daemons/`
-- several external-effect methods or substantial logic repeated across pages -> extract a controller
+- visual behavior -> element
+- application behavior specific to a set of elements -> controller
+- element orchestration -> page; do not attach a controller to the page host
+- host-free reusable function -> plain module in the project's chosen location
 
 Both `doctor` and `validate` accept `--json`.
 
+## Diagnostic codes and `.sniceignore`
+
+Every error, warning, and suggestion has a stable `code` in JSON and text
+output. Create `.sniceignore` at the project root to suppress an accepted
+diagnostic. Entries are exact; glob patterns are not used.
+
+```text
+# One exact diagnostic (preferred)
+snice/prefer-dispatch-decorator src/components/legacy-filter.ts:42:5
+
+# Every instance in one file
+snice/prefer-dispatch-decorator src/components/legacy-filter.ts
+
+# The rule everywhere in the project
+snice/prefer-dispatch-decorator
+```
+
+`code path:line` is also accepted. Paths are project-relative. A code-only
+entry suppresses the rule globally, including its effect on the command's exit
+status; use it only when the project intentionally rejects that rule. The same
+file applies to `check`, `doctor`, and `validate`.
+
 ## init-ai
 
 ```bash

package/docs/ai/components/badge.md

@@ -19,6 +19,10 @@ showZero: boolean = false;          // attr: show-zero — render 0 instead of h
 offset: number = 0;
 ```
 
+The indicator is hidden when there is no dot, non-empty `content`, positive
+`count`, or `showZero`. Slotted content remains available as the element the
+badge would overlay.
+
 ## Methods
 
 - `setBadgeContent(content)` - Set text content

package/docs/ai/components/pagination.md

@@ -57,9 +57,11 @@ variant: 'default'|'rounded'|'text' = 'default';
 
 ```typescript
 import 'snice/components/pagination/snice-pagination';
+import type { PaginationChangeDetail } from 'snice/components/pagination/snice-pagination.types';
 
-pagination.addEventListener('pagination-change', (e) => {
-  console.log('Page:', e.detail.page);
+pagination.addEventListener('pagination-change', (event) => {
+  const { detail } = event as CustomEvent<PaginationChangeDetail>;
+  console.log('Page:', detail.page);
 });
 ```
 

package/docs/ai/components/segmented-control.md

@@ -5,7 +5,7 @@ Multi-option switcher with sliding indicator. One selected at a time.
 ## Properties
 
 ```typescript
-value: string = '';
+value: string = '';  // user selection updates this before value-change dispatches
 options: SegmentedControlOption[] = [];  // JS only: { value, label, icon?, disabled? }
 size: 'small'|'medium'|'large' = 'medium';
 disabled: boolean = false;
@@ -15,6 +15,10 @@ disabled: boolean = false;
 
 - `value-change` → `{ value: string, previousValue: string, option: SegmentedControlOption, control }`
 
+`value` is self-mutating: selecting an option assigns it before the event is
+dispatched. An owner that must reassert an unchanged value on a later render
+should use a `.value=${live(value)}` property binding.
+
 ## CSS Parts
 
 - `base` - Root container

package/docs/ai/controllers.md

@@ -2,7 +2,15 @@
 
 Mirrors `docs/controllers.md`.
 
-Controllers handle data fetching, business logic, and server communication separately from visual components. Attach to any HTML element, including native elements.
+Controllers hold application behavior specific to a set of elements, including
+their data fetching, business rules, and server communication. Attach to any
+HTML element, including native elements.
+
+Visual behavior belongs in elements, application behavior specific to a set of
+elements belongs in a controller, and element orchestration belongs in pages.
+Do not attach a controller to the page host. A host-free reusable function may
+stay a plain module wherever the project keeps it. URL/query parsing belongs in
+`@page({ routes })`, not in a controller.
 
 ## Basic Usage
 
@@ -67,18 +75,21 @@ el.controller = UserController;                  // snice elements
 **Attachment flow:**
 1. Controller instance created
 2. `element` property set
-3. Router context passed (if available)
+3. Router application context passed (if available)
 4. Element's `ready` promise awaited
 5. `attach()` called
-6. Observers set up
-7. Channel/response handlers set up
-8. Event handlers set up
-9. `controller-attached` event dispatched
+6. `@context` handlers registered and caught up with the current Router context
+7. Observers set up
+8. Channel/response handlers set up
+9. Event handlers set up
+10. `controller-attached` event dispatched
 
 Exception to step 4: `await attachController(this, ControllerClass)` inside the
 host's own `@ready` handler attaches immediately because initial render is
 already complete. Awaiting that same host's `ready` would self-deadlock. An
 attachment targeting any other element still waits for the target's `ready`.
+This runtime safeguard does not make attaching a controller to a routed page a
+good architecture; pages should orchestrate directly.
 
 **Detachment flow:**
 1. `detach()` called
@@ -86,8 +97,9 @@ attachment targeting any other element still waits for the target's `ready`.
 3. Observers cleaned up
 4. Channel/response handlers cleaned up
 5. Event handlers cleaned up
-6. Controller scope cleaned up
-7. `controller-detached` event dispatched
+6. `@context` handlers cleaned up
+7. Controller scope cleaned up
+8. `controller-detached` event dispatched
 
 ## Native Element Controllers
 
@@ -103,7 +115,7 @@ Controllers provide specific behaviors (fetch/sort/filter) to generic visual com
 
 ## Resource Cleanup
 
-Framework auto-cleans `@on`, `@observe`, `@respond` handlers. Clean up your own resources (WebSockets, timers, manual listeners) in `detach`:
+Framework auto-cleans `@on`, `@observe`, `@respond`, and `@context` handlers. Clean up your own resources (WebSockets, timers, manual listeners) in `detach`:
 
 ```typescript
 @controller('resource-controller')
@@ -182,6 +194,8 @@ the element's reactive public API. Dispatch outcome events, never mutate the
 element's rendered DOM.
 
 ```typescript
+import { context, type Context } from 'snice';
+
 interface DataHost<T> extends HTMLElement {
   loading: boolean;
   error: string;
@@ -192,17 +206,24 @@ interface DataHost<T> extends HTMLElement {
 @controller('data-controller')
 class DataController<T> implements IController<DataHost<T>> {
   element: DataHost<T> | null = null;
+  private ctx?: Context;
   private abort?: AbortController;
   private version = 0;
 
-  async attach(element: DataHost<T>) {
+  attach(element: DataHost<T>) {
     this.element = element;
-    await this.reload();
+  }
+
+  @context()
+  receiveContext(ctx: Context) {
+    this.ctx = ctx;
+    void this.reload();
   }
 
   async detach() {
     this.version++;
     this.abort?.abort();
+    this.ctx = undefined;
   }
 
   async reload() {
@@ -216,7 +237,9 @@ class DataController<T> implements IController<DataHost<T>> {
     host.empty = false;
 
     try {
-      const response = await fetch('/api/data', { signal: abort.signal });
+      const ctx = this.ctx;
+      if (!ctx) throw new Error('DataController requires Router context');
+      const response = await ctx.fetch('/api/data', { signal: abort.signal });
       if (!response.ok) throw new Error(`Request failed (${response.status})`);
       const data = await response.json() as T[];
       if (version !== this.version || this.element !== host) return;
@@ -241,6 +264,12 @@ class DataController<T> implements IController<DataHost<T>> {
 }
 ```
 
+`@context()` works on controllers as well as elements. It receives the same
+long-lived `Context` instance, including `application`, navigation state, and
+the Router's middleware-aware `fetch`. Managed decorators are activated after
+`attach()`, so start context-dependent work in the `@context()` handler (or in
+an event handled later), not in `attach()`.
+
 Required pieces: abort previous work, increment a version for stale-response
 guarding, reset loading/error/empty before fetch, check version + host identity
 before every commit, expose retry as `reload()`, and render all four states in

package/docs/ai/decorators.md

@@ -2,7 +2,7 @@
 
 ## Class
 - `@element('tag-name', options?)` - Custom element. Options: `{ formAssociated?, renderRoot?: 'shadow'|'light', shadow?: 'open'|'closed'|false, delegatesFocus? }`
-- `@page({ tag, routes, guards?, placard? })` - Routable page
+- `@page({ tag, routes, guards?, placard? })` - Routable page. `routes` normally uses ordered strings; optional `{ path, order? }` entries explicitly break specificity ties.
 - `@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"`. A class attachment reflects this name in the DOM as a diagnostic marker without attaching through the registry.
 - `@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
@@ -66,8 +66,8 @@ Resolver re-runs on reconnect — listeners track DOM moves.
 ## Communication
 - `@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
+- `@context(options?)` - Receive router navigation context updates on pages, descendant elements, and attached controllers
+- `provideContext(root, context, { fetch? })` / `getContext(participant)` / `getContextFetch(participant)` - Explicit app-context and transport provisioning/lookup
 
 ## Observers
 - `@observe(target, selector?, options?)` - Watch intersection, resize, media query, mutation

package/docs/ai/events.md

@@ -272,7 +272,7 @@ updateStatus(status: string) {
 
 ```typescript
 interface DispatchOptions extends EventInit {
-  dispatchOnUndefined?: boolean; // Skip dispatch when return is undefined (default: true)
+  dispatchOnUndefined?: boolean; // Undefined return still dispatches unless false (default: true)
   debounce?: number;             // Debounce dispatch by ms
   throttle?: number;             // Throttle dispatch by ms
   // Where to dispatch the event (see scope below)
@@ -379,7 +379,13 @@ methods themselves default to their own private target. See
 
 ## Custom events
 
-Dispatching manually:
+Prefer `@dispatch` for a static custom event emitted from a Snice element or a
+controller's host. It supplies the standard bubbling/composed behavior, uses
+the method return value as `detail`, and keeps event timing options declarative.
+
+Manual dispatch remains a valid low-level escape hatch when code needs the
+Event object, a dynamic event name, `dispatchEvent()`'s cancellation boolean,
+or a non-host target:
 
 ```typescript
 notify() {

package/docs/ai/fetcher.md

@@ -30,7 +30,13 @@ const router = Router({ target: '#app', context: { auth: null }, fetcher });
 router.initialize();
 ```
 
-## `ctx.fetch` in pages
+Pages, descendant elements, and attached controllers receive the Router's
+long-lived `Context` through `@context()`; its `ctx.fetch` is the bound,
+middleware-aware function. `getContextFetch(this)` remains the lower-level
+lookup for code using an explicit non-router
+`provideContext(root, appContext, { fetch })` boundary.
+
+## `ctx.fetch` in pages, elements, and controllers
 
 Available on any `Context` obtained via `@context()`; middleware applies automatically:
 
@@ -45,6 +51,31 @@ class UserPage extends HTMLElement {
 }
 ```
 
+Controllers use the same decorator. Managed decorators are activated after
+`attach()`, so start context-dependent work from the handler:
+
+```typescript
+@controller('user-data')
+class UserDataController implements IController<HTMLElement> {
+  element: HTMLElement | null = null;
+  private ctx?: Context;
+
+  attach(element: HTMLElement) { this.element = element; }
+  detach() { this.ctx = undefined; }
+
+  @context()
+  receiveContext(ctx: Context) {
+    this.ctx = ctx;
+    void this.load();
+  }
+
+  async load() {
+    const response = await this.ctx!.fetch('/api/users');
+    // Commit through the host's public API.
+  }
+}
+```
+
 ## Middleware types
 
 ### Request middleware — runs before the `fetch()` call

package/docs/ai/lifecycle.md

@@ -120,7 +120,10 @@ Options object always comes after the property names — works with multiple wat
 
 ## @context()
 
-Receives router context updates. Called whenever the router context changes (navigation, app context update, etc.):
+Receives router context updates on pages, descendant elements, and attached
+controllers. Called whenever the router context changes (navigation, app
+context update, etc.). A controller's managed decorators activate after
+`attach()`, so context-dependent startup belongs in this handler:
 
 ```typescript
 @property({ type: Array }) placards: Placard[] = [];

package/docs/ai/patterns.md

@@ -170,17 +170,17 @@ import { page } from '../router';  // NOT from 'snice'!
 @page({ tag: 'user-page', routes: ['/users/:id'], guards: [isAuthenticated] })
 class UserPage extends HTMLElement {
   @property() id = '';
-  private appContext?: AppContext;
+  private ctx?: Context;
 
   @context()
   handleContext(ctx: Context) {
-    this.appContext = ctx.application;
+    this.ctx = ctx;
     this.requestRender();
   }
 
   @ready()
   async load() {
-    const user = await fetch(`/api/users/${this.id}`).then(r => r.json());
+    const user = await this.ctx!.fetch(`/api/users/${this.id}`).then(r => r.json());
     // ...
   }
 }
@@ -219,9 +219,14 @@ Mock controller for tests, real API controller in production — same element.
 // Controller responds to requests (receives payload, returns result directly)
 @controller('api')
 class API {
+  private ctx!: Context;
+
+  @context()
+  receiveContext(ctx: Context) { this.ctx = ctx; }
+
   @respond('fetch-user')
   async handleFetchUser(payload: { id: string }) {
-    const user = await fetch(`/api/users/${payload.id}`).then(r => r.json());
+    const user = await this.ctx.fetch(`/api/users/${payload.id}`).then(r => r.json());
     return user;  // Direct return, not callback
   }
 }

package/docs/ai/react-integration.md

@@ -33,6 +33,7 @@ Deep import: `import { useRequestHandler } from 'snice/react/useRequestHandler'`
 ## Route Props
 
 - `path`: Route pattern (e.g., `/users/:id`)
+- `order`: Optional numeric specificity tie-break; lower values match first. Equal/omitted values preserve declaration order.
 - `page`: React component (receives params as props) OR Snice tag name string (params set as attributes)
 - `guard`: `(ctx, params) => boolean | Promise<boolean>`
 - `guards`: Array of guard functions (AND logic, sequential, short-circuit)

package/docs/ai/request-response.md

@@ -57,17 +57,21 @@ returns a promise for `T`.
 @controller('processing-controller')
 class ProcessingController implements IController {
   element: HTMLElement | null = null;
+  private ctx!: Context;
   async attach() {}
   async detach() {}
 
+  @context()
+  receiveContext(ctx: Context) { this.ctx = ctx; }
+
   @respond('search', { debounce: 300 })
   async handleSearch(query: { term: string }) {
-    return await fetch(`/api/search?q=${encodeURIComponent(query.term)}`).then(r => r.json());
+    return await this.ctx.fetch(`/api/search?q=${encodeURIComponent(query.term)}`).then(r => r.json());
   }
 
   @respond('analytics', { throttle: 1000 })
   async handleAnalytics(event: any) {
-    return await fetch('/api/track', { method: 'POST', body: JSON.stringify(event) });
+    return await this.ctx.fetch('/api/track', { method: 'POST', body: JSON.stringify(event) });
   }
 }
 ```
@@ -117,17 +121,23 @@ How it works:
 @controller('product-controller')
 class ProductController implements IController {
   element: HTMLElement | null = null;
+  private ctx!: Context;
   async attach() {}
   async detach() {}
 
+  @context()
+  receiveContext(ctx: Context) { this.ctx = ctx; }
+
   @respond('fetch-product')
   async handleFetchProduct(request: { id: string }) {
-    return await fetch(`/api/products/${request.id}`).then(r => r.json());
+    return await this.ctx.fetch(`/api/products/${request.id}`).then(r => r.json());
   }
 }
 ```
 
-Elements never call `fetch()` or manage data directly — they yield requests upward and render whatever comes back. Controllers own the data layer.
+Elements stay visual and yield requests upward. A controller owns application
+behavior specific to the elements it controls; the page still owns element
+orchestration.
 
 ## Options
 
@@ -175,7 +185,7 @@ async *loadData(): Response<void> {
 @respond('load-data')
 async handleLoadData(request: { id: string }) {
   if (!request.id) throw new Error('ID is required');
-  const response = await fetch(`/api/data/${request.id}`);
+  const response = await this.ctx.fetch(`/api/data/${request.id}`);
   if (!response.ok) throw new Error(`API error: ${response.status}`);
   return await response.json();
 }
@@ -189,18 +199,22 @@ async handleLoadData(request: { id: string }) {
 @controller('cached-controller')
 class CachedController implements IController {
   element: HTMLElement | null = null;
+  private ctx!: Context;
   private cache = new Map<string, { data: any; timestamp: number }>();
   private ttl = 60000; // 1 minute
   async attach() {}
   async detach() {}
 
+  @context()
+  receiveContext(ctx: Context) { this.ctx = ctx; }
+
   @respond('fetch-cached')
   async handleFetch(request: { key: string; forceRefresh?: boolean }) {
     const cached = this.cache.get(request.key);
     if (!request.forceRefresh && cached && Date.now() - cached.timestamp < this.ttl) {
       return { data: cached.data, fromCache: true };
     }
-    const data = await fetch(`/api/${request.key}`).then(r => r.json());
+    const data = await this.ctx.fetch(`/api/${request.key}`).then(r => r.json());
     this.cache.set(request.key, { data, timestamp: Date.now() });
     return { data, fromCache: false };
   }

package/docs/ai/routing.md

@@ -58,6 +58,12 @@ Router({
 });
 ```
 
+The same boundary supplies the full Router `Context` to `@context()` methods on
+descendant elements and attached controllers. They use `ctx.fetch` with the
+configured request/response middleware without importing the router or adding
+a reserved field to the application context. `getContextFetch()` is the
+lower-level transport-only lookup for explicit non-router providers.
+
 ### Module structure (avoids circular imports)
 
 ```typescript
@@ -88,7 +94,8 @@ class HomePage extends HTMLElement {
 
 ### `@context()` — method decorator
 
-Receives context updates from the router; called on navigation and on `ctx.update()`.
+Receives context updates from the router on pages, descendant elements, and
+attached controllers; called on navigation and on `ctx.update()`.
 
 ```typescript
 @context(options?: { debounce?: number; throttle?: number; once?: boolean })
@@ -144,7 +151,10 @@ changeTheme(theme: 'light' | 'dark') {
 ```typescript
 interface PageOptions {
   tag: string;                       // custom element tag name
-  routes: string[];                  // route patterns
+  routes: Array<string | {           // strings are the normal form
+    path: string;
+    order?: number;                  // lower wins on a specificity tie
+  }>;
   transition?: Transition;           // page-specific transition
   guards?: Guard | Guard[];          // route guards
   layout?: string | false;           // layout tag, or false to disable
@@ -154,6 +164,25 @@ interface PageOptions {
 
 - Multiple routes: `routes: ['/user', '/users', '/profile']` — all resolve to the same page.
 - Route params: `:name` segments inside a route pattern (see Route Parameters below).
+- Routes are sorted by specificity first. When specificity ties, string entries
+  keep registration order, including their order in one `routes` array.
+- Object notation is optional. Use `{ path, order }` only for an explicit tie-break
+  across registrations; lower `order` values match first. Equal or omitted values
+  still preserve registration order.
+
+```typescript
+@page({
+  tag: 'work-orders-page',
+  routes: ['/work-orders?status=:status', '/work-orders']
+})
+class WorkOrdersPage extends HTMLElement {}
+
+@page({
+  tag: 'override-page',
+  routes: [{ path: '/:section/:item', order: -10 }]
+})
+class OverridePage extends HTMLElement {}
+```
 
 ## Navigation
 
@@ -183,7 +212,7 @@ function Router(options: RouterOptions): {
   page: (pageOptions: PageOptions) => ClassDecorator;
   initialize: () => void;
   navigate: (path: string) => Promise<void>;
-  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[]) => void;
+  register: (route: string, tag: string, transition?: Transition, guards?: Guard | Guard[], layout?: string | false, placard?: Placard | ((ctx: AppContext) => Placard), order?: number) => void;
 }
 ```
 
@@ -191,4 +220,4 @@ function Router(options: RouterOptions): {
 - `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.
+- `register(route, tag, transition?, guards?, layout?, placard?, order?): void` — manually registers a route without `@page`. Lower `order` values win only after specificity ties; omitted/equal order preserves registration order.

package/docs/ai/testing.md

@@ -42,6 +42,27 @@ Gotcha: awaiting `ready` on an element that never connects hangs — append it t
 - `ready` rejects with the first thrown/rejected `@ready()` failure; always await it.
 - jsdom's partial `ElementInternals` is supported; form controls keep native-input/proxy fallback behavior when `setFormValue`/`setValidity` are absent.
 
+## Partial DOM compatibility
+
+In a simulated DOM, opt into Snice's standards compatibility layer from the
+test setup file:
+
+```typescript
+import 'snice/testing/dom';
+```
+
+It capability-tests the current DOM and fills only missing IDL behavior. For
+example, jsdom and some happy-dom versions omit the browser's reflective
+`HTMLElement.autofocus` property for generic custom-element hosts; the adapter
+adds that property without replacing implementations already supplied by the
+runner. Application tests can then use `element.autofocus = true` exactly as
+browser code does.
+
+This adapter does not simulate layout, paint, or real focus navigation. Keep a
+browser-test lane for behavior that depends on those capabilities. For a DOM
+created after module evaluation, call `installDOMTestingCompatibility(scope)`
+from the same module explicitly.
+
 ## Reading the DOM
 
 ```typescript
@@ -80,6 +101,56 @@ await attachController(el, UserController);
 
 To test an element in isolation, swap in a fixture controller that responds on the same channel the production controller uses; the element itself never changes. See request-response.md, controllers.md.
 
+If the controller calls `getContext(this)`, provide its host (or an ancestor)
+with the same application-context shape before attaching it. Release both
+resources after the assertion:
+
+```typescript
+import { attachController, detachController, provideContext } from 'snice';
+
+const host = document.createElement('user-list');
+document.body.append(host);
+const releaseContext = provideContext(host, {
+  api: { listUsers: async () => [{ id: 'u1' }] }
+}, {
+  fetch: async () => new Response(JSON.stringify([{ id: 'u1' }]))
+});
+
+try {
+  await attachController(host, UserController);
+  // assert controller effects
+} finally {
+  await detachController(host);
+  releaseContext();
+  host.remove();
+}
+```
+
+Assigning a value to the host's own `@context` field is not a provider;
+`getContext()` resolves the nearest `provideContext()` boundary.
+When production code uses `getContextFetch()`, pass the test fetch function in
+the same provider's third argument as shown above; `Router` supplies its
+middleware-bound fetch function there in an application.
+
+If the controller uses `@context()`, test it beneath a real `Router` target.
+`provideContext()` intentionally provides application state and transport, not
+navigation notifications; using `Router` exercises the same registration,
+initial catch-up, middleware-aware `ctx.fetch`, updates, and detach cleanup as
+production:
+
+```typescript
+const router = Router({ target: '#fixture', context: { accountId: 'a1' }, fetcher });
+
+@router.page({ tag: 'fixture-page', routes: ['/fixture'] })
+class FixturePage extends HTMLElement {}
+
+router.initialize();
+await router.navigate('/fixture');
+const host = document.createElement('user-list');
+document.querySelector('fixture-page')!.append(host);
+await attachController(host, UserController);
+```
+
 ## Validating source
 
 ```bash

package/docs/bindings.md

@@ -128,7 +128,7 @@ Property bindings preserve type and identity. They are the correct channel for a
 
 ### Live property values
 
-Native controls can mutate their own properties after Snice writes them. Normally, if the bound value has not changed, a later render leaves that user-edited DOM value alone. Wrap a property value in `live()` when the component state must be reasserted even if the bound value itself is unchanged:
+Native controls and stateful custom elements can mutate their own properties after Snice writes them. Normally, if the bound value has not changed, a later render leaves that user- or element-edited DOM value alone. Wrap a property value in `live()` when the owner state must be reasserted even if the bound value itself is unchanged:
 
 ```typescript
 html`<input .value=${live(this.canonicalValue)}>`;

package/docs/cli.md

@@ -55,11 +55,36 @@ npx snice validate    # source analyzer only
 
 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.
+`src/controllers`, and `src/daemons`; keep visual behavior in elements,
+application behavior specific to a set of elements in controllers, and element
+orchestration in pages. A host-free reusable function may remain a plain module
+wherever the project convention places it.
 
 Both accept `--json` for CI.
 
+### Diagnostic codes and `.sniceignore`
+
+Every error, warning, and suggestion has a stable code in human and JSON
+output. When a project intentionally accepts a finding, create `.sniceignore`
+in the project root. Prefer the narrowest entry:
+
+```text
+# One exact diagnostic
+snice/prefer-dispatch-decorator src/components/legacy-filter.ts:42:5
+
+# Every instance in one file
+snice/prefer-dispatch-decorator src/components/legacy-filter.ts
+
+# Every instance in the project
+snice/prefer-dispatch-decorator
+```
+
+`code path:line` is also accepted. Paths are project-relative and entries are
+exact rather than glob patterns. Suppressed diagnostics are omitted from both
+text and JSON output and do not affect the exit status. The file applies to
+`check`, `doctor`, and `validate`, including doctor codes such as
+`snice-skill`.
+
 ## AI Setup
 
 ```bash