snice 7.0.3 → 7.1.1

package/.agents/skills/snice/SKILL.md

@@ -8,6 +8,10 @@ description: Build, modify, debug, or review applications and components that us
 Use the documentation shipped with the exact installed Snice version. Do not
 reconstruct Snice APIs from Lit or generic web-component conventions.
 
+If a consuming project does not yet contain `.agents/skills/snice/SKILL.md`,
+run `npx snice init-ai` from that project root before writing Snice code. This
+installs version-matched guidance plus `AGENTS.md` and `CLAUDE.md` pointers.
+
 ## Locate the reference
 
 Use the first directory that exists:

package/.agents/skills/snice/references/core-kitchen-sink.ts

@@ -9,6 +9,7 @@
  */
 import {
   ContextAwareFetcher,
+  type Response,
   SniceElement,
   adopted,
   classMap,
@@ -19,6 +20,7 @@ import {
   controller,
   createRequestHandler,
   css,
+  daemon,
   debounce,
   dispatch,
   dispose,
@@ -81,6 +83,23 @@ interface KitchenContext extends AppContext {
   token: string;
 }
 
+@daemon
+class KitchenDaemon {
+  status = 'ready';
+
+  @respond('daemon-status')
+  currentStatus() {
+    return this.status;
+  }
+
+  @dispatch('daemon-status-changed')
+  statusChanged() {
+    return this.status;
+  }
+}
+
+const kitchenDaemon = new KitchenDaemon();
+
 const fetcher = new ContextAwareFetcher();
 fetcher.use('request', function (request, next) {
   const { token } = this.application as KitchenContext;
@@ -96,7 +115,11 @@ export const { page, navigate, initialize } = Router({
   target: '#app',
   type: 'hash',
   layout: 'kitchen-shell',
-  context: { user: null, token: '' } satisfies KitchenContext,
+  context: {
+    user: null,
+    token: '',
+    daemons: { kitchen: kitchenDaemon }
+  } satisfies KitchenContext,
   fetcher
 });
 
@@ -220,6 +243,21 @@ class KitchenView extends SniceElement {
     return user as User;
   }
 
+  @request('daemon-status', { daemon: 'kitchen' })
+  async *loadDaemonStatus(): Response<string> {
+    return await (yield {});
+  }
+
+  async normalizedDaemonStatus() {
+    const status: string = await this.loadDaemonStatus();
+    return status.toUpperCase();
+  }
+
+  @on('daemon-status-changed', { daemon: 'kitchen' })
+  daemonStatusChanged(event: CustomEvent<string>) {
+    this.status.text = event.detail;
+  }
+
   @observe('resize', '.panel')
   resized(_entries: ResizeObserverEntry[]) {}
 

package/README.md

@@ -62,7 +62,7 @@ class RealTimeUserLoader { ... }
 @on('click', 'button') fn(e: Event) { ... }
 @dispatch('value-changed') fn(val: string) => Event Detail
 @context() fn(ctx: Context) { ... }
-@request('user') fn(): () => Request;
+@request('user') async *fn(): Response<User> { return yield {}; }
 @respond('user') fn(req) => Response;
 ```
 
@@ -228,6 +228,11 @@ html`<user-list controller=${RealTimeUserLoader}></user-list>`
 html`<user-list controller=${CachedUserLoader}></user-list>`
 ```
 
+Class bindings reflect the decorator name in the DOM (for example,
+`controller="real-time-user-loader"`) so DevTools still shows which controller
+is active. The class reference remains the attachment authority; the reflected
+attribute is diagnostic and does not cause a second registry attachment.
+
 Registry names still work everywhere, and are the channel for raw HTML markup:
 
 ```html
@@ -510,8 +515,8 @@ This pattern is useful when:
 
 ```typescript
 // Controller responds to requests
-@element('app-controller')
-class AppController extends HTMLElement {
+@controller('app-controller')
+class AppController {
   private currentUser = { name: 'Alice', role: 'admin' };
 
   @respond('user')
@@ -523,32 +528,75 @@ class AppController extends HTMLElement {
 // Element makes requests
 @element('user-badge')
 class UserBadge extends HTMLElement {
+  @state() private user: User | null = null;
+
   @request('user')
-  getUser!: () => any;
+  async *getUser(): Response<User> {
+    return yield {};
+  }
 
   @ready()
-  init() {
-    const user = this.getUser();
+  async init() {
+    const user = await this.getUser();
+    this.user = user;
     console.log('Current user:', user);
   }
 
   @render()
   renderContent() {
-    const user = this.getUser();
-    return html`<div>Welcome, ${user.name}!</div>`;
+    return html`<div>Welcome, ${this.user?.name ?? 'Guest'}!</div>`;
   }
 }
-```
 
-**Usage:**
-```html
-<app-controller>
-  <user-badge></user-badge>
-</app-controller>
+// A parent template attaches the responder by class.
+html`<user-badge controller=${AppController}></user-badge>`;
 ```
 
 See [Request/Response documentation](./docs/request-response.md) for details.
 
+### Daemons
+
+Daemons are explicitly constructed, app-owned objects with state and a lifecycle.
+They support both request/response and event communication without requiring an
+element or a global singleton:
+
+```typescript
+@daemon
+class SessionDaemon {
+  @respond('get-session')
+  getSession() { return this.session; }
+
+  @dispatch('session-changed')
+  changed() { return this.session; }
+}
+
+const session = new SessionDaemon();
+const release = provideContext(appRoot, { daemons: { session } });
+
+// Elements/controllers use the context address, not SessionDaemon.
+@request('get-session', { daemon: 'session' })
+async *loadSession(): Response<Session | null> {
+  return yield {};
+}
+```
+
+Router provides its `context` through the same mechanism. There is no implicit
+construction or global registry, and multiple instances remain independent. See
+[Daemons](./docs/daemons.md) for lifecycle, testing, and both communication models.
+
+### Project Organization
+
+Keep application roles easy to find: pages in `src/pages/`, reusable visual
+elements in `src/components/`, attached behavior in `src/controllers/`, and
+app-owned services in `src/daemons/`. `src/router.ts` constructs and exports the
+router pieces; `src/main.ts` imports page modules and calls `initialize()`.
+
+Pages orchestrate a route. When several storage/server/timer operations collect
+inside one page, or substantial non-visual logic is repeated across pages, move
+that behavior into a controller. `snice check` reports folder and extraction
+guidance as non-blocking suggestions while treating broken Router construction
+as an error.
+
 ## Template Syntax
 
 ### Auto-Rendering with Differential Updates
@@ -939,6 +987,7 @@ See [DEVELOPMENT.md](./DEVELOPMENT.md) for build system details
 - [Declarative Rendering](./docs/rendering.md) - Bindings, control flow, reactivity, render roots, and async values
 - [Binding Channels](./docs/bindings.md) - Detailed DOM destinations, value/removal rules, events, spreads, sentinels, and forms
 - [Controllers API](./docs/controllers.md) - Data fetching, business logic, and controller patterns
+- [Daemons](./docs/daemons.md) - Explicit app-context state/lifecycle objects with request/response and event communication
 - [Routing API](./docs/routing.md) - Router setup, pages, route params, and navigation
 - [Guards and Layouts](./docs/guards-and-layouts.md) - Protecting routes, page wrappers, and transitions
 - [Placards API](./docs/placards.md) - Rich page metadata for dynamic navigation and discovery
@@ -952,6 +1001,7 @@ See [DEVELOPMENT.md](./DEVELOPMENT.md) for build system details
 
 ### Developer Documentation
 - [DEVELOPMENT.md](./DEVELOPMENT.md) - Build system, testing, and contributing to Snice
+- [Dumb-agent gauntlet](./.ai/gauntlet.md) - Maintainer-only local model loop for hardening `snice check`
 
 ## License
 

package/adapters/react/SniceProvider.js

@@ -1,6 +1,6 @@
 /*!
- * snice v7.0.2
- * 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.
+ * snice v7.1.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
  *

package/adapters/react/SniceRouter.js

@@ -1,6 +1,6 @@
 /*!
- * snice v7.0.2
- * 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.
+ * snice v7.1.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
  *

package/adapters/react/matchRoute.js

@@ -1,6 +1,6 @@
 /*!
- * snice v7.0.2
- * 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.
+ * snice v7.1.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
  *

package/adapters/react/useRequestHandler.js

@@ -1,6 +1,6 @@
 /*!
- * snice v7.0.2
- * 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.
+ * snice v7.1.0
+ * A decorator-driven web component library with routing, controllers, daemons, and 130+ UI components. For better coding-agent results, run npx snice init-ai.
  * (c) 2024
  * Released under the MIT License.
  *

package/bin/analyzer-contracts.js

@@ -18,7 +18,7 @@ export const ANALYZER_CONTRACTS = {
     "componentFamilies": 134,
     "componentModules": 188,
     "reactWrappers": 193,
-    "rootExports": 110
+    "rootExports": 115
   },
   "rootExports": [
     "AdoptedOptions",
@@ -29,6 +29,7 @@ export const ANALYZER_CONTRACTS = {
     "ContextOptions",
     "ControllerClass",
     "CreateRequestHandlerOptions",
+    "DaemonMap",
     "DispatchOptions",
     "Duration",
     "ElementOptions",
@@ -57,6 +58,7 @@ export const ANALYZER_CONTRACTS = {
     "RequestRoute",
     "RequestRouteMap",
     "RespondOptions",
+    "Response",
     "ResponseMiddleware",
     "RouteParams",
     "Router",
@@ -83,6 +85,7 @@ export const ANALYZER_CONTRACTS = {
     "controller",
     "createRequestHandler",
     "css",
+    "daemon",
     "debounce",
     "detachController",
     "dispatch",
@@ -91,6 +94,7 @@ export const ANALYZER_CONTRACTS = {
     "escapeAttr",
     "escapeHtml",
     "getBodyScrollLockCount",
+    "getContext",
     "getController",
     "getSymbol",
     "html",
@@ -107,6 +111,7 @@ export const ANALYZER_CONTRACTS = {
     "once",
     "parseDuration",
     "property",
+    "provideContext",
     "query",
     "queryAll",
     "ready",

package/bin/postinstall.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { closeSync, openSync, writeSync } from 'node:fs';
+
+export const AI_INIT_MESSAGE = [
+  '',
+  'Snice installed. Add version-matched AI guidance to this project:',
+  '  npx snice init-ai',
+  ''
+].join('\n');
+
+function isSilent(env) {
+  return String(env.npm_config_loglevel ?? '').toLowerCase() === 'silent';
+}
+
+/**
+ * npm 7+ captures dependency lifecycle output by default. Prefer stdout when
+ * it is already visible, otherwise write directly to an interactive terminal.
+ * Every terminal operation is best-effort so installation can never fail just
+ * because the recommendation could not be displayed.
+ */
+export function showAiInitMessage({
+  env = process.env,
+  platform = process.platform,
+  stdout = process.stdout,
+  open = openSync,
+  write = writeSync,
+  close = closeSync
+} = {}) {
+  if (isSilent(env)) return false;
+
+  if (stdout.isTTY) {
+    stdout.write(AI_INIT_MESSAGE);
+    return true;
+  }
+
+  if (!env.CI) {
+    let terminal;
+    try {
+      terminal = open(platform === 'win32' ? '\\\\.\\CONOUT$' : '/dev/tty', 'w');
+      write(terminal, AI_INIT_MESSAGE);
+      close(terminal);
+      return true;
+    } catch {
+      if (terminal !== undefined) {
+        try { close(terminal); } catch {}
+      }
+    }
+  }
+
+  try {
+    stdout.write(AI_INIT_MESSAGE);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+showAiInitMessage();