snice 3.5.0 → 3.7.0

package/dist/symbols.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.4.1
+ * snice v3.6.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/symbols.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.4.1
+ * snice v3.6.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v3.4.1
+ * snice v3.6.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/transitions.esm.js

@@ -1,5 +1,5 @@
 /*!
- * snice v3.4.1
+ * snice v3.6.0
  * Imperative TypeScript framework for building vanilla web components with decorators, differential rendering, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.

package/dist/types/context.d.ts

@@ -3,6 +3,7 @@ import { NavContext } from './nav-context';
 import { Placard } from './placard';
 import { RouteParams } from './route-params';
 import { REGISTERED_ELEMENTS, IS_UPDATING, CONTEXT_REGISTER, CONTEXT_UNREGISTER, CONTEXT_NOTIFY_ELEMENT } from '../symbols';
+import type { Fetcher } from '../fetcher';
 declare const REGISTERED_ELEMENTS_SET: unique symbol;
 /**
  * Represents the bundled router state that can notify registered elements of changes
@@ -38,7 +39,12 @@ export declare class Context {
      * Navigation state
      */
     navigation: NavContext;
-    constructor(context?: AppContext, placards?: Placard[], currentRoute?: string, routeParams?: RouteParams);
+    /**
+     * Fetch function with optional middleware support
+     * Bound to this Context instance, allowing middleware to access application and navigation state
+     */
+    fetch: typeof globalThis.fetch;
+    constructor(context?: AppContext, placards?: Placard[], currentRoute?: string, routeParams?: RouteParams, fetcher?: Fetcher);
     /**
      * Update the context and notify all registered elements
      * Prevents infinite loops by tracking update state

package/dist/types/router-options.d.ts

@@ -1,4 +1,5 @@
 import { Transition } from './transition';
+import type { Fetcher } from '../fetcher';
 export interface RouterOptions {
     /**
      * The target element selector where the page element will be instantiated.
@@ -29,4 +30,9 @@ export interface RouterOptions {
      * Default layout element tag name for all pages
      */
     layout?: string;
+    /**
+     * Optional fetcher for context-aware HTTP requests with middleware support
+     * If not provided, Context.fetch will default to native fetch
+     */
+    fetcher?: Fetcher;
 }

package/docs/ai/api.md

@@ -147,13 +147,45 @@ html`
 //     ctx.update(); // notify all subscribers
 //   }
 
-Router({ target, context?, layout? })
+Router({ target, context?, layout?, fetcher? })
 // Returns: { page, navigate, initialize }
 // page() - decorator factory
 // navigate(path) - programmatic navigation
 // initialize() - start router
 ```
 
+## Fetcher
+
+```typescript
+class ContextAwareFetcher implements Fetcher {
+  use(type: 'request', middleware: RequestMiddleware): void
+  use(type: 'response', middleware: ResponseMiddleware): void
+  create(ctx: Context): typeof globalThis.fetch
+}
+
+type RequestMiddleware = (
+  this: Context,
+  request: Request,
+  next: () => Promise<Response>
+) => Promise<Response>
+
+type ResponseMiddleware = (
+  this: Context,
+  response: Response,
+  next: () => Promise<Response>
+) => Promise<Response>
+```
+
+**Usage:**
+- Create fetcher, add middleware via `.use('request', fn)` and `.use('response', fn)`
+- Request middleware runs before fetch, response middleware after
+- Middleware `this` bound to Context instance
+- Access `this.application` and `this.navigation` in middleware
+- Pass to Router via `fetcher` option
+- Use via `ctx.fetch()` in pages/components
+- Optional - defaults to native fetch if not provided
+```
+
 ## Templates
 
 ```typescript

package/docs/ai/components/music-player.md

@@ -0,0 +1,134 @@
+# snice-music-player
+
+Full-featured audio player with playlist, shuffle, repeat, and volume control.
+
+## Properties
+
+```typescript
+tracks: Track[] = [];
+currentTrackIndex: number = 0;
+currentTrack: string = ''; // reflected attribute
+currentTime: number = 0; // read-only, use seek()
+duration: number = 0;
+volume: number = 1;
+muted: boolean = false;
+shuffle: boolean = false;
+repeat: 'off'|'all'|'one' = 'off';
+state: 'playing'|'paused'|'stopped'|'loading'|'error' = 'stopped';
+autoplay: boolean = false;
+showPlaylist: boolean = true;
+showControls: boolean = true;
+showVolume: boolean = true;
+showArtwork: boolean = true;
+showTrackInfo: boolean = true;
+compact: boolean = false;
+```
+
+## Methods
+
+```typescript
+play(): Promise<void>
+pause(): void
+stop(): void
+next(): void
+previous(): void
+seek(time: number): void
+setVolume(volume: number): void
+toggleShuffle(): void
+setRepeat(mode: 'off'|'all'|'one'): void
+loadTrack(index: number): Promise<void>
+getCurrentTrack(): Track | null
+```
+
+## Track Interface
+
+```typescript
+interface Track {
+  id: string;
+  title: string;
+  artist?: string;
+  album?: string;
+  artwork?: string;
+  src: string;
+  duration?: number;
+}
+```
+
+## Events
+
+- `@snice/player-play` - Playback started
+- `@snice/player-pause` - Playback paused
+- `@snice/player-stop` - Playback stopped
+- `@snice/player-track-change` - Track changed
+- `@snice/player-track-ended` - Track ended
+- `@snice/player-shuffle-change` - Shuffle changed
+- `@snice/player-repeat-change` - Repeat mode changed
+- `@snice/player-volume-change` - Volume changed
+- `@snice/player-time-update` - Time updated
+- `@snice/player-error` - Error occurred
+
+## Usage
+
+```javascript
+// Set tracks
+player.tracks = [
+  {
+    id: '1',
+    title: 'Song Title',
+    artist: 'Artist Name',
+    album: 'Album Name',
+    artwork: 'https://example.com/art.jpg',
+    src: 'https://example.com/audio.mp3',
+    duration: 180
+  }
+];
+
+// Controls
+await player.play();
+player.pause();
+player.stop();
+player.next();
+player.previous();
+player.seek(30);
+
+// Volume
+player.setVolume(0.5);
+
+// Shuffle & repeat
+player.toggleShuffle();
+player.setRepeat('all');
+
+// Load track
+await player.loadTrack(2);
+
+// Get current
+const track = player.getCurrentTrack();
+
+// Get/set via currentTrack attribute
+console.log(player.currentTrack); // track ID
+player.currentTrack = 'track-2'; // loads track by ID
+```
+
+```html
+<snice-music-player
+  autoplay
+  shuffle
+  compact
+  show-playlist="false">
+</snice-music-player>
+```
+
+## Features
+
+- HTML5 Audio API
+- Playlist support
+- Play/pause/stop/next/previous
+- Shuffle with randomization
+- Repeat modes: off, all, one
+- Volume control (vertical slider)
+- Progress bar with seek
+- Real-time updates
+- Track artwork & metadata
+- Compact mode
+- Event-driven
+- Clickable playlist

package/docs/ai/components/terminal.md

@@ -0,0 +1,147 @@
+# snice-terminal
+
+Shell terminal emulator with command execution, history, ANSI colors, and keyboard navigation.
+
+## Usage
+
+```html
+<snice-terminal prompt="$ " cwd="~"></snice-terminal>
+```
+
+## Properties
+
+- `prompt: string` - Terminal prompt (default: `"$ "`)
+- `cwd: string` - Current working directory (default: `"~"`)
+- `readonly: boolean` - Disable input (default: `false`)
+- `maxLines: number` - Max lines in history (default: `1000`)
+- `showTimestamps: boolean` - Show line timestamps (default: `false`)
+
+## Methods
+
+- `write(content: string, type?: TerminalLineType): void` - Write without newline
+- `writeln(content: string, type?: TerminalLineType): void` - Write with newline
+- `writeLines(lines: Array<{ content: string; type?: TerminalLineType }>): void` - Write multiple lines
+- `writeError(content: string): void` - Write error line
+- `clear(): void` - Clear terminal
+- `focus(): void` - Focus input
+- `getHistory(): string[]` - Get command history
+- `clearHistory(): void` - Clear command history
+
+## Events
+
+- `@snice/terminal-command: CustomEvent<{ command: string; args: string[] }>` - Command entered
+- `@snice/terminal-clear: CustomEvent<{}>` - Terminal cleared
+- `@snice/terminal-ready: CustomEvent<{}>` - Terminal ready
+
+## Request/Response Pattern
+
+Terminal uses `@request('terminal-command')` decorator pattern:
+
+```typescript
+// Terminal component makes request
+@request('terminal-command')
+async *executeCommand(commandLine: string): any {
+  const response = await (yield payload);
+  return response;
+}
+
+// Controller responds
+@respond('terminal-command')
+async handleCommand(payload: TerminalCommandRequest) {
+  const { command, args, cwd } = payload;
+  // Execute command
+  return { output: 'result', exitCode: 0 };
+}
+```
+
+## Line Types
+
+- `input` - User input
+- `output` - Command output
+- `error` - Error message
+- `info` - Info message
+- `success` - Success message
+- `warning` - Warning message
+
+## Keyboard Shortcuts
+
+- `Enter` - Execute command
+- `↑/↓` - Navigate history
+- `Ctrl+C` - Cancel input
+- `Ctrl+L` - Clear terminal
+- `Tab` - Command completion (TODO)
+
+## ANSI Color Support
+
+Supports ANSI escape codes for colors:
+- `30-37` - Standard colors
+- `90-97` - Bright colors
+
+Special output `\x1B[CLEAR]` clears terminal.
+
+## CSS Variables
+
+```css
+--snice-terminal-background
+--snice-terminal-foreground
+--snice-terminal-border
+--snice-terminal-scrollbar
+--snice-terminal-scrollbar-thumb
+--snice-terminal-input-color
+--snice-terminal-output-color
+--snice-terminal-error-color
+--snice-terminal-info-color
+--snice-terminal-success-color
+--snice-terminal-warning-color
+--snice-terminal-prompt-color
+--snice-terminal-selection
+```
+
+## Types
+
+```typescript
+type TerminalLineType = 'input' | 'output' | 'error' | 'info' | 'success' | 'warning';
+
+interface TerminalCommandRequest {
+  command: string;
+  args: string[];
+  cwd?: string;
+  history?: string[];
+}
+
+interface TerminalCommandResponse {
+  output?: string;
+  error?: string;
+  exitCode?: number;
+}
+```
+
+## Example
+
+```javascript
+const terminal = document.querySelector('snice-terminal');
+
+// Listen for commands (event pattern)
+terminal.addEventListener('@snice/terminal-command', (e) => {
+  console.log('Command:', e.detail.command, e.detail.args);
+});
+
+// Handle commands (@respond pattern)
+class TerminalController extends HTMLElement {
+  @respond('terminal-command')
+  async handleCommand(req) {
+    if (req.command === 'echo') {
+      return { output: req.args.join(' '), exitCode: 0 };
+    }
+    if (req.command === 'clear') {
+      return { output: '\x1B[CLEAR]' };
+    }
+    return { error: `Command not found: ${req.command}`, exitCode: 127 };
+  }
+}
+
+// Write to terminal
+terminal.writeln('Welcome to the terminal!', 'info');
+terminal.writeln('\x1b[32mGreen text\x1b[0m', 'output');
+terminal.writeError('Error: Something went wrong');
+```

package/docs/ai/components/timer.md

@@ -0,0 +1,43 @@
+# Timer
+
+```html
+<snice-timer mode="stopwatch"></snice-timer>
+<snice-timer mode="timer" initial-time="60"></snice-timer>
+```
+
+## Properties
+- `mode`: 'stopwatch' | 'timer' (default: 'stopwatch')
+- `initial-time`: number (default: 0) - Starting time in seconds for timer mode
+- `running`: boolean (read-only)
+
+## Methods
+- `start()`: Start timer
+- `stop()`: Stop/pause timer
+- `reset()`: Reset to initial state
+- `getTime()`: Get current time in seconds
+
+## Events
+- `@snice/timer-start`: { timer, time }
+- `@snice/timer-stop`: { timer, time }
+- `@snice/timer-reset`: { timer, time }
+- `@snice/timer-complete`: { timer } - Countdown reached 0
+
+## Implementation
+- Uses requestAnimationFrame for smooth updates
+- Direct DOM manipulation for display to avoid re-renders
+- Stopwatch: counts up from 0
+- Timer: counts down from initial-time
+- Auto-stops at 0 in timer mode
+
+## Display Format
+- Under 1 hour: `M:SS.D` (e.g., "2:05.3")
+- Over 1 hour: `H:MM:SS` (e.g., "1:05:30")
+
+## Theme Integration
+Uses standard theme tokens:
+- Background: `--snice-color-background-element`
+- Borders: `--snice-color-border`
+- Text: `--snice-color-text`
+- Start button: `--snice-color-success`
+- Pause button: `--snice-color-warning`
+- Reset button: `--snice-color-neutral`

package/docs/ai/patterns.md

@@ -115,6 +115,53 @@ class UserProfile extends HTMLElement {
 }
 ```
 
+## Fetch with Middleware
+
+```typescript
+import { Router, ContextAwareFetcher } from 'snice';
+
+const fetcher = new ContextAwareFetcher();
+
+// Request middleware - modify request before fetch
+fetcher.use('request', function(request, next) {
+  const token = this.application.user?.token;
+  if (token) {
+    request.headers.set('Authorization', `Bearer ${token}`);
+  }
+  return next();
+});
+
+// Response middleware - handle response after fetch
+fetcher.use('response', async function(response, next) {
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return next();
+});
+
+const router = Router({
+  target: '#app',
+  context: { user: null },
+  fetcher
+});
+
+// In pages
+@page({ tag: 'user-page', routes: ['/users/:id'] })
+class UserPage extends HTMLElement {
+  private ctx: Context;
+
+  @context()
+  handleContext(ctx: Context) {
+    this.ctx = ctx;
+  }
+
+  @ready()
+  async load() {
+    const user = await this.ctx.fetch('/api/users/123').then(r => r.json());
+  }
+}
+```
+
 ## Conditional Rendering
 ```typescript
 html`