snice 7.2.0 → 7.4.0

package/bin/snice.js

@@ -14,7 +14,7 @@ import {
 import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { promisify } from 'node:util';
 import { analyzeProject, findImports, isTypeOnlyImport, maskComments } from './project-analyzer.js';
@@ -26,6 +26,7 @@ const packageRoot = join(__dirname, '..');
 const packageJson = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'));
 const argv = process.argv.slice(2);
 const command = argv[0];
+const DIAGNOSTIC_IGNORE_FILENAME = '.sniceignore';
 
 function help() {
   console.log(`Snice CLI ${packageJson.version}
@@ -52,6 +53,9 @@ Commands:
 AI setup:
   npx snice init-ai   Install version-matched guidance before an agent writes Snice code.
 
+Diagnostics:
+  .sniceignore        Suppress diagnostic codes globally or at an exact source location.
+
 Build options:
   --output=<dir>       Output directory (default: ./dist/cdn)
   --format=iife,es     Output formats (default: iife; table: iife,es)
@@ -207,21 +211,79 @@ function walkSource(root) {
 }
 
 function validateProject(targetDir, json = false) {
-  const issues = collectValidationIssues(targetDir);
+  const ignored = readDiagnosticIgnores(targetDir);
+  const issues = collectValidationIssues(targetDir, ignored);
   renderValidation(issues, json);
   return issues;
 }
 
-function collectValidationIssues(targetDir) {
+function collectValidationIssues(targetDir, ignored = readDiagnosticIgnores(targetDir)) {
   const sourceRoot = existsSync(join(targetDir, 'src')) ? join(targetDir, 'src') : targetDir;
   const projectFiles = ['package.json', 'tsconfig.json', 'index.html']
     .map(filename => join(targetDir, filename))
     .filter(existsSync);
   const files = [...new Set([...projectFiles, ...walkSource(sourceRoot)])].sort();
-  return analyzeProject(files.map(file => ({
+  const issues = analyzeProject(files.map(file => ({
     filename: file,
     source: readFileSync(file, 'utf8')
   })));
+  return filterIgnoredDiagnostics(issues, ignored, targetDir);
+}
+
+function readDiagnosticIgnores(targetDir) {
+  const path = join(targetDir, DIAGNOSTIC_IGNORE_FILENAME);
+  if (!existsSync(path)) return [];
+
+  const entries = [];
+  for (const authoredLine of readFileSync(path, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)) {
+    const line = authoredLine.replace(/\s+#.*$/, '').trim();
+    if (!line || line.startsWith('#')) continue;
+    const separator = line.search(/\s/);
+    const code = separator < 0 ? line : line.slice(0, separator);
+    const locator = separator < 0 ? '' : line.slice(separator).trim();
+    if (!locator) {
+      entries.push({ code });
+      continue;
+    }
+
+    let file = locator;
+    let lineNumber;
+    let column;
+    const exact = /^(.*):(\d+):(\d+)$/.exec(locator);
+    const lineOnly = exact ? null : /^(.*):(\d+)$/.exec(locator);
+    if (exact) {
+      file = exact[1];
+      lineNumber = Number(exact[2]);
+      column = Number(exact[3]);
+    } else if (lineOnly) {
+      file = lineOnly[1];
+      lineNumber = Number(lineOnly[2]);
+    }
+    if (!file) continue;
+    entries.push({ code, file: normalizeDiagnosticPath(file), line: lineNumber, column });
+  }
+  return entries;
+}
+
+function filterIgnoredDiagnostics(diagnostics, ignored, targetDir) {
+  if (!ignored.length) return diagnostics;
+  return diagnostics.filter(diagnostic => !ignored.some(entry => {
+    const code = diagnostic.code ?? diagnostic.ruleId;
+    if (entry.code !== code) return false;
+    if (!entry.file) return true;
+    if (!diagnostic.file) return false;
+    const absolute = isAbsolute(diagnostic.file)
+      ? diagnostic.file
+      : resolve(targetDir, diagnostic.file);
+    if (normalizeDiagnosticPath(relative(targetDir, absolute)) !== entry.file) return false;
+    if (entry.line !== undefined && diagnostic.line !== entry.line) return false;
+    if (entry.column !== undefined && diagnostic.column !== entry.column) return false;
+    return true;
+  }));
+}
+
+function normalizeDiagnosticPath(path) {
+  return path.replaceAll('\\', '/').replace(/^\.\//, '');
 }
 
 function renderValidation(issues, json = false) {
@@ -230,7 +292,7 @@ function renderValidation(issues, json = false) {
   else {
     for (const issue of issues) {
       console.log(
-        `[${issue.severity.toUpperCase()}] ${issue.file ?? ''}:${issue.line}:${issue.column} ${issue.ruleId}\n` +
+        `[${issue.severity.toUpperCase()}] ${issue.file ?? ''}:${issue.line}:${issue.column} ${issue.code}\n` +
         `  ${issue.message}\n  ${issue.fix}`
       );
     }
@@ -280,7 +342,8 @@ function resolveTsconfigChain(dir, entry = 'tsconfig.json', seen = new Set()) {
 }
 
 async function doctor(targetDir, json = false) {
-  const findings = await collectDoctorFindings(targetDir);
+  const ignored = readDiagnosticIgnores(targetDir);
+  const findings = await collectDoctorFindings(targetDir, ignored);
   renderDoctor(findings, json);
   return findings;
 }
@@ -381,7 +444,7 @@ async function probeDecoratorTransform(targetDir, add, projectPackage) {
   }
 }
 
-async function collectDoctorFindings(targetDir) {
+async function collectDoctorFindings(targetDir, ignored = readDiagnosticIgnores(targetDir)) {
   const findings = [];
   const add = (severity, code, message) => findings.push({ severity, code, message });
   const projectPackage = readJson(join(targetDir, 'package.json'));
@@ -443,7 +506,7 @@ async function collectDoctorFindings(targetDir) {
 
   await probeDecoratorTransform(targetDir, add, projectPackage);
 
-  return findings;
+  return filterIgnoredDiagnostics(findings, ignored, targetDir);
 }
 
 function renderDoctor(findings, json = false) {
@@ -451,15 +514,16 @@ function renderDoctor(findings, json = false) {
   const warnings = findings.filter(item => item.severity === 'warning').length;
   if (json) console.log(JSON.stringify({ ok: errors === 0, findings }, null, 2));
   else {
-    for (const finding of findings) console.log(`[${finding.severity.toUpperCase()}] ${finding.message}`);
+    for (const finding of findings) console.log(`[${finding.severity.toUpperCase()}] ${finding.code} ${finding.message}`);
     console.log(`Doctor finished with ${errors} error(s) and ${warnings} warning(s).`);
   }
   if (errors) process.exitCode = 1;
 }
 
 async function checkProject(targetDir, json = false) {
-  const findings = await collectDoctorFindings(targetDir);
-  const issues = collectValidationIssues(targetDir);
+  const ignored = readDiagnosticIgnores(targetDir);
+  const findings = await collectDoctorFindings(targetDir, ignored);
+  const issues = collectValidationIssues(targetDir, ignored);
   const ok = !findings.some(item => item.severity === 'error') &&
     !issues.some(item => item.severity === 'error');
 
@@ -467,12 +531,12 @@ async function checkProject(targetDir, json = false) {
     console.log(JSON.stringify({ ok, findings, issues }, null, 2));
   } else {
     console.log('Project configuration:');
-    for (const finding of findings) console.log(`[${finding.severity.toUpperCase()}] ${finding.message}`);
+    for (const finding of findings) console.log(`[${finding.severity.toUpperCase()}] ${finding.code} ${finding.message}`);
     console.log('\nSnice source:');
     if (!issues.length) console.log('No Snice authoring issues found.');
     for (const issue of issues) {
       console.log(
-        `[${issue.severity.toUpperCase()}] ${issue.file ?? ''}:${issue.line}:${issue.column} ${issue.ruleId}\n` +
+        `[${issue.severity.toUpperCase()}] ${issue.file ?? ''}:${issue.line}:${issue.column} ${issue.code}\n` +
         `  ${issue.message}\n  ${issue.fix}`
       );
     }

package/bin/templates/AI_GUIDANCE.md

@@ -7,6 +7,12 @@ reviewing Snice code. It routes you to the version-matched references under
 Do not infer Snice behavior from Lit or generic web-component conventions. Read
 only the topical reference and component documents needed for the task.
 
+Visual behavior belongs in elements. Application behavior specific to a set of
+elements belongs in a controller. Element orchestration belongs in pages. Keep
+those ownership rules separate from the attachment mechanism: do not attach a
+controller to a page host. A host-free reusable function may stay a plain module
+wherever the project convention puts it; state plus lifecycle belongs in a daemon.
+
 Useful diagnostics:
 
 ```bash
@@ -15,4 +21,3 @@ npx snice check
 
 Use `doctor` or `validate` only to isolate the configuration or source half of
 a failed check.
-

package/bin/templates/default/README.md

@@ -61,7 +61,7 @@ src/
     notifications.ts    # Live feed, filters, @watch, keyboard shortcuts
     settings.ts         # Theme toggle, form bindings, @context, Ctrl+S save
     data.ts             # Data table, search-bar, @observe('resize'), filters
-  services/       # Business logic (auth, storage, jwt)
+  services/       # This project's host-free functions (auth, storage, jwt)
   middleware/      # Fetch middleware (auth, error, retry)
   daemons/        # Lifecycle-managed classes (notifications WebSocket)
   guards/         # Route guards (auth)

package/bin/templates/default/src/components/app-header.ts

@@ -1,19 +1,17 @@
-import { element, property, render, styles, context, on, dispatch, dispose, html, css, watch, query } from 'snice';
+import { element, render, styles, context, on, dispatch, dispose, html, css, state } from 'snice';
 import type { Context } from 'snice';
 import type { ApplicationContext } from '../context';
 import { logout } from '../services/auth';
 
 @element('app-header')
 export class AppHeader extends HTMLElement {
-  @property() userName = '';
-  @property() userAvatar = '';
-  @property({ type: Boolean }) authenticated = false;
-  @property({ type: Boolean }) menuOpen = false;
-  @property({ type: Number }) notificationCount = 0;
+  @state() userName = '';
+  @state() userAvatar = '';
+  @state() authenticated = false;
+  @state() menuOpen = false;
+  @state() notificationCount = 0;
   private unsubscribeNotifications: (() => void) | null = null;
 
-  @query('.user-menu') $menu!: HTMLElement;
-
   @context()
   handleContext(ctx: Context) {
     const { principal, notifications } = ctx.application as ApplicationContext;
@@ -37,13 +35,6 @@ export class AppHeader extends HTMLElement {
     }
   }
 
-  @watch('menuOpen')
-  onMenuToggle() {
-    if (this.$menu) {
-      this.$menu.style.display = this.menuOpen ? 'block' : 'none';
-    }
-  }
-
   toggleMenu() {
     this.menuOpen = !this.menuOpen;
   }
@@ -96,7 +87,7 @@ export class AppHeader extends HTMLElement {
               <span class="user-name">${this.userName}</span>
             </button>
 
-            <div class="user-menu" style="display: none">
+            <div class="user-menu" ?hidden=${!this.menuOpen}>
               <a href="#/profile" @click=${() => this.menuOpen = false}>Profile</a>
               <a href="#/settings" @click=${() => this.menuOpen = false}>Settings</a>
               <snice-divider></snice-divider>
@@ -195,6 +186,10 @@ export class AppHeader extends HTMLElement {
         z-index: 100;
       }
 
+      .user-menu[hidden] {
+        display: none;
+      }
+
       .user-menu a,
       .user-menu button {
         display: block;

package/bin/templates/default/src/components/notification-badge.ts

@@ -1,24 +1,15 @@
-import { element, property, render, styles, html, css, watch, query } from 'snice';
+import { element, property, render, styles, html, css } from 'snice';
 
 @element('notification-badge')
 export class NotificationBadge extends HTMLElement {
   @property({ type: Number }) count = 0;
 
-  @query('.badge') $badge!: HTMLElement;
-
-  @watch('count')
-  onCountChange() {
-    if (this.$badge) {
-      this.$badge.textContent = this.count > 99 ? '99+' : String(this.count);
-      this.$badge.style.display = this.count > 0 ? 'flex' : 'none';
-    }
-  }
-
-  @render({ once: true })
+  @render()
   renderContent() {
-    const display = this.count > 0 ? 'flex' : 'none';
     return html`
-      <span class="badge" style="display: ${display}">${this.count}</span>
+      <if ${this.count > 0}>
+        <span class="badge">${this.count > 99 ? '99+' : this.count}</span>
+      </if>
     `;
   }
 

package/bin/templates/default/src/components/search-bar.ts

@@ -1,20 +1,22 @@
-import { element, property, render, styles, on, dispatch, html, css } from 'snice';
+import { debounce, dispatch, element, html, live, property, render, styles, css } from 'snice';
 
 @element('search-bar')
 export class SearchBar extends HTMLElement {
   @property() value = '';
   @property() placeholder = 'Search...';
 
-  @on('input', 'input', { debounce: 300 })
-  handleInput(e: Event) {
-    this.value = (e.target as HTMLInputElement).value;
-    this.dispatchSearch();
+  handleInput(e: CustomEvent<{ value: string }>) {
+    this.value = e.detail.value;
+    this.queueSearch();
   }
 
-  @on('keydown:Escape', 'input')
-  clearSearch(e: Event) {
+  clearSearch() {
     this.value = '';
-    (e.target as HTMLInputElement).value = '';
+    this.dispatchSearch();
+  }
+
+  @debounce(300)
+  queueSearch() {
     this.dispatchSearch();
   }
 
@@ -26,17 +28,15 @@ export class SearchBar extends HTMLElement {
   @render()
   renderContent() {
     return html`
-      <div class="search-container">
-        <span class="icon">&#128269;</span>
-        <input
-          type="text"
-          .value=${this.value}
-          placeholder="${this.placeholder}"
-        />
-        <if ${this.value.length > 0}>
-          <button class="clear" @click=${() => { this.value = ''; this.dispatchSearch(); }}>&#10005;</button>
-        </if>
-      </div>
+      <snice-input
+        type="search"
+        clearable
+        prefix-icon="🔍"
+        .value=${live(this.value)}
+        placeholder="${this.placeholder}"
+        @input-input=${this.handleInput}
+        @keydown.escape=${this.clearSearch}
+      ></snice-input>
     `;
   }
 
@@ -47,52 +47,8 @@ export class SearchBar extends HTMLElement {
         display: block;
       }
 
-      .search-container {
-        display: flex;
-        align-items: center;
-        gap: 0.5rem;
-        padding: 0.5rem 0.75rem;
-        background: var(--snice-color-surface);
-        border: 1px solid var(--snice-color-border);
-        border-radius: var(--snice-border-radius-lg);
-      }
-
-      .search-container:focus-within {
-        border-color: var(--snice-color-primary);
-        box-shadow: 0 0 0 3px color-mix(in srgb, var(--snice-color-primary) 15%, transparent);
-      }
-
-      .icon {
-        color: var(--snice-color-text-secondary);
-        font-size: 0.875rem;
-      }
-
-      input {
-        flex: 1;
-        border: none;
-        outline: none;
-        background: transparent;
-        font-size: 0.875rem;
-        color: var(--snice-color-text);
-      }
-
-      input::placeholder {
-        color: var(--snice-color-text-secondary);
-      }
-
-      .clear {
-        background: none;
-        border: none;
-        cursor: pointer;
-        color: var(--snice-color-text-secondary);
-        font-size: 0.75rem;
-        padding: 0.125rem 0.25rem;
-        border-radius: var(--snice-border-radius-md);
-      }
-
-      .clear:hover {
-        background: var(--snice-color-surface-container-low);
-        color: var(--snice-color-text);
+      snice-input {
+        width: 100%;
       }
     `;
   }

package/bin/templates/default/src/pages/dashboard.ts

@@ -1,5 +1,5 @@
 import { page } from '../router';
-import { render, styles, html, css, context, observe, dispose } from 'snice';
+import { render, styles, html, css, context, observe, dispose, state } from 'snice';
 import type { Placard, Context } from 'snice';
 import type { ApplicationContext } from '../context';
 import { isAuthenticated } from '../guards/auth';
@@ -15,9 +15,9 @@ const placard: Placard = {
 
 @page({ tag: 'dashboard-page', routes: ['/', '/dashboard'], guards: [isAuthenticated], placard })
 export class DashboardPage extends HTMLElement {
-  userName = '';
-  notificationCount = 0;
-  isCompact = false;
+  @state() userName = '';
+  @state() notificationCount = 0;
+  @state() isCompact = false;
   private unsubscribe: (() => void) | null = null;
 
   @context()
@@ -48,7 +48,7 @@ export class DashboardPage extends HTMLElement {
   @render()
   renderContent() {
     return html`
-      <div class="container">
+      <div class="container" class:compact=${this.isCompact}>
         <div class="welcome">
           <h1>Welcome, ${this.userName}!</h1>
           <p class="subtitle">This is your dashboard</p>
@@ -87,12 +87,12 @@ export class DashboardPage extends HTMLElement {
           <snice-card>
             <h3>Architecture</h3>
             <ul>
-              <li><strong>Pages:</strong> Route orchestrators</li>
-              <li><strong>Components:</strong> Reusable UI</li>
-              <li><strong>Controllers:</strong> Behavior modules</li>
-              <li><strong>Services:</strong> Business logic</li>
+              <li><strong>Pages:</strong> Element orchestration</li>
+              <li><strong>Components:</strong> Reusable visual behavior</li>
+              <li><strong>Controllers:</strong> Application behavior for a set of elements</li>
+              <li><strong>Services:</strong> Host-free functions in this project</li>
               <li><strong>Middleware:</strong> Fetch interceptors</li>
-              <li><strong>Daemons:</strong> Lifecycle classes</li>
+              <li><strong>Daemons:</strong> Explicit state and lifecycle</li>
               <li><strong>Guards:</strong> Route protection</li>
             </ul>
           </snice-card>
@@ -102,7 +102,7 @@ export class DashboardPage extends HTMLElement {
             <ul>
               <li><code>@page</code> - Route pages</li>
               <li><code>@element</code> - Custom elements</li>
-              <li><code>@controller</code> - Behavior modules</li>
+              <li><code>@controller</code> - Element-specific application behavior</li>
               <li><code>@context</code> - Global state</li>
               <li><code>@observe</code> - DOM observers</li>
               <li><code>@watch</code> - Property watchers</li>
@@ -140,6 +140,10 @@ export class DashboardPage extends HTMLElement {
         margin: 0 auto;
       }
 
+      .container.compact {
+        padding: 1rem;
+      }
+
       .welcome {
         margin-bottom: 2rem;
       }

package/bin/templates/default/src/pages/data.ts

@@ -1,5 +1,5 @@
 import { page } from '../router';
-import { render, styles, observe, property, ready, html, css } from 'snice';
+import { render, styles, observe, ready, html, css, state } from 'snice';
 import type { Placard } from 'snice';
 import { isAuthenticated } from '../guards/auth';
 
@@ -34,19 +34,16 @@ const MOCK_ITEMS: DataItem[] = [
 
 @page({ tag: 'data-page', routes: ['/data'], guards: [isAuthenticated], placard })
 export class DataPage extends HTMLElement {
-  allItems: DataItem[] = [];
-  filteredItems: DataItem[] = [];
-  searchQuery = '';
-  statusFilter: 'all' | 'active' | 'pending' | 'archived' = 'all';
-  @property({ type: Boolean }) loading = true;
+  @state() allItems: DataItem[] = [];
+  @state() filteredItems: DataItem[] = [];
+  @state() searchQuery = '';
+  @state() statusFilter: 'all' | 'active' | 'pending' | 'archived' = 'all';
+  @state() loading = true;
+  @state() compact = false;
 
   @observe('resize')
   handleResize(entries: ResizeObserverEntry[]) {
-    const width = entries[0].contentRect.width;
-    const table = this.shadowRoot?.querySelector('.data-table');
-    if (table) {
-      table.classList.toggle('compact', width < 600);
-    }
+    this.compact = entries[0].contentRect.width < 600;
   }
 
   @ready()
@@ -145,7 +142,7 @@ export class DataPage extends HTMLElement {
             ></snice-empty-state>
           </when>
           <default>
-            <div class="data-table">
+            <div class="data-table" class:compact=${this.compact}>
               <div class="table-header">
                 <span class="col-title">Title</span>
                 <span class="col-status">Status</span>
@@ -158,7 +155,7 @@ export class DataPage extends HTMLElement {
                     <span class="description">${item.description}</span>
                   </div>
                   <div class="col-status">
-                    <span class="status-dot" style="background: ${this.getStatusColor(item.status)}"></span>
+                    <span class="status-dot" style:background=${this.getStatusColor(item.status)}></span>
                     ${item.status}
                   </div>
                   <div class="col-date">${item.createdAt}</div>

package/bin/templates/default/src/pages/notifications.ts

@@ -1,5 +1,5 @@
 import { page } from '../router';
-import { render, styles, html, css, context, dispose, watch, on } from 'snice';
+import { render, styles, html, css, context, dispose, on, state } from 'snice';
 import type { Placard, Context } from 'snice';
 import type { ApplicationContext } from '../context';
 import { isAuthenticated } from '../guards/auth';
@@ -16,8 +16,8 @@ const placard: Placard = {
 
 @page({ tag: 'notifications-page', routes: ['/notifications'], guards: [isAuthenticated], placard })
 export class NotificationsPage extends HTMLElement {
-  notifications: Notification[] = [];
-  filter: NotificationType | 'all' = 'all';
+  @state() notifications: Notification[] = [];
+  @state() filter: NotificationType | 'all' = 'all';
   private unsubscribe: (() => void) | null = null;
 
   @context()
@@ -38,11 +38,6 @@ export class NotificationsPage extends HTMLElement {
     }
   }
 
-  @watch('filter')
-  onFilterChange() {
-    // Re-render triggers automatically via property change
-  }
-
   get filteredNotifications(): Notification[] {
     if (this.filter === 'all') return this.notifications;
     return this.notifications.filter(n => n.type === this.filter);
@@ -124,7 +119,7 @@ export class NotificationsPage extends HTMLElement {
                   key=${notification.id}
                   .variant=${notification.type}
                   dismissible
-                  @dismiss=${() => this.removeNotification(notification.id)}
+                  @alert-dismiss=${() => this.removeNotification(notification.id)}
                 >
                   <strong>${notification.title}</strong>
                   <p>${notification.message}</p>

package/bin/templates/default/src/pages/profile.ts

@@ -1,5 +1,5 @@
 import { page } from '../router';
-import { render, styles, html, css, context, dispatch, observe } from 'snice';
+import { render, styles, html, css, context, dispatch, state } from 'snice';
 import type { Placard, Context } from 'snice';
 import type { Principal, User } from '../types/auth';
 import { isAuthenticated } from '../guards/auth';
@@ -16,9 +16,8 @@ const placard: Placard = {
 
 @page({ tag: 'profile-page', routes: ['/profile'], guards: [isAuthenticated], placard })
 export class ProfilePage extends HTMLElement {
-  user: User | null = null;
+  @state() user: User | null = null;
   private ctx?: Context;
-  isMobile = false;
 
   @context()
   handleContext(ctx: Context) {
@@ -27,11 +26,6 @@ export class ProfilePage extends HTMLElement {
     this.user = principal?.user || null;
   }
 
-  @observe('media:(max-width: 640px)')
-  handleMediaChange(matches: boolean) {
-    this.isMobile = matches;
-  }
-
   @dispatch('user-logout')
   async handleLogout() {
     await logout();