snice 5.2.2 → 6.0.0

package/docs/ai/components/message-strip.md

@@ -6,7 +6,7 @@ Inline contextual message bar within content flow. Differs from alert (card), ba
 
 ```ts
 variant: 'info'|'success'|'warning'|'danger' = 'info';
-dismissable: boolean = false;
+dismissible: boolean = false;
 icon: string = '';  // Custom icon (set "none" to hide)
 ```
 
@@ -43,8 +43,8 @@ import 'snice/components/message-strip/snice-message-strip';
 <snice-message-strip variant="warning">Review your changes.</snice-message-strip>
 <snice-message-strip variant="danger">An error occurred.</snice-message-strip>
 
-<!-- Dismissable -->
-<snice-message-strip variant="info" dismissable>You can close this.</snice-message-strip>
+<!-- Dismissible -->
+<snice-message-strip variant="info" dismissible>You can close this.</snice-message-strip>
 
 <!-- Custom icon -->
 <snice-message-strip variant="info" icon="🔔">New notification.</snice-message-strip>

package/docs/ai/decorators.md

@@ -13,7 +13,8 @@
 
 ## Properties
 - `@property({ type?, attribute?: string|boolean, converter?, hasChanged? })` - Reactive, syncs attrs. Initial defaults NOT reflected to attrs.
-- `@watch('propName')` - React to changes: `(oldVal, newVal, propertyName) => void`
+- `@watch('propName')` - Fires once on init as `(undefined, initialValue, propertyName)`, then on every change: `(oldVal, newVal, propertyName) => void`.
+- `@watch('propName', { immediate: false })` - Change-only; skips the init call (use for watchers that dispatch events). Options object is the last arg (works with multiple names).
 
 ## Lifecycle
 - `@ready()` - After first render. Fires once.
@@ -27,8 +28,37 @@
 - `@queryAll('selector', { light? })` - NodeList
 
 ## Events
-- `@on('event', 'selector?')` - Delegation, auto-bound
-- `@dispatch('event-name', options?)` - Emit CustomEvent, detail = return value. Supports async. Options: `{ debounce?, throttle?, dispatchOnUndefined? }`
+- `@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 }`
+
+### scope (on both `@on` and `@dispatch`)
+
+Redirects where the listener is attached / event is dispatched. Default: host element.
+
+```ts
+scope?: 'global' | string | EventTarget | ((this: HTMLElement) => EventTarget | null)
+```
+
+| value | resolves to |
+|---|---|
+| omitted | host element |
+| `'global'` | `document` |
+| selector string | `host.closest(selector)` — nearest ancestor |
+| Element / EventTarget | that node |
+| resolver fn | called with host as `this`; `null` skips |
+
+```ts
+@on('bus:save', { scope: 'global' }) onSave(e) {}
+@on('bus:cart-added', { scope: 'cart-shell' }) onAdd(e) {}
+@on('go', { scope: someEl }) onGo(e) {}
+@on('beep', { scope() { return this.closest('app-shell'); } }) onBeep(e) {}
+
+@dispatch('bus:cart-added', { scope: 'global' }) add(id) { return { id }; }
+@dispatch('bus:x', { scope: 'cart-shell' }) fire() { return 1; }
+```
+
+Unresolved scope → `console.warn`, listener not attached / event not dispatched.
+Resolver re-runs on reconnect — listeners track DOM moves.
 
 ## Communication
 - `@request(channel, options?)` - Async generator request pattern
@@ -58,9 +88,18 @@ attr="${val}"     - String attribute
 @event=${fn}      - Event listener (auto-bound)
 ```
 
-## Event Modifiers
+## Event Modifiers (keyboard only)
+Template dotted/colon modifiers apply ONLY to keydown/keyup/keypress — they are
+key filters, not general event options. A dot in any other event name is part of
+the event name (e.g. `@app.ready`).
 ```
 @keydown:Enter=${fn}    - Key filter
 @keydown.ctrl+s=${fn}   - Key combo
-@click.once=${fn}       - Fire once
+@keydown.~enter=${fn}   - Key, any modifiers
+```
+`once` / `preventDefault` / `stopPropagation` / `capture` are NOT template
+modifiers — use the `@on` decorator's options object:
+```typescript
+@on('click', { once: true, preventDefault: true, stopPropagation: true })
+handleClick(e: Event) {}
 ```

package/docs/cdn.md

@@ -0,0 +1,56 @@
+<!-- AI: For the AI-optimized version of this doc, see docs/ai/cdn.md -->
+
+# CDN / Standalone Usage
+
+Use any Snice component on a plain HTML page — no bundler, no build step. Each component is a standalone `.min.js` bundle that shares one small runtime.
+
+## Load Order
+
+Load the runtime **once, first**, then one bundle per component. Components load in any order *after* the runtime:
+
+```html
+<link rel="stylesheet" href="theme.css">      <!-- optional: design tokens + dark mode -->
+<script src="snice-runtime.min.js"></script>  <!-- required, load first -->
+<script src="snice-button.min.js"></script>   <!-- one bundle per component -->
+<script src="snice-card.min.js"></script>
+
+<snice-button variant="primary">Click me</snice-button>
+```
+
+`snice-runtime.min.js` is shared by every component. Load it before any `snice-<name>.min.js` — without it the custom elements never register and the page renders blank.
+
+## Bundle Families
+
+One bundle registers its whole element family — you don't load sub-elements separately:
+
+| Bundle | Registers |
+|--------|-----------|
+| `snice-tabs.min.js` | `<snice-tabs>`, `<snice-tab>`, `<snice-tab-panel>` |
+| `snice-select.min.js` | `<snice-select>`, `<snice-option>` |
+| `snice-toast.min.js` | `<snice-toast>`, `<snice-toast-container>` |
+
+## Theme and Dark Mode
+
+Components ship with built-in light-mode token fallbacks, so they render correctly with no stylesheet. Add `theme.css` for the full design-token set and dark mode:
+
+```html
+<link rel="stylesheet" href="theme.css">
+```
+
+Dark mode follows the OS setting automatically. To force it, set `data-theme` on the root element:
+
+```html
+<html data-theme="dark">   <!-- or data-theme="light" to pin light -->
+```
+
+## Use the `.min.js` Builds
+
+Load the `.min.js` (IIFE) bundles in `<script src>` tags. The `.esm.min.js` builds are ES modules for bundler/`import` use, not `<script src>`.
+
+## Generating Bundles
+
+Bundles are published to the CDN, or build them yourself:
+
+```bash
+snice build-component button
+```

package/docs/components/chat.md

@@ -2,9 +2,10 @@
 
 # Chat Component
 
-Slack-style chat interface with messages, typing indicators, reactions, file attachments, and message threading.
+Slack-style chat interface with messages, typing indicators, reactions, and file attachments.
 
 ## Table of Contents
+- [Components](#components)
 - [Properties](#properties)
 - [Methods](#methods)
 - [Events](#events)
@@ -14,6 +15,13 @@ Slack-style chat interface with messages, typing indicators, reactions, file att
 - [Examples](#examples)
 - [Accessibility](#accessibility)
 
+## Components
+
+| Element | Description |
+|---------|-------------|
+| `snice-chat` | The chat container — renders messages, input, typing indicators. |
+| `snice-chat-message` | Declarative message authoring. Provide messages as child elements instead of (or as well as) the `messages` array; child elements render first, array entries append after. |
+
 ## Properties
 
 | Property | Type | Default | Description |
@@ -26,6 +34,23 @@ Slack-style chat interface with messages, typing indicators, reactions, file att
 | `showTyping` (attr: `show-typing`) | `boolean` | `true` | Show typing indicators |
 | `showAvatars` (attr: `show-avatars`) | `boolean` | `true` | Show user avatars |
 | `showTimestamps` (attr: `show-timestamps`) | `boolean` | `true` | Show message timestamps |
+| `authorColors` | `Record<string, string>` | `{}` | Per-author name colors, keyed by author name (property only) |
+| `colorAuthors` (attr: `color-authors`) | `boolean` | `false` | Auto-assign a stable color to each author |
+| `markdown` | `boolean` | `false` | Render message content as markdown by default |
+| `layout` | `'default' \| 'bubbles'` | `'default'` | Built-in message layout; `'bubbles'` aligns own messages right in colored bubbles |
+
+### snice-chat-message Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `author` | `string` | `''` | Message author name |
+| `avatar` | `string` | `''` | Author avatar URL |
+| `type` | `'text' \| 'file' \| 'image' \| 'system'` | `'text'` | Message type |
+| `format` | `'text' \| 'markdown'` | — | How the body is rendered; unset defers to the chat-level `markdown` flag |
+| `edited` | `boolean` | `false` | Marks the message as edited |
+| `author-color` | `string` | `''` | Per-message author color override |
+
+The message body is the element's text content. Rich fields with no attribute form — `reactions`, `attachment` — can be set as JS properties on the element and are carried into the message.
 
 ### ChatMessage Interface
 
@@ -41,6 +66,8 @@ interface ChatMessage {
   reactions?: MessageReaction[];
   thread?: ChatMessage[];
   attachment?: MessageAttachment;
+  format?: 'text' | 'markdown';   // unset = the chat-level markdown flag applies
+  authorColor?: string;           // per-message author color override (CSS color; values containing ; { } are rejected)
 }
 
 interface MessageAttachment {
@@ -79,10 +106,11 @@ interface MessageReaction {
 | `message-edit` | `{ messageId: string, newContent: string }` | User edits a message |
 | `message-delete` | `{ messageId: string }` | User deletes a message |
 | `message-react` | `{ messageId: string, emoji: string }` | User reacts to a message |
-| `message-thread` | `{ messageId: string }` | User starts a thread |
 | `typing-start` | `{}` | Current user starts typing |
 | `typing-stop` | `{}` | Current user stops typing |
 
+React, edit, and delete are applied to the local `messages` model by the component itself in addition to emitting the event — your handler should persist the change to a backend, not re-apply it to `messages` (doing both double-applies). If the backend rejects a change, revert it with `updateMessage()` (or by reassigning `messages`) from your handler. Reactions work on any message (yours or another user's); edit and delete are owner-only. Delete asks for inline confirmation before removing. `message-send` is the exception: the component does not self-add the sent message, so your handler appends it.
+
 ## CSS Custom Properties
 
 | Property | Description |
@@ -132,6 +160,27 @@ interface MessageReaction {
 |------|-------------|
 | `base` | The chat container |
 | `messages` | The scrollable messages area |
+| `message` | A message row (every message) |
+| `message-own` | A message row authored by the current user |
+| `message-other` | A message row authored by someone else |
+| `system-message` | A system message row |
+| `avatar` | A message avatar |
+| `author` | A message author name |
+| `timestamp` | A message timestamp |
+| `edited` | The "(edited)" marker |
+| `message-text` | A message body |
+| `attachment` | A message attachment |
+| `reactions` | A message's reactions container |
+| `reaction` | A single reaction |
+| `reaction-active` | A reaction the current user has added |
+| `actions` | The hover action menu |
+| `edit-input` | The inline edit textarea (shown while editing) |
+| `edit-save` | The save button in the inline editor |
+| `edit-cancel` | The cancel button in the inline editor |
+| `delete-confirm` | The inline delete-confirmation row |
+| `delete-confirm-yes` | The confirm (delete) button |
+| `delete-confirm-no` | The cancel button in the delete confirmation |
+| `typing-indicator` | A typing indicator row |
 | `input-area` | The input area wrapper |
 | `input-container` | Container holding the input and buttons |
 | `input` | The message input field |
@@ -231,6 +280,63 @@ setTimeout(() => {
 }, 2000);
 ```
 
+### Declarative Messages
+
+Author messages as `snice-chat-message` children instead of the `messages` array. When both are present, child elements render first and array entries (including `addMessage()` calls) append after them. Slotted messages keep their identity across DOM updates, so reactions and edits made in the UI survive re-renders.
+
+```html
+<snice-chat current-user="Me">
+  <snice-chat-message slot="messages" author="Alice" timestamp="2026-05-26T09:24:00Z">Hey, deploy is green</snice-chat-message>
+  <snice-chat-message slot="messages" author="Me" timestamp="2026-05-26T09:25:00Z">Merging now</snice-chat-message>
+</snice-chat>
+```
+
+### Per-User Name Colors
+
+Set `colorAuthors` to auto-assign a stable color per author, or supply explicit colors with `authorColors`. A per-message `authorColor` overrides both.
+
+```html
+<snice-chat color-authors></snice-chat>
+```
+
+```javascript
+chat.authorColors = { Alice: '#e11d48', Bob: '#2563eb' };
+```
+
+### Markdown
+
+Set `markdown` to render every message body as markdown, or set `format: 'markdown'` per message. A per-message `format: 'text'` opts out of the component-wide default.
+
+```html
+<snice-chat markdown></snice-chat>
+```
+
+```javascript
+chat.addMessage({
+  type: 'text', author: 'Alice', timestamp: new Date(),
+  format: 'markdown',
+  content: 'shipped **v5.3** — run `npm i snice@latest`'
+});
+```
+
+### Bubble Layout
+
+Set `layout="bubbles"` for a mobile-OS style: own messages right-aligned in colored bubbles, others left.
+
+```html
+<snice-chat layout="bubbles" current-user="Me"></snice-chat>
+```
+
+### Custom Styling with Parts
+
+Every message internal is exposed as a CSS part.
+
+```css
+snice-chat::part(author)        { font-family: 'Inter'; }
+snice-chat::part(message-own)   { background: rgba(37, 99, 235, 0.06); }
+snice-chat::part(message-text)  { font-size: 0.9375rem; }
+```
+
 ## Accessibility
 
 - Keyboard navigation for messages and controls

package/docs/components/message-strip.md

@@ -3,7 +3,7 @@
 # Message Strip
 `<snice-message-strip>`
 
-An inline contextual message bar for displaying status messages within content flow. Unlike alerts (dismissable card), banners (full-width top), and toasts (floating), message strips are designed to sit inline within your content.
+An inline contextual message bar for displaying status messages within content flow. Unlike alerts (dismissible card), banners (full-width top), and toasts (floating), message strips are designed to sit inline within your content.
 
 ## Table of Contents
 - [Properties](#properties)
@@ -20,7 +20,7 @@ An inline contextual message bar for displaying status messages within content f
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `variant` | `'info' \| 'success' \| 'warning' \| 'danger'` | `'info'` | Message type / color |
-| `dismissable` | `boolean` | `false` | Show dismiss button |
+| `dismissible` | `boolean` | `false` | Show dismiss button |
 | `icon` | `string` | `''` | Custom icon (set "none" to hide default icon) |
 
 ## Methods
@@ -86,12 +86,12 @@ Use the `variant` attribute to indicate the message type.
 <snice-message-strip variant="danger">An error occurred while saving.</snice-message-strip>
 ```
 
-### Dismissable
+### Dismissible
 
-Set the `dismissable` attribute to allow users to close the message.
+Set the `dismissible` attribute to allow users to close the message.
 
 ```html
-<snice-message-strip variant="info" dismissable>
+<snice-message-strip variant="info" dismissible>
   You can dismiss this message.
 </snice-message-strip>
 ```
@@ -142,7 +142,7 @@ messageStrip.show();
 
 ```html
 <form>
-  <snice-message-strip variant="danger" dismissable style="display: none;">
+  <snice-message-strip variant="danger" dismissible style="display: none;">
     Please fill in all required fields.
   </snice-message-strip>
 
@@ -155,10 +155,10 @@ messageStrip.show();
 
 ```html
 <div style="display: flex; flex-direction: column; gap: 8px;">
-  <snice-message-strip variant="danger" dismissable>
+  <snice-message-strip variant="danger" dismissible>
     Server connection lost.
   </snice-message-strip>
-  <snice-message-strip variant="warning" dismissable>
+  <snice-message-strip variant="warning" dismissible>
     Your session will expire in 5 minutes.
   </snice-message-strip>
   <snice-message-strip variant="info">

package/docs/elements.md

@@ -995,6 +995,27 @@ class ReactiveComponent extends HTMLElement {
 }
 ```
 
+**Initial values.** By default a watcher fires once during initialization with the element's starting value — from markup (`<reactive-component user-name="Ada">`) or the field default — with `oldValue` undefined, then again on every later change:
+
+```typescript
+@watch('userName')
+onUserNameChange(oldVal: string | undefined, newVal: string) {
+  // Init:   (undefined, 'Ada')
+  // Change: ('Ada', 'Grace')
+}
+```
+
+Pass `{ immediate: false }` as the last argument for a change-only watcher — one that must not run on mount, such as a watcher that dispatches an event:
+
+```typescript
+@watch('value', { immediate: false })
+onValueChange(oldVal: string, newVal: string) {
+  this.dispatchChange();   // only on real changes, never on mount
+}
+```
+
+The options object always comes after the property names, so it works with multiple watched properties too: `@watch('width', 'height', { immediate: false })`.
+
 ### @context() Decorator
 
 Receive router context updates. The decorated method is called whenever the router context changes (navigation, app context update, etc.):

package/docs/events.md

@@ -385,9 +385,56 @@ interface OnOptions {
 
   // Shadow DOM delegation
   target?: string;             // CSS selector to target specific elements within shadow root
+
+  // Where to attach the listener (see scope section below)
+  scope?: 'global' | string | EventTarget | ((this: HTMLElement) => EventTarget | null);
 }
 ```
 
+#### scope — controlling the listener target
+
+By default, `@on` attaches the listener to the host element. The `scope` option redirects
+that attachment to another target, which is how Snice expresses cross-cutting events.
+
+| `scope` value | Listener attaches to |
+|---|---|
+| omitted | host element (default) |
+| `'global'` | `document` |
+| selector string | `host.closest(selector)` — nearest matching ancestor |
+| `Element` / `EventTarget` | that node directly |
+| `(this) => EventTarget \| null` | called at connect; `null` skips |
+
+The resolver function is called with the host element as `this` and re-resolves each time
+the component reconnects to the DOM, so listeners follow the host when it moves.
+
+```typescript
+// Cross-cutting global event (document)
+@on('bus:save', { scope: 'global' })
+onSave(e: CustomEvent) { /* ... */ }
+
+// Scoped to nearest ancestor matching the selector
+@on('bus:cart-added', { scope: 'cart-shell' })
+onCartAdded(e: CustomEvent) { /* ... */ }
+
+// Explicit EventTarget
+@on('go', { scope: someElement })
+onGo() { /* ... */ }
+
+// Resolver — full control, re-runs on reconnect
+@on('beep', { scope() { return this.closest('app-shell'); } })
+onBeep() { /* ... */ }
+```
+
+If `scope` cannot resolve (selector matches no ancestor, resolver returns `null` or throws),
+the listener is **not attached** and a `console.warn` is emitted. The component still
+mounts; only the listener is skipped.
+
+Disconnect removes the listener from whichever target it was attached to. Reconnect
+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.
+
 #### Throttling
 
 ```typescript
@@ -534,9 +581,50 @@ interface DispatchOptions extends EventInit {
   dispatchOnUndefined?: boolean; // Skip dispatch when return is undefined (default: true)
   debounce?: number;             // Debounce dispatch by ms
   throttle?: number;             // Throttle dispatch by ms
+  // Where to dispatch the event (see scope section below)
+  scope?: 'global' | string | EventTarget | ((this: HTMLElement) => EventTarget | null);
+}
+```
+
+#### 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
+event behaves as if it originated there. Use this with `@on({ scope })` to express
+cross-cutting events without going through bubbling.
+
+| `scope` value | Event dispatched on |
+|---|---|
+| omitted | host element (default) |
+| `'global'` | `document` |
+| selector string | `host.closest(selector)` — nearest matching ancestor |
+| `Element` / `EventTarget` | that node directly |
+| `(this) => EventTarget \| null` | called per dispatch; `null` skips |
+
+```typescript
+// Global cart-add bus
+@element('add-to-cart-button')
+class AddToCartButton extends HTMLElement {
+  @on('click', 'button')
+  click() { this.add(this.productId); }
+
+  @dispatch('bus:cart-added', { scope: 'global' })
+  add(id: string) { return { id }; }
+}
+
+// Listener on any other element
+@element('cart-counter')
+class CartCounter extends HTMLElement {
+  @on('bus:cart-added', { scope: 'global' })
+  bump() { this.count++; }
 }
 ```
 
+If `scope` cannot resolve (selector matches no ancestor, resolver returns `null`),
+the event is **not dispatched** and a `console.warn` is emitted. The method's return
+value still flows through `dispatchOnUndefined` / `debounce` / `throttle` semantics
+before the scope check.
+
 ### Debounce/Throttle
 
 ```typescript

package/docs/superpowers/specs/2026-05-26-chat-styling-design.md

@@ -0,0 +1,155 @@
+# snice-chat: full theming surface + declarative messages + markdown
+
+**Date:** 2026-05-26
+**Status:** Approved design, pre-implementation
+
+## Problem
+
+`snice-chat` is barely styleable. It exposes only 5 CSS parts (`base`, `messages`,
+`input-area`, `input-container`, `input`) and theme tokens. None of the per-message
+pieces — author name, avatar, timestamp, bubble, reactions — are reachable from
+outside the shadow DOM. There is no per-user color, no own-vs-other distinction
+(the component computes `isCurrentUser` but never writes it to the DOM), no
+markdown, and no declarative authoring API (it is imperative-only via `messages[]`).
+
+## Goals
+
+Deliver five capabilities, all **opt-in** and **purely additive** — the default
+render must be byte-for-byte identical to today:
+
+- **A · Per-user name colors** — each author's name colored, Slack/Discord style.
+- **B · Own vs other** — style "my" messages differently; ship an opt-in bubble layout.
+- **C · Bubble / message-type theming** — restyle bubble, system message, reactions, timestamps.
+- **D · Full part surface** — every internal element exposed as a CSS `::part`.
+- **E · Markdown** — render message content as markdown, opt-in.
+
+Plus the architectural change the user approved:
+
+- **Declarative `<snice-chat-message>` sub-element** giving `snice-chat` the dual API
+  (imperative array **or** slotted children) required of collection components.
+
+## Non-Goals (explicitly out of scope)
+
+- **CDN bundling of the new sub-element.** The known table/`snice-column` CDN
+  gotcha is not solved here. Do not touch the CDN build for this work.
+- Inline message editing UX (stays the existing `prompt()` behavior).
+- Threads / reaction pickers / any new interaction.
+
+## Architecture
+
+Follows the existing **table / `snice-column` pattern**: the sub-element is a
+declarative *config carrier*, not a self-rendering element. The parent keeps
+ownership of all rendering, so the styling part surface stays flat — no nested
+shadow DOM, no `exportparts` chaining.
+
+```
+<snice-chat>                         parent — owns rendering, owns the part surface
+  ├─ messages[] (imperative API)  ┐
+  │                               ├─ merged → renders message rows in its shadow DOM
+  └─ <snice-chat-message slot>  ──┘   (slot wins when present)
+        (declarative config carrier, render() = <slot></slot>, renders nothing)
+```
+
+Ingestion mirrors the table:
+
+```
+await customElements.whenDefined('snice-chat-message');
+const els = Array.from(this.querySelectorAll('snice-chat-message[slot="messages"]'));
+this.messages = els.map(el => el.getMessageDefinition());
+// re-read on bubbling 'message-changed'
+```
+
+## New element: `<snice-chat-message>`
+
+Files: `components/chat/snice-chat-message.ts`, `snice-chat-message.types.ts`, `snice-chat-message.css` (minimal).
+
+- `@element('snice-chat-message')`, `@render()` → `html\`<slot></slot>\``.
+- Attributes: `author`, `avatar`, `timestamp`, `type`, `format` (`text` | `markdown`),
+  `edited` (boolean), `author-color`.
+- Message body = default slot text content.
+- `getMessageDefinition(): ChatMessage` — serializes props to a `ChatMessage`.
+- Bubbles `message-changed` (`{ message: ChatMessage }`) on any prop change, so the
+  parent re-reads (same as `snice-column`'s `column-changed`).
+
+## `<snice-chat>` additions — all additive
+
+### 1. Dual API
+Keep `messages[]`, `addMessage`, `updateMessage`, `deleteMessage`, `clear`. Also
+ingest slotted `<snice-chat-message slot="messages">` via the table pattern above.
+Slot children win when present.
+
+### 2. Per-user name colors (A)
+- New property `authorColors: Record<string, string>` (override map).
+- New boolean attribute `color-authors` — opt-in to automatic coloring.
+- Resolution per message, computed inside the component instance (no global
+  registry, no singleton):
+  1. `authorColors[author]` if set, else
+  2. auto: stable hash of author name → fixed accent palette **only when `color-authors` is present**, else
+  3. unset → falls through to the current default color.
+- Implementation: author element gets `style="--snice-chat-author-color:${resolved}"`
+  when a color resolves; CSS reads `color: var(--snice-chat-author-color, <current default token>)`.
+  Inline-CSS-var injection is the established snice idiom (`--c`, `--bar-delay`,
+  `--volume-percent`, `--form-columns`). **No `data-*` styling hooks.**
+
+### 3. Own vs other (B)
+- Each message row gets space-separated part names: `part="message message-own"`
+  or `part="message message-other"` (the established stateful-variant idiom —
+  cf. `part="button first-button"`). Default CSS for these adds nothing visual.
+- Opt-in `layout="bubbles"` attribute ships the aligned colored-bubble look via
+  `:host([layout="bubbles"])` rules. Absent attribute = today's look.
+
+### 4. Bubble / type theming (C) + full part surface (D)
+Add `part=` to: `avatar`, `author`, `timestamp`, `edited`, `message-text`,
+`attachment`, `reactions`, `reaction`, `message-actions`, `system-message`,
+`typing-indicator`. (Generic role names; stateful variants via space-separated
+second names where applicable.)
+
+### 5. Markdown (E)
+- Add `format?: 'text' | 'markdown'` to `ChatMessage`.
+- New boolean attribute `markdown` — component-wide default.
+- A message renders as markdown when `message.format === 'markdown'`, or when the
+  `markdown` attribute is set and `message.format !== 'text'` (per-message `'text'`
+  overrides the component default).
+- Markdown rendered through the existing `<snice-markdown>` component; import follows
+  the existing `import '../empty-state/snice-empty-state'` precedent. Off by default.
+
+### Types
+- `ChatMessage` gains `format?: 'text' | 'markdown'`.
+- New `SniceChatMessageElement` interface + `SniceChatMessageEventMap`.
+- `snice-chat` gains `authorColors`, `markdown`, `colorAuthors`, `layout` on its element interface.
+
+## Deliverables
+
+- Source: the new element (3 files) + additive edits to `snice-chat.ts`, `.types.ts`, `.css`.
+- React adapter: metadata for `snice-chat` (new props) and new `snice-chat-message` in
+  `scripts/generate-react-adapters.js`; regenerate adapters + tests.
+- Tests: unit tests for both elements (see Verification).
+- Docs: `docs/components/chat.md` and `docs/ai/components/chat.md` updated to mirror —
+  new properties, attributes, parts, the sub-element, markdown, layout. Behavior + API
+  only; no internal symbol names or framework plumbing in the prose.
+- Showcase: update `public/showcases/chat.html` to demo the new capabilities.
+
+## Verification (required before calling done)
+
+- **Tests for everything authored.** Cover: dual-API ingestion (array, slot, both →
+  slot wins), boundary cases (no messages, one, many), author-color resolution
+  (map / auto / default / `color-authors` off), own/other part names, markdown
+  on/off and per-message override, all new parts present, default render unchanged.
+- **Full suite:** `npm test` — the whole vitest suite, not a filtered path. Every
+  failure is in scope to fix; no "pre-existing" excuses.
+- **Visual confirmation of all authored code** — exercise the live component in the
+  browser (showcase/demo), in **both dark and light** (Snice defaults to dark). Confirm:
+  default render unchanged, per-user colors, bubble layout, markdown, system messages,
+  reactions. Visual defects are bugs, not "polish later".
+
+## Key design decisions
+
+1. **Sub-element is a config carrier, not self-rendering** — mirrors `snice-column`.
+   Keeps the part surface on the parent's shadow DOM (flat `::part`, no `exportparts`).
+2. **Auto-coloring is opt-in (`color-authors`), not on by default** — preserves the
+   byte-for-byte-unchanged default render. `authorColors` map always wins over auto.
+3. **Per-author color via inline `--snice-chat-author-color`, not `data-*`** — matches
+   the snice dynamic-per-item idiom; `data-*` in snice are behavioral/JS hooks only.
+4. **Own/other via space-separated part names**, matching `part="button first-button"`.
+5. **Markdown reuses `<snice-markdown>`**, imported like the existing empty-state import.
+6. **CDN bundling of the sub-element is out of scope** by explicit instruction.