snice 7.0.2 → 7.1.0

package/docs/daemons.md

@@ -0,0 +1,200 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/daemons.md -->
+# Daemons
+
+Daemons are ordinary, explicitly constructed objects with state and an
+application-owned lifecycle. The `@daemon` decorator gives each instance a
+private communication target so elements, controllers, and daemons can use
+Snice's two communication models:
+
+- `@request` / `@respond` for one request and one asynchronous response.
+- `@dispatch` / `@on` for ephemeral notifications with zero or more listeners.
+
+`@daemon` does not construct, cache, globally register, start, or stop
+anything.
+
+## Define and provide a daemon
+
+```typescript
+import { daemon, dispatch, on, request, respond, provideContext } from 'snice';
+import type { Response } from 'snice';
+
+@daemon
+class SessionDaemon {
+  session: Session | null = null;
+
+  @respond('get-session')
+  getSession() {
+    return this.session;
+  }
+
+  @on('set-session')
+  setSession(event: CustomEvent<Session>) {
+    this.session = event.detail;
+    this.sessionChanged();
+  }
+
+  @dispatch('session-changed')
+  sessionChanged() {
+    return this.session;
+  }
+}
+
+const session = new SessionDaemon();
+const appContext = {
+  daemons: { session }
+};
+
+const release = provideContext(document.querySelector('#app')!, appContext);
+```
+
+The context key is the daemon's address. The class decorator takes no name,
+avoiding two sources of truth.
+
+Application contexts expose only this daemon surface to Snice:
+
+```typescript
+type DaemonMap = Readonly<Record<string, object>>;
+
+interface AppContext {
+  readonly daemons?: DaemonMap;
+  [key: string]: unknown;
+}
+```
+
+They may still contain application-specific state such as `user`, `theme`, or
+configuration. Extend `AppContext` with those fields to give application code
+their concrete types.
+
+## Router integration
+
+`Router` provides its `context` beneath its target before rendering a page.
+No separate `provideContext()` call is needed:
+
+```typescript
+const session = new SessionDaemon();
+
+const router = Router({
+  target: '#app',
+  type: 'hash',
+  context: {
+    user: null,
+    daemons: { session }
+  }
+});
+```
+
+`provideContext(root, context)` is the same public mechanism used internally
+by Router. Use it for applications without Router and for isolated tests. It
+returns an idempotent cleanup function.
+
+`getContext(elementOrController)` returns the raw application context visible
+to that participant. It is separate from the method-form `@context()`, which
+receives Router navigation updates.
+
+## Communicate from elements and controllers
+
+Consumers use the context address and never import the daemon implementation:
+
+```typescript
+@element('session-view')
+class SessionView extends HTMLElement {
+  @request<Session | null>('get-session', { daemon: 'session' })
+  async *loadSession(): Response<Session | null> {
+    return yield {};
+  }
+
+  @dispatch('set-session', { daemon: 'session' })
+  setSession(session: Session) {
+    return session;
+  }
+
+  @on('session-changed', { daemon: 'session' })
+  sessionChanged(event: CustomEvent<Session | null>) {
+    this.renderSession(event.detail);
+  }
+}
+```
+
+Controllers resolve the context through their attached host element, so the
+same syntax works in controller methods.
+
+The reverse direction is also supported. A daemon's `@request` dispatches on
+its own communication target, while an element or controller may install a
+responder there:
+
+```typescript
+@daemon
+class SessionDaemon {
+  @request<boolean>('confirm-logout')
+  async *confirmLogout(): Response<boolean> {
+    return yield {};
+  }
+}
+
+class SessionView extends HTMLElement {
+  @respond('confirm-logout', { daemon: 'session' })
+  confirmLogout() {
+    return window.confirm('Log out?');
+  }
+}
+```
+
+As with DOM-scoped request channels, only one responder should own a daemon
+request channel.
+
+## Resolution and lifecycle
+
+Resolution has one path:
+
+```text
+element/controller
+  -> nearest explicitly provided application context
+  -> context.daemons[name]
+  -> that instance's private communication target
+```
+
+There is no global fallback, implicit construction, registry scan, or delayed
+registration.
+
+- Construct every daemon explicitly with `new`.
+- Provide the context before connecting elements or attaching controllers.
+  `@on` and `@respond` install listeners at those lifecycle boundaries.
+- `@request` and `@dispatch` resolve their daemon when invoked.
+- Disconnecting an element or detaching a controller removes its daemon
+  listeners automatically.
+- Releasing the context deactivates its daemon communication. A later provision
+  starts with a fresh event target.
+- The same daemon class may have any number of independently provided
+  instances.
+- The same name may resolve to different instances under different context
+  roots.
+
+Missing contexts, missing daemon names, undecorated values, and inactive
+daemon instances produce explicit errors or setup warnings. `daemon` and DOM
+`scope` options are mutually exclusive. Selector delegation is not available
+on a daemon target because it is not a DOM tree.
+
+## Testing
+
+Each test owns its instance, context root, and cleanup:
+
+```typescript
+const root = document.createElement('div');
+document.body.appendChild(root);
+
+const session = new SessionDaemon();
+const release = provideContext(root, {
+  daemons: { session }
+});
+
+const view = document.createElement('session-view');
+root.appendChild(view);
+await view.ready;
+
+expect(await view.loadSession()).toBeNull();
+
+root.remove();
+release();
+```
+
+No shared singleton state or framework reset API is involved.

package/docs/events.md

@@ -7,6 +7,7 @@ Event handling in Snice provides two powerful approaches: **template event synta
 - [Template Event Syntax (Preferred for Elements)](#template-event-syntax-preferred-for-elements)
 - [@on Decorator](#on-decorator)
 - [@dispatch Decorator](#dispatch-decorator)
+- [Event Bus](#event-bus)
 - [Custom Events](#custom-events)
 - [Event Delegation](#event-delegation)
 - [Keyboard Shortcuts](#keyboard-shortcuts)
@@ -413,6 +414,9 @@ interface OnOptions {
 
   // Where to attach the listener (see scope section below)
   scope?: 'global' | string | EventTarget | ((this: HTMLElement) => EventTarget | null);
+
+  // Named daemon from the nearest provided app context
+  daemon?: string;
 }
 ```
 
@@ -460,6 +464,9 @@ re-resolves and re-attaches, so resolver-based scopes track DOM moves correctly.
 `scope` is compatible with the delegation selector — the listener attaches on the
 scoped target and still matches the selector when an event fires within it.
 
+`daemon` is a separate, non-DOM target. It cannot be combined with `scope` and does
+not support selector delegation. See [Daemons](./daemons.md).
+
 #### Throttling
 
 ```typescript
@@ -608,13 +615,15 @@ interface DispatchOptions extends EventInit {
   throttle?: number;             // Throttle dispatch by ms
   // Where to dispatch the event (see scope section below)
   scope?: 'global' | string | EventTarget | ((this: HTMLElement) => EventTarget | null);
+  // Named daemon from the nearest provided app context
+  daemon?: string;
 }
 ```
 
 #### scope — controlling the dispatch target
 
-By default, `@dispatch` calls `this.dispatchEvent(event)` — the event originates from
-the host element. The `scope` option redirects the dispatch to another target so the
+By default, `@dispatch` originates from the element or a controller's host; on a
+daemon it uses that instance's private target. The `scope` option redirects a DOM dispatch so the
 event behaves as if it originated there. Use this with `@on({ scope })` to express
 cross-cutting events without going through bubbling.
 
@@ -650,6 +659,10 @@ the event is **not dispatched** and a `console.warn` is emitted. The method's re
 value still flows through `dispatchOnUndefined` / `debounce` / `throttle` semantics
 before the scope check.
 
+Use `{ daemon: 'session' }` to dispatch on an explicitly provided daemon's private
+communication target. `daemon` and `scope` are mutually exclusive. See
+[Daemons](./daemons.md).
+
 ### Debounce/Throttle
 
 ```typescript
@@ -715,6 +728,83 @@ class ColorPicker extends HTMLElement {
 }
 ```
 
+## Event Bus
+
+Snice has no bus object and no singleton. A bus is `@dispatch` publishing upward and
+`@on` subscribing at a chosen ancestor -- the scope is a DOM node, so it is created and
+torn down with the DOM.
+
+There are two ways to publish, and the choice decides who can hear it.
+
+**Bubble up from the host.** `@dispatch` is `bubbles: true, composed: true` by default, so
+the event crosses shadow boundaries and passes every ancestor on its way to `document`.
+Use this when the event is about *this* element and ancestors may care.
+
+```typescript
+@element('product-tile')
+class ProductTile extends HTMLElement {
+  @dispatch('bus:cart-added')
+  addToCart(sku: string) {
+    return { sku, qty: 1 };
+  }
+}
+```
+
+**Dispatch directly on a scope.** `@dispatch` takes the same `scope` option as `@on`, which
+fires the event *on* that target instead of bubbling from the host. Use this when the
+subscriber is not an ancestor -- a sibling subtree, or a host that may be detached.
+
+```typescript
+@dispatch('bus:cart-added', { scope: 'global' })   // dispatched on document
+add(id: string) { return { id }; }
+```
+
+Subscribe at the scope you want to share.
+
+```typescript
+// App-wide: listens on document
+@on('bus:cart-added', { scope: 'global' })
+onCartAdded(e: CustomEvent) { /* ... */ }
+
+// Feature-scoped: listens on the nearest <cart-shell> ancestor, so a second
+// <cart-shell> elsewhere on the page keeps its own traffic
+@on('bus:cart-added', { scope: 'cart-shell' })
+onCartAdded(e: CustomEvent) { /* ... */ }
+```
+
+Choosing a scope:
+
+| Reach | `scope` | Use when |
+|---|---|---|
+| Whole document | `'global'` | Genuinely app-wide: auth expiry, theme change, save shortcut |
+| A feature subtree | selector string | The event belongs to one shell and must not leak to a sibling instance |
+| A specific node | `EventTarget` / resolver | You already hold the node, or the target moves and must re-resolve |
+
+Prefer the narrowest scope that works. `'global'` means every instance on the page hears
+every message, which is what makes singleton buses hard to reason about.
+
+Match the two halves. A bubbling publish only reaches subscribers that sit on the host's
+ancestor chain; if the subscriber lives in a sibling subtree, scope the dispatch too so
+both meet on the same node. See
+[scope on @dispatch](#scope-controlling-the-dispatch-target).
+
+Name events so the routing is visible at the call site -- the `bus:` prefix above is a
+convention, not a framework feature. Any string works.
+
+Teardown is automatic: the listener is removed on disconnect from whichever target it
+resolved to, and re-resolved on reconnect, so subscribers follow the host when it moves.
+If a selector scope matches no ancestor the listener is skipped with a `console.warn`
+rather than silently binding to the wrong node. See
+[scope](#scope-controlling-the-listener-target) for the full resolution table.
+
+For a request that needs an answer rather than a broadcast, use
+[@request / @respond](./request-response.md) instead.
+
+For app-owned state with an explicit lifecycle, provide an `@daemon` instance and
+use `{ daemon: 'name' }` on both publishers and subscribers. This keeps consumers
+decoupled from the implementation class without introducing a global singleton.
+See [Daemons](./daemons.md).
+
 ## Custom Events
 
 ### Dispatching Manually

package/docs/request-response.md

@@ -1,7 +1,8 @@
-<!-- AI: For the AI-optimized version of this doc, see docs/ai/patterns.md -->
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/request-response.md -->
 # Request/Response API Documentation
 
-Request/Response provides request/response communication between elements and controllers using async generators.
+Request/Response provides request/response communication between elements,
+controllers, and explicitly provided daemons using async generators.
 
 ## Table of Contents
 - [Why Request/Response?](#why-request-response)
@@ -45,6 +46,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 in ms (default: 120000ms = 2 minutes)
   discoveryTimeout?: number; // Handler discovery timeout in ms (default: 50ms)
   debounce?: number;        // Debounce requests by specified ms
@@ -54,15 +56,21 @@ interface RequestOptions extends EventInit {
 }
 
 interface RespondOptions {
+  daemon?: string;     // Install responder on named daemon target
   debounce?: number;   // Debounce responses by specified ms
   throttle?: number;   // Throttle responses by specified ms
 }
 
-// Recommended type helper for request generator return types:
-type RequestResult<T> = AsyncGenerator<any, T, any> | Promise<T>;
-// Define this in your project — it satisfies both the generator and the caller
+// 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. `Response<T>` is the pragmatic annotation for that
+boundary: it keeps strict projects usable while documenting the response value
+for readers and tooling. At runtime, calling the decorated method returns a
+promise for `T`.
+
 #### Response Debounce/Throttle
 
 Response handlers can be debounced or throttled:
@@ -92,8 +100,7 @@ Elements use async generators to make requests. The element stays visual — it
 
 ```typescript
 import { element, request, property, render, html } from 'snice';
-
-type RequestResult<T> = AsyncGenerator<any, T, any> | Promise<T>;
+import type { Response } from 'snice';
 
 @element('product-card')
 class ProductCard extends HTMLElement {
@@ -102,7 +109,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;
@@ -164,7 +171,7 @@ The timeout system has **two separate timeouts**:
   discoveryTimeout: 50,   // 50ms to find handler
   timeout: 30000          // 30s for actual processing
 })
-async *compute(): RequestResult<any> {
+async *compute(): Response<any> {
   return await (yield data);
 }
 ```
@@ -174,13 +181,13 @@ async *compute(): RequestResult<any> {
 ```typescript
 // Debounce: wait for typing to stop before searching
 @request('search', { debounce: 300 })
-async *search(): RequestResult<any[]> {
+async *search(): Response<any[]> {
   return await (yield { query: this.searchTerm });
 }
 
 // Throttle: limit analytics to 1 per second
 @request('track', { throttle: 1000 })
-async *trackEvent(): RequestResult<void> {
+async *trackEvent(): Response<void> {
   await (yield { event: 'scroll', position: window.scrollY });
 }
 ```
@@ -196,7 +203,7 @@ class SafeLoader extends HTMLElement {
   @property() data: any = null;
 
   @request('load-data', { timeout: 5000 })
-  async *loadData(): RequestResult<void> {
+  async *loadData(): Response<void> {
     try {
       this.data = await (yield { id: this.dataId });
       this.error = '';
@@ -290,7 +297,7 @@ class LiveTicker extends HTMLElement {
   @property() symbol = 'BTC';
 
   @request('subscribe-ticker')
-  async *subscribe(): RequestResult<void> {
+  async *subscribe(): Response<void> {
     await (yield { symbol: this.symbol });
   }
 

package/docs/routing.md

@@ -35,7 +35,7 @@ interface RouterOptions {
   document?: Document;               // Override document object (for testing)
   transition?: Transition;           // Global transition config
   layout?: string;                   // Default layout for all pages
-  context?: any;                     // Router context object (shared state)
+  context?: any;                     // App context (shared state and optional daemons)
   fetcher?: Fetcher;                 // Optional fetch middleware (see docs/fetcher.md)
 }
 ```
@@ -67,6 +67,27 @@ const { page, initialize } = Router({
 });
 ```
 
+Router provides this application context beneath its target before it connects a
+page. That includes explicitly constructed daemon instances:
+
+```typescript
+const session = new SessionDaemon();
+
+Router({
+  target: '#app',
+  type: 'hash',
+  context: {
+    user: null,
+    daemons: { session }
+  }
+});
+```
+
+This uses the same `provideContext(root, context)` mechanism available to apps
+without Router. Descendant elements and attached controllers address the instance
+as `{ daemon: 'session' }`; they do not import `SessionDaemon`. See
+[Daemons](./daemons.md).
+
 ## Page Components
 
 ### Basic Page
@@ -806,6 +827,9 @@ navigate(path: string): Promise<void>
 
 Navigates to the specified path. Uses hash (#) or pushstate depending on router type.
 
+Do not combine `@page` with `@element` on the same class. `@page` already
+registers the custom element and applies Snice element behavior.
+
 ### initialize()
 
 ```typescript

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "snice",
-  "version": "7.0.2",
+  "version": "7.1.0",
   "type": "module",
-  "description": "A decorator-driven web component library with differential rendering, routing, controllers, and 130+ ready-made UI components. Use as much or as little as you want. Zero dependencies, works anywhere.",
+  "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",
   "module": "dist/index.esm.js",
   "browser": "dist/index.iife.js",
@@ -112,11 +112,11 @@
     "build:distribution": "rm -rf dist && npm run generate:metadata && rollup -c && npm run build:types && node tooling/build/embed-sourcemap-sources.mjs dist",
     "build:types": "tsc --project packages/components/tsconfig.json --emitDeclarationOnly && cp packages/components/custom-elements.d.ts dist/components/custom-elements.d.ts",
     "prebuild:cdn": "test -f dist/index.esm.js || npm run build:distribution",
-    "build:cdn": "rollup -c rollup.config.cdn.js && cp dist/cdn/*/snice-*.min.js website/public/components/ && node tooling/website/update-cdn-sizes.js",
+    "build:cdn": "rollup -c rollup.config.cdn.js && node tooling/website/sync-component-assets.js && node tooling/website/update-cdn-sizes.js",
     "prebuild:react": "test -f dist/index.d.ts || npm run build:distribution",
     "build:react": "npm run generate:react-adapters && tsc --project adapters/react/tsconfig.json && node tooling/build/embed-sourcemap-sources.mjs adapters/react",
     "build:testing": "rollup -c rollup.config.test.js && node tooling/build/embed-sourcemap-sources.mjs dist",
-    "build:website": "node tooling/website/build-website.js && node tooling/website/build-showcases.js",
+    "build:website": "node tooling/website/sync-component-assets.js && node tooling/website/build-website.js && node tooling/website/build-showcases.js",
     "build:website:full": "npm run build:cdn && npm run build:website",
     "build:storybook": "storybook build",
     "generate:metadata": "node tooling/generators/generate-component-metadata.js && node tooling/generators/generate-analyzer-contracts.js",
@@ -142,6 +142,8 @@
     "test:react": "npm run build:react && npm run test:react:prepared",
     "test:react:prepared": "vitest run tests/react-adapters",
     "test:website": "vitest run tests/website.test.ts",
+    "gauntlet": "node tooling/testing/run-gauntlet.js",
+    "postinstall": "node ./bin/postinstall.js",
     "test:browser": "npm run test:browser:framework && npm run test:browser:website",
     "test:browser:framework": "npm run build:distribution && npm run test:browser:framework:prepared",
     "test:browser:framework:prepared": "node tooling/testing/run-live-tests.js --workers=4",