snice 7.2.0 → 7.4.0

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

@@ -1,7 +1,15 @@
 <!-- AI: For the AI-optimized version of this doc, see docs/ai/api.md -->
 # Controllers API Documentation
 
-Controllers handle data fetching, business logic, and server communication separately from visual components. They can be attached 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. They can be
+attached 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.
 
 ## Table of Contents
 - [Basic Usage](#basic-usage)
@@ -111,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,
@@ -125,6 +134,8 @@ Snice attaches immediately. Initial rendering has already completed at that
 point, and waiting for `ready` would otherwise create a self-deadlock because
 `ready` cannot settle until the current handler returns. Attaching to any
 other element still awaits that element's `ready` promise.
+This runtime safeguard does not make attaching a controller to a routed page a
+good architecture; pages should orchestrate directly.
 
 ### Detachment Flow
 
@@ -133,8 +144,9 @@ other element still awaits that element's `ready` promise.
 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
 
@@ -230,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';
@@ -355,11 +367,15 @@ class FormValidationController implements IController<HTMLFormElement> {
 
 ### Data Fetching Controller
 
-Controllers own data fetching. Pass state through the element's public API and
-dispatch outcome events — do not manipulate its rendered DOM. A production
-controller should also prevent an older response from overwriting a newer one:
+A data-fetching controller is appropriate when the fetch is application behavior
+specific to the elements it controls. Pass state through the element's public
+API and dispatch outcome events — do not manipulate its rendered DOM. A
+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 {
@@ -372,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() {
@@ -385,6 +407,7 @@ export class OrdersDataController implements IController<OrdersView> {
     this.requestVersion++;
     this.abortController?.abort();
     this.abortController = undefined;
+    this.ctx = undefined;
   }
 
   async reload() {
@@ -401,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})`);
@@ -439,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/react-integration.md

@@ -147,6 +147,7 @@ Defines a route within `<SniceRouter>`. The `<Route>` component itself renders n
 | Prop | Type | Description |
 |------|------|-------------|
 | `path` | `string` | URL pattern. Supports dynamic segments: `/users/:id`, `/posts/:slug`. |
+| `order` | `number` | Optional specificity tie-break. Lower values match first; equal or omitted values preserve declaration order. |
 | `page` | `Component \| string` | What to render. React component receives route params as props. String = Snice web component tag name (params set as attributes). |
 | `guard` | `(ctx, params) => boolean \| Promise<boolean>` | Single guard function. |
 | `guards` | `function[]` | Multiple guards — all must pass (AND logic). |

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';
@@ -294,7 +303,10 @@ class SettingsPage extends HTMLElement {
 ```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
@@ -317,6 +329,30 @@ class UserPage extends HTMLElement {
 }
 ```
 
+Routes are sorted by specificity first. If specificity ties, registration
+order wins, including the order of plain strings in one `routes` array. Keep
+that compact syntax for normal pages:
+
+```typescript
+@page({
+  tag: 'work-orders-page',
+  routes: ['/work-orders?status=:status', '/work-orders']
+})
+class WorkOrdersPage extends HTMLElement {}
+```
+
+Object notation is optional. Use it only when a route needs an explicit
+tie-break across registrations; lower `order` values match first. Equal or
+omitted values still preserve registration order.
+
+```typescript
+@page({
+  tag: 'override-page',
+  routes: [{ path: '/:section/:item', order: -10 }]
+})
+class OverridePage extends HTMLElement {}
+```
+
 ### Route with Parameters
 
 ```typescript
@@ -815,7 +851,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;
 }
 ```
 

package/docs/testing.md

@@ -47,6 +47,27 @@ element. Snice form controls also retain their native-input/proxy fallback in
 DOM runners such as jsdom that expose only the ARIA subset of
 `ElementInternals`.
 
+## Partial DOM Compatibility
+
+In a simulated DOM, opt into Snice's standards compatibility layer from your
+test setup file:
+
+```typescript
+import 'snice/testing/dom';
+```
+
+The module 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 an implementation already
+provided by the runner. Application tests can then use
+`element.autofocus = true` exactly as browser code does.
+
+The adapter does not simulate layout, paint, or real focus navigation. Keep a
+browser-test lane for behavior that depends on those capabilities. If a runner
+creates its DOM after module evaluation, import and call
+`installDOMTestingCompatibility(scope)` explicitly.
+
 ## Reading the DOM
 
 Use the element's render root directly:
@@ -87,6 +108,56 @@ await attachController(el, UserController);
 
 Swapping a controller is the supported way to test an element in isolation: attach a fixture controller that responds on the same channel the production controller uses, and the element itself never changes. See [Request / Response](./request-response.md) and [Controllers](./controllers.md).
 
+When a controller calls `getContext(this)`, install the same application
+context on its host (or an ancestor) before attachment, then release it during
+cleanup:
+
+```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 the host's own `@context` field does not create 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
 
 Beyond unit tests, the analyzer catches Snice-specific mistakes that still compile:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snice",
-  "version": "7.2.0",
+  "version": "7.4.0",
   "type": "module",
   "description": "A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.",
   "main": "dist/index.cjs",
@@ -24,6 +24,11 @@
       "import": "./dist/transitions.esm.js",
       "require": "./dist/transitions.cjs"
     },
+    "./testing/dom": {
+      "types": "./dist/testing-dom.d.ts",
+      "import": "./dist/testing-dom.esm.js",
+      "require": "./dist/testing-dom.cjs"
+    },
     "./react": {
       "types": "./adapters/react/index.d.ts",
       "import": "./adapters/react/index.js"