snice 7.3.0 → 7.4.0

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 })

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

@@ -62,6 +62,29 @@ 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

package/docs/components/badge.md

@@ -31,6 +31,10 @@ The badge component displays notification indicators, status markers, and counts
 | `showZero` (attr: `show-zero`) | `boolean` | `false` | Render a zero count instead of hiding the badge |
 | `offset` | `number` | `0` | Offset in pixels from default position |
 
+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
 
 | Method | Arguments | Description |

package/docs/components/pagination.md

@@ -81,16 +81,19 @@ snice-pagination::part(button) {
 
 ```typescript
 import 'snice/components/pagination/snice-pagination';
+import type { PaginationChangeDetail } from 'snice/components/pagination/snice-pagination.types';
 ```
 
 ```html
 <snice-pagination current="1" total="10"></snice-pagination>
+```
 
-<script type="module">
-  document.querySelector('snice-pagination').addEventListener('pagination-change', (e) => {
-    console.log('Page:', e.detail.page, 'Previous:', e.detail.previousPage);
-  });
-</script>
+```typescript
+const pagination = document.querySelector('snice-pagination')!;
+pagination.addEventListener('pagination-change', (event) => {
+  const { detail } = event as CustomEvent<PaginationChangeDetail>;
+  console.log('Page:', detail.page, 'Previous:', detail.previousPage);
+});
 ```
 
 ## Examples

package/docs/components/segmented-control.md

@@ -17,7 +17,7 @@ A multi-option switcher with a sliding indicator. One option is selected at a ti
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `value` | `string` | `''` | Selected option value |
+| `value` | `string` | `''` | Selected option value; user selection updates it before `value-change` |
 | `options` | `SegmentedControlOption[]` | `[]` | Array of `{ value, label, icon?, disabled? }` (JS only) |
 | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Control size |
 | `disabled` | `boolean` | `false` | Disables the entire control |
@@ -39,6 +39,10 @@ interface SegmentedControlOption {
 |-------|--------|-------------|
 | `value-change` | `{ value: string, previousValue: string, option: SegmentedControlOption, control }` | Selection changed |
 
+`value` is self-mutating. If an owning template must reassert the same
+controlled value after user selection, bind it as `.value=${live(value)}` so
+the next owner render compares against the control's current property.
+
 ## CSS Parts
 
 | Part | Description |

package/docs/controllers.md

@@ -119,13 +119,14 @@ interface IController<T extends HTMLElement = HTMLElement> {
 
 1. Controller instance is created
 2. `element` property is set
-3. Router context is passed (if available)
+3. Router application context is passed (if available)
 4. Element's `ready` promise is awaited
 5. `attach()` method is called
-6. Observers are set up
-7. Channel/response handlers are set up
-8. Event handlers are set up
-9. `controller-attached` event is dispatched
+6. `@context` handlers are registered and caught up with the current Router context
+7. Observers are set up
+8. Channel/response handlers are set up
+9. Event handlers are set up
+10. `controller-attached` event is dispatched
 
 The step-4 wait has one safe exception: when an element calls
 `await attachController(this, ControllerClass)` from its own `@ready` handler,
@@ -143,8 +144,9 @@ good architecture; pages should orchestrate directly.
 3. Observers are cleaned up
 4. Channel/response handlers are cleaned up
 5. Event handlers are cleaned up
-6. Controller scope is cleaned up
-7. `controller-detached` event is dispatched
+6. `@context` handlers are cleaned up
+7. Controller scope is cleaned up
+8. `controller-detached` event is dispatched
 
 ### Example with Lifecycle Logging
 
@@ -240,7 +242,7 @@ class TableController implements IController<HTMLTableElement> {
 
 ## Resource Cleanup
 
-The framework auto-cleans `@on`, `@observe`, and `@respond` handlers. Clean up your own resources (WebSockets, timers, manual listeners) in `detach`:
+The framework auto-cleans `@on`, `@observe`, `@respond`, and `@context` handlers. Clean up your own resources (WebSockets, timers, manual listeners) in `detach`:
 
 ```typescript
 import { controller, IController } from 'snice';
@@ -372,6 +374,8 @@ production controller should also prevent an older response from overwriting a
 newer one:
 
 ```typescript
+import { context, type Context } from 'snice';
+
 interface Order { id: string; total: number }
 
 interface OrdersView extends HTMLElement {
@@ -384,12 +388,18 @@ interface OrdersView extends HTMLElement {
 @controller('orders-data')
 export class OrdersDataController implements IController<OrdersView> {
   element: OrdersView | null = null;
+  private ctx?: Context;
   private abortController?: AbortController;
   private requestVersion = 0;
 
-  async attach(element: OrdersView) {
+  attach(element: OrdersView) {
     this.element = element;
-    await this.reload();
+  }
+
+  @context()
+  receiveContext(ctx: Context) {
+    this.ctx = ctx;
+    void this.reload();
   }
 
   async detach() {
@@ -397,6 +407,7 @@ export class OrdersDataController implements IController<OrdersView> {
     this.requestVersion++;
     this.abortController?.abort();
     this.abortController = undefined;
+    this.ctx = undefined;
   }
 
   async reload() {
@@ -413,7 +424,9 @@ export class OrdersDataController implements IController<OrdersView> {
     host.empty = false;
 
     try {
-      const response = await fetch('/api/orders', {
+      const ctx = this.ctx;
+      if (!ctx) throw new Error('OrdersDataController requires Router context');
+      const response = await ctx.fetch('/api/orders', {
         signal: abortController.signal
       });
       if (!response.ok) throw new Error(`Orders request failed (${response.status})`);
@@ -451,6 +464,12 @@ export class OrdersDataController implements IController<OrdersView> {
 }
 ```
 
+`@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()`.
+
 The element owns presentation for every state:
 
 ```typescript

package/docs/events.md

@@ -610,7 +610,7 @@ class StatusIndicator extends HTMLElement {
 
 ```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 section below)
@@ -807,7 +807,16 @@ See [Daemons](./daemons.md).
 
 ## Custom Events
 
-### Dispatching Manually
+Prefer `@dispatch` for a static custom event emitted from a Snice element or a
+controller's host. The decorator supplies the standard bubbling and composed
+behavior, uses the method return value as `detail`, and keeps debounce,
+throttle, and scope declarative.
+
+Manual dispatch remains valid when code needs direct access to the Event
+object, a dynamic event name, the cancellation boolean returned by
+`dispatchEvent()`, or a target other than the Snice host.
+
+### Manual Escape Hatch
 
 ```typescript
 @element('manual-dispatcher')

package/docs/fetcher.md

@@ -51,7 +51,13 @@ const router = Router({
 router.initialize();
 ```
 
-## Using Context.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.
+
+## Using Context.fetch in Pages, Elements, and Controllers
 
 Once configured, `ctx.fetch` is available in all pages and components that use the `@context` decorator:
 
@@ -80,6 +86,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

package/docs/lifecycle.md

@@ -198,7 +198,11 @@ The options object always comes after the property names, so it works with multi
 
 ## @context() Decorator
 
-Receive router context updates. The decorated method is called whenever the router context changes (navigation, app context update, etc.):
+Receive router context updates on pages, descendant elements, and attached
+controllers. The decorated method is 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
 import { element, context, property, render, html } from 'snice';

package/docs/request-response.md

@@ -79,17 +79,21 @@ Response handlers can be debounced or throttled:
 @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) });
   }
 }
 ```
@@ -139,23 +143,29 @@ class ProductCard extends HTMLElement {
 Controllers handle requests — this is where business logic, API calls, and data management belong:
 
 ```typescript
-import { controller, respond, IController } from 'snice';
+import { context, controller, respond, IController, type Context } from 'snice';
 
 @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 }) {
-    const response = await fetch(`/api/products/${request.id}`);
+    const response = await this.ctx.fetch(`/api/products/${request.id}`);
     return await response.json();
   }
 }
 ```
 
-**Architecture:** Elements never call `fetch()` or manage data directly. They yield requests upward and render whatever comes back. Controllers own the data layer.
+**Architecture:** Elements stay visual and yield requests upward. A controller
+owns application behavior specific to the elements it controls; the page still
+owns element orchestration.
 
 ## Request/Response Options
 
@@ -238,16 +248,20 @@ class SafeLoader extends HTMLElement {
 @controller('resilient-controller')
 class ResilientController implements IController {
   element: HTMLElement | null = null;
+  private ctx!: Context;
   async attach() {}
   async detach() {}
 
+  @context()
+  receiveContext(ctx: Context) { this.ctx = ctx; }
+
   @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}`);
     }
@@ -265,12 +279,16 @@ class ResilientController implements IController {
 @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);
@@ -278,7 +296,7 @@ class CachedController implements IController {
       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/routing.md

@@ -88,6 +88,12 @@ without Router. Descendant elements and attached controllers address the instanc
 as `{ daemon: 'session' }`; they do not import `SessionDaemon`. See
 [Daemons](./daemons.md).
 
+That provider 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.
+
 ## Page Components
 
 ### Basic Page
@@ -135,7 +141,10 @@ class HomePage extends HTMLElement {
 
 ### Page with Context
 
-The `@context()` decorator is a **method decorator** that receives context updates from the router. The method is called whenever navigation occurs, with a Context object containing application state and navigation data.
+The `@context()` decorator is a **method decorator** that receives context
+updates from the router on pages, descendant elements, and attached
+controllers. The method is called whenever navigation occurs, with a Context
+object containing application state and navigation data.
 
 ```typescript
 import { context, render, html, Context } from 'snice';