snice 7.0.3 → 7.1.0

package/docs/ai/api.md

@@ -15,6 +15,7 @@
 //         attachController(el, MyController) | el.controller = MyController
 //         controller="name" string attr (only channel in raw HTML; still supported everywhere)
 // Class binding: reference-deduped, removes controller attr, attr writes ignored while bound
+@daemon // Explicitly constructed app-context state/lifecycle object; no name or global registration
 @layout('name') // Define page wrapper
 ```
 
@@ -112,13 +113,13 @@ html`
 ```typescript
 @on(event: string | string[], selector?: string, options?: OnOptions)
 // Works in elements + controllers
-// Options: { debounce?, throttle?, preventDefault?, stopPropagation?, once?, capture?, passive?, target?, scope? }
+// Options: { debounce?, throttle?, preventDefault?, stopPropagation?, once?, capture?, passive?, target?, scope?, daemon? }
 // target: CSS selector for shadow DOM event delegation
 // scope: 'global' | selector | EventTarget | () => EventTarget | null — redirects listener attachment
 // Keyboard: 'keydown:Enter', 'keydown.escape', 'keydown:ctrl+s', 'keydown:~Space'
 // Supports both ':' and '.' notation
 
-@dispatch(eventName: string, options?: { debounce?, throttle?, dispatchOnUndefined?, scope?, ...EventInit })
+@dispatch(eventName: string, options?: { debounce?, throttle?, dispatchOnUndefined?, scope?, daemon?, ...EventInit })
 // Fires CustomEvent after method, detail = return value
 // Supports async methods (dispatches after promise resolves)
 // dispatchOnUndefined: false (default) — skips dispatch if method returns undefined
@@ -142,7 +143,7 @@ html`
 ## Communication
 
 ```typescript
-@request(channel: string, options?: { timeout?, discoveryTimeout?, debounce?, throttle?, bubbles?, cancelable? })
+@request(channel: string, options?: { daemon?, timeout?, discoveryTimeout?, debounce?, throttle?, bubbles?, cancelable? })
 // Request pattern using async generator syntax
 // Method must be async generator that yields payload and receives response
 // Returns Promise<T>
@@ -166,7 +167,7 @@ html`
 //   }
 //   // Usage: const user = await this.fetchUser('123');
 
-@respond(channel: string, options?: { debounce?, throttle? })
+@respond(channel: string, options?: { daemon?, debounce?, throttle? })
 // Respond to requests from @request decorators
 // Method receives payload and returns response
 // Works in both elements and controllers
@@ -182,6 +183,14 @@ html`
 //   }
 ```
 
+Daemon addressing:
+```typescript
+const release = provideContext(appRoot, { daemons: { session: new SessionDaemon() } });
+const context = getContext(elementOrController);
+// Consumers use { daemon: 'session' }; daemon methods default to their own private target.
+// Provide before connect/attach. Call release() during app/test teardown.
+```
+
 ## Observers
 
 ```typescript

package/docs/ai/architecture.md

@@ -7,6 +7,7 @@
 - **Pages:** Orchestrate elements, handle URLs
 - **Elements:** Generic visual building blocks — no fetch(), no API calls, no business logic
 - **Controllers:** Specific behavior (data, APIs, business rules) — swappable per element
+- **Daemons:** Explicitly constructed app-owned state/lifecycle objects — addressable through context, never global singletons
 
 **Generic vs Specific:** Elements say *what* they need, controllers decide *how*.
 Swap controllers to change behavior without touching the component.
@@ -16,6 +17,26 @@ Mock controller for tests, real API controller in production — same element.
 - Down: Properties
 - Up: Events
 - Sideways: Request/Response channels
+- App services: daemon-addressed request/response or dispatch/on
+
+## Project Structure
+
+Conventional application layout:
+
+```text
+src/
+  main.ts
+  router.ts
+  pages/          # @page classes; route orchestration and presentation
+  components/     # reusable @element visual components
+  controllers/    # @controller data, API, and reusable business behavior
+  daemons/        # explicitly constructed @daemon state/lifecycle services
+```
+
+Pages may coordinate a route and perform a small one-off load. Move behavior to
+a controller when a page owns several storage/server/timer operations or when
+substantial non-visual logic is copied across pages. `snice check` reports these
+as architecture suggestions, not errors.
 
 ## Rendering System
 
@@ -74,6 +95,15 @@ Mock controller for tests, real API controller in production — same element.
 - Class bindings own the element: attribute writes ignored while a class is bound
 - Native elements: class bindings attach via ControllerPart; string attrs via MutationObserver
 
+**Daemon lifecycle:**
+1. Application constructs an `@daemon` class with `new`
+2. `provideContext(root, { daemons })` activates its private communication target
+3. Elements/controllers resolve the nearest context by string address
+4. Provider release removes daemon handlers and deactivates that target
+- Router provides its `context` through the same mechanism
+- Multiple instances of the same class remain independent
+- No implicit construction, registry scan, singleton, start, or stop hook
+
 ## Router System
 
 **Registration:**
@@ -136,7 +166,7 @@ onChange() { return { value: this.value }; }
 ```typescript
 // Element requests (async generator: yield sends, await receives)
 @request('fetch-data')
-async *fetchData(): any {
+async *fetchData(): Response<Data> {
   return await (yield { id: this.dataId });  // single yield per call
 }
 
@@ -148,6 +178,25 @@ async handleFetch(payload: { id: string }) {
 // Wiring: html`<my-element controller=${MyController}></my-element>` (or controller="my-controller" in raw HTML)
 ```
 
+**Element/Controller ↔ Daemon:** Addressed communication
+```typescript
+@daemon
+class SessionDaemon {
+  @respond('session/get') get() { return this.session; }
+  @dispatch('session/changed') changed() { return this.session; }
+}
+
+const session = new SessionDaemon();
+const release = provideContext(appRoot, { daemons: { session } });
+
+// Consumer imports no daemon implementation class.
+@request('session/get', { daemon: 'session' })
+async *getSession(): Response<Session | null> { return yield {}; }
+
+@on('session/changed', { daemon: 'session' })
+sessionChanged(event: CustomEvent<Session | null>) {}
+```
+
 **Global State:** Context
 ```typescript
 @context() handleContext(ctx: Context) {

package/docs/ai/cli.md

@@ -44,6 +44,15 @@ npx snice validate           # source analyzer only
 `validate` runs the analyzer over source. Catches mistakes that compile but never work:
 - an `@element`-decorated class that does not extend `HTMLElement` (or a Snice element subclass) — Snice registers/renders only element subclasses
 - deep imports that were never released package paths, e.g. `snice/decorators`
+- Router missing `target`, `type`, or a project-wide `initialize()` call
+- a routed class combining `@page` with redundant `@element`
+
+Non-blocking architecture suggestions:
+- `@page` -> `src/pages/`
+- `@element` -> `src/components/`
+- `@controller` -> `src/controllers/`
+- `@daemon` -> `src/daemons/`
+- several external-effect methods or substantial logic repeated across pages -> extract a controller
 
 Both `doctor` and `validate` accept `--json`.
 

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

@@ -371,6 +371,12 @@ Prefer the narrowest scope that works; `'global'` means every instance hears eve
 
 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.