fancy-ui-svelte 0.9.1 → 0.11.0

package/dist/fancy-ui/sound/types.js

@@ -0,0 +1,59 @@
+/**
+ * Sound design — shared types and constants.
+ *
+ * Themes are DATA (a map from semantic cue to a synthesis recipe) and the
+ * engine is the interpreter. Components only ever name a cue; they never
+ * know how it sounds, which is what lets a future sound theme follow a visual
+ * skin without coupling audio code to it.
+ *
+ * This module has no runtime side effects and touches no browser global.
+ */
+/** Semantic UI cues. Every theme defines a recipe for each one. */
+export const SOUND_CUES = [
+    "hover",
+    "press",
+    "toggle-on",
+    "toggle-off",
+    "open",
+    "close",
+    "select",
+    "success",
+    "error",
+    "tick",
+    "copy",
+];
+export const SOUND_THEME_NAMES = ["fancy"];
+export const DEFAULT_SOUND_PREFERENCES = Object.freeze({
+    enabled: false,
+    volume: 0.5,
+    theme: "fancy",
+});
+export const SOUND_STORAGE_KEY = "fancy-ui-sound";
+/** Default same-cue minimum interval, ms. Engine-enforced, independent of the action's own guards. */
+export const SOUND_MIN_INTERVAL_MS = Object.freeze({
+    hover: 60,
+    tick: 40,
+    select: 40,
+    press: 15,
+    "toggle-on": 15,
+    "toggle-off": 15,
+    open: 15,
+    close: 15,
+    success: 15,
+    error: 15,
+    copy: 15,
+});
+/** Hard safety limits. Not configurable. */
+export const SOUND_LIMITS = Object.freeze({
+    /** Master gain = prefs.volume * MASTER_CEILING. */
+    MASTER_CEILING: 0.8,
+    /** Per-layer peak gain clamp. */
+    LAYER_PEAK_CEILING: 0.9,
+    /** Concurrent voices; extra `play()` calls are dropped, never steal. */
+    MAX_VOICES: 8,
+    /** Minimum attack / release enforced for click-free edges. */
+    MIN_ATTACK_MS: 2,
+    MIN_RELEASE_MS: 8,
+    /** Longest any single layer may run (guards a malformed theme). */
+    MAX_LAYER_MS: 400,
+});

package/dist/fancy-ui/sound/web-audio-mock.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Pure, dependency-free fakes for the Web Audio surface the sound engine uses.
+ *
+ * Imports nothing — no vitest — so it is safe to sit beside the engine it
+ * fakes: it is not exported from the barrel, it is never executed at runtime,
+ * and keeping it inside the folder means the colocated tests never reach
+ * outside the package root for it.
+ */
+export type AutomationMethod = "setValueAtTime" | "linearRampToValueAtTime" | "exponentialRampToValueAtTime" | "setTargetAtTime" | "cancelScheduledValues";
+export interface AutomationEvent {
+    method: AutomationMethod;
+    value: number;
+    time: number;
+    timeConstant?: number;
+}
+export declare class FakeAudioParam {
+    value: number;
+    readonly events: AutomationEvent[];
+    constructor(value?: number);
+    setValueAtTime(value: number, time: number): this;
+    linearRampToValueAtTime(value: number, time: number): this;
+    exponentialRampToValueAtTime(value: number, time: number): this;
+    setTargetAtTime(value: number, time: number, timeConstant: number): this;
+    cancelScheduledValues(time: number): this;
+}
+export declare class FakeAudioNode {
+    readonly context: FakeAudioContext;
+    readonly outputs: FakeAudioNode[];
+    disconnected: boolean;
+    constructor(context: FakeAudioContext);
+    connect(node: FakeAudioNode): FakeAudioNode;
+    disconnect(): void;
+}
+export declare class FakeGainNode extends FakeAudioNode {
+    readonly gain: FakeAudioParam;
+}
+export declare class FakeBiquadFilterNode extends FakeAudioNode {
+    type: BiquadFilterType;
+    readonly frequency: FakeAudioParam;
+    readonly Q: FakeAudioParam;
+    readonly detune: FakeAudioParam;
+    readonly gain: FakeAudioParam;
+}
+export declare class FakeDynamicsCompressorNode extends FakeAudioNode {
+    readonly threshold: FakeAudioParam;
+    readonly knee: FakeAudioParam;
+    readonly ratio: FakeAudioParam;
+    readonly attack: FakeAudioParam;
+    readonly release: FakeAudioParam;
+}
+export declare class FakeAudioBuffer {
+    readonly numberOfChannels: number;
+    readonly length: number;
+    readonly sampleRate: number;
+    private readonly channels;
+    constructor(numberOfChannels: number, length: number, sampleRate: number);
+    get duration(): number;
+    getChannelData(channel: number): Float32Array;
+}
+export declare class FakeScheduledSource extends FakeAudioNode {
+    startTime: number | null;
+    /** Second argument of `start()` — the buffer offset for AudioBufferSourceNode. */
+    startOffset: number | null;
+    stopTime: number | null;
+    onended: (() => void) | null;
+    ended: boolean;
+    start(when?: number, offset?: number): void;
+    stop(when?: number): void;
+    /** Test helper: simulate the source reaching its stop time. */
+    fireEnded(): void;
+}
+export declare class FakeOscillatorNode extends FakeScheduledSource {
+    type: OscillatorType;
+    readonly frequency: FakeAudioParam;
+    readonly detune: FakeAudioParam;
+}
+export declare class FakeBufferSourceNode extends FakeScheduledSource {
+    buffer: FakeAudioBuffer | null;
+    loop: boolean;
+    readonly playbackRate: FakeAudioParam;
+}
+export interface FakeAudioContextOptions {
+    /** Default "running". Real browsers often start "suspended" before a gesture. */
+    initialState?: AudioContextState;
+    /** What resume() does: "resolve" (→ running), "reject" (throws), "pending" (never settles). Default "resolve". */
+    resume?: "resolve" | "reject" | "pending";
+    /** Throw from the constructor (simulates a browser refusing a context). */
+    throwOnConstruct?: boolean;
+    sampleRate?: number;
+    /** Omit createDynamicsCompressor to simulate an engine that lacks it. */
+    withoutCompressor?: boolean;
+}
+export declare class FakeAudioContext {
+    state: AudioContextState;
+    currentTime: number;
+    readonly sampleRate: number;
+    readonly destination: FakeAudioNode;
+    readonly allNodes: FakeAudioNode[];
+    readonly created: {
+        gains: FakeGainNode[];
+        oscillators: FakeOscillatorNode[];
+        sources: FakeBufferSourceNode[];
+        filters: FakeBiquadFilterNode[];
+        compressors: FakeDynamicsCompressorNode[];
+        buffers: FakeAudioBuffer[];
+    };
+    resumeCalls: number;
+    suspendCalls: number;
+    closeCalls: number;
+    private readonly options;
+    private readonly listeners;
+    createDynamicsCompressor?: () => FakeDynamicsCompressorNode;
+    constructor(options?: FakeAudioContextOptions);
+    createGain(): FakeGainNode;
+    createOscillator(): FakeOscillatorNode;
+    createBufferSource(): FakeBufferSourceNode;
+    createBiquadFilter(): FakeBiquadFilterNode;
+    createBuffer(channels: number, length: number, sampleRate: number): FakeAudioBuffer;
+    resume(): Promise<void>;
+    suspend(): Promise<void>;
+    close(): Promise<void>;
+    addEventListener(_type: "statechange", cb: () => void): void;
+    removeEventListener(_type: "statechange", cb: () => void): void;
+    get onstatechange(): null;
+    /** Test helper: sets `state` and dispatches statechange. */
+    setState(next: AudioContextState): void;
+    /** Test helper: advances currentTime and fires `onended` on every source whose stopTime has passed. */
+    advance(seconds: number): void;
+    /** Every created node not yet disconnected (leak assertions). Excludes `destination`. */
+    liveNodes(): FakeAudioNode[];
+}
+export interface InstallOptions extends FakeAudioContextOptions {
+    /** Install only `webkitAudioContext` to exercise the prefixed fallback. */
+    webkitOnly?: boolean;
+}
+/**
+ * Installs a FakeAudioContext constructor as `AudioContext` (and/or
+ * `webkitAudioContext`) on `target`. Returns every instance constructed and a
+ * `restore()` that puts the previous globals back.
+ */
+export declare function installFakeAudioContext(target?: Record<string, unknown>, options?: InstallOptions): {
+    instances: FakeAudioContext[];
+    restore(): void;
+};

package/dist/fancy-ui/sound/web-audio-mock.js

@@ -0,0 +1,274 @@
+/**
+ * Pure, dependency-free fakes for the Web Audio surface the sound engine uses.
+ *
+ * Imports nothing — no vitest — so it is safe to sit beside the engine it
+ * fakes: it is not exported from the barrel, it is never executed at runtime,
+ * and keeping it inside the folder means the colocated tests never reach
+ * outside the package root for it.
+ */
+export class FakeAudioParam {
+    value;
+    events = [];
+    constructor(value = 0) {
+        this.value = value;
+    }
+    setValueAtTime(value, time) {
+        this.events.push({ method: "setValueAtTime", value, time });
+        this.value = value;
+        return this;
+    }
+    linearRampToValueAtTime(value, time) {
+        this.events.push({ method: "linearRampToValueAtTime", value, time });
+        return this;
+    }
+    exponentialRampToValueAtTime(value, time) {
+        this.events.push({ method: "exponentialRampToValueAtTime", value, time });
+        return this;
+    }
+    setTargetAtTime(value, time, timeConstant) {
+        this.events.push({ method: "setTargetAtTime", value, time, timeConstant });
+        return this;
+    }
+    cancelScheduledValues(time) {
+        this.events.push({ method: "cancelScheduledValues", value: this.value, time });
+        return this;
+    }
+}
+export class FakeAudioNode {
+    context;
+    outputs = [];
+    disconnected = false;
+    constructor(context) {
+        this.context = context;
+        context.allNodes.push(this);
+    }
+    connect(node) {
+        this.outputs.push(node);
+        return node;
+    }
+    disconnect() {
+        this.outputs.length = 0;
+        this.disconnected = true;
+    }
+}
+export class FakeGainNode extends FakeAudioNode {
+    gain = new FakeAudioParam(1);
+}
+export class FakeBiquadFilterNode extends FakeAudioNode {
+    type = "lowpass";
+    frequency = new FakeAudioParam(350);
+    Q = new FakeAudioParam(1);
+    detune = new FakeAudioParam(0);
+    gain = new FakeAudioParam(0);
+}
+export class FakeDynamicsCompressorNode extends FakeAudioNode {
+    threshold = new FakeAudioParam(-24);
+    knee = new FakeAudioParam(30);
+    ratio = new FakeAudioParam(12);
+    attack = new FakeAudioParam(0.003);
+    release = new FakeAudioParam(0.25);
+}
+export class FakeAudioBuffer {
+    numberOfChannels;
+    length;
+    sampleRate;
+    channels;
+    constructor(numberOfChannels, length, sampleRate) {
+        this.numberOfChannels = numberOfChannels;
+        this.length = length;
+        this.sampleRate = sampleRate;
+        this.channels = Array.from({ length: numberOfChannels }, () => new Float32Array(length));
+    }
+    get duration() {
+        return this.length / this.sampleRate;
+    }
+    getChannelData(channel) {
+        return this.channels[channel];
+    }
+}
+export class FakeScheduledSource extends FakeAudioNode {
+    startTime = null;
+    /** Second argument of `start()` — the buffer offset for AudioBufferSourceNode. */
+    startOffset = null;
+    stopTime = null;
+    onended = null;
+    ended = false;
+    start(when = 0, offset) {
+        this.startTime = when;
+        this.startOffset = offset ?? null;
+    }
+    stop(when = 0) {
+        this.stopTime = when;
+    }
+    /** Test helper: simulate the source reaching its stop time. */
+    fireEnded() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        this.onended?.();
+    }
+}
+export class FakeOscillatorNode extends FakeScheduledSource {
+    type = "sine";
+    frequency = new FakeAudioParam(440);
+    detune = new FakeAudioParam(0);
+}
+export class FakeBufferSourceNode extends FakeScheduledSource {
+    buffer = null;
+    loop = false;
+    playbackRate = new FakeAudioParam(1);
+}
+export class FakeAudioContext {
+    state;
+    currentTime = 0;
+    sampleRate;
+    destination;
+    allNodes = [];
+    created = {
+        gains: [],
+        oscillators: [],
+        sources: [],
+        filters: [],
+        compressors: [],
+        buffers: [],
+    };
+    resumeCalls = 0;
+    suspendCalls = 0;
+    closeCalls = 0;
+    options;
+    listeners = new Set();
+    // Assigned via a property so `delete` can simulate its absence.
+    createDynamicsCompressor;
+    constructor(options = {}) {
+        if (options.throwOnConstruct)
+            throw new Error("AudioContext refused");
+        this.options = options;
+        this.state = options.initialState ?? "running";
+        this.sampleRate = options.sampleRate ?? 48000;
+        this.destination = new FakeAudioNode(this);
+        // destination is not a "created" node
+        this.allNodes.length = 0;
+        if (!options.withoutCompressor) {
+            this.createDynamicsCompressor = () => {
+                const n = new FakeDynamicsCompressorNode(this);
+                this.created.compressors.push(n);
+                return n;
+            };
+        }
+    }
+    createGain() {
+        const n = new FakeGainNode(this);
+        this.created.gains.push(n);
+        return n;
+    }
+    createOscillator() {
+        const n = new FakeOscillatorNode(this);
+        this.created.oscillators.push(n);
+        return n;
+    }
+    createBufferSource() {
+        const n = new FakeBufferSourceNode(this);
+        this.created.sources.push(n);
+        return n;
+    }
+    createBiquadFilter() {
+        const n = new FakeBiquadFilterNode(this);
+        this.created.filters.push(n);
+        return n;
+    }
+    createBuffer(channels, length, sampleRate) {
+        const b = new FakeAudioBuffer(channels, length, sampleRate);
+        this.created.buffers.push(b);
+        return b;
+    }
+    resume() {
+        this.resumeCalls++;
+        const mode = this.options.resume ?? "resolve";
+        if (mode === "pending")
+            return new Promise(() => { });
+        if (mode === "reject")
+            return Promise.reject(new Error("resume rejected"));
+        if (this.state !== "closed")
+            this.setState("running");
+        return Promise.resolve();
+    }
+    suspend() {
+        this.suspendCalls++;
+        if (this.state !== "closed")
+            this.setState("suspended");
+        return Promise.resolve();
+    }
+    close() {
+        this.closeCalls++;
+        this.setState("closed");
+        return Promise.resolve();
+    }
+    addEventListener(_type, cb) {
+        this.listeners.add(cb);
+    }
+    removeEventListener(_type, cb) {
+        this.listeners.delete(cb);
+    }
+    get onstatechange() {
+        return null;
+    }
+    /** Test helper: sets `state` and dispatches statechange. */
+    setState(next) {
+        this.state = next;
+        for (const cb of [...this.listeners])
+            cb();
+    }
+    /** Test helper: advances currentTime and fires `onended` on every source whose stopTime has passed. */
+    advance(seconds) {
+        this.currentTime += seconds;
+        const sources = [...this.created.oscillators, ...this.created.sources];
+        for (const s of sources) {
+            if (!s.ended && s.stopTime !== null && s.stopTime <= this.currentTime)
+                s.fireEnded();
+        }
+    }
+    /** Every created node not yet disconnected (leak assertions). Excludes `destination`. */
+    liveNodes() {
+        return this.allNodes.filter((n) => !n.disconnected);
+    }
+}
+/**
+ * Installs a FakeAudioContext constructor as `AudioContext` (and/or
+ * `webkitAudioContext`) on `target`. Returns every instance constructed and a
+ * `restore()` that puts the previous globals back.
+ */
+export function installFakeAudioContext(target = globalThis, options = {}) {
+    const instances = [];
+    const { webkitOnly, ...ctxOptions } = options;
+    class InstalledAudioContext extends FakeAudioContext {
+        constructor() {
+            super(ctxOptions);
+            instances.push(this);
+        }
+    }
+    const prevStd = Object.getOwnPropertyDescriptor(target, "AudioContext");
+    const prevWebkit = Object.getOwnPropertyDescriptor(target, "webkitAudioContext");
+    const define = (key, value) => Object.defineProperty(target, key, { value, configurable: true, writable: true });
+    if (webkitOnly) {
+        define("AudioContext", undefined);
+        define("webkitAudioContext", InstalledAudioContext);
+    }
+    else {
+        define("AudioContext", InstalledAudioContext);
+        define("webkitAudioContext", InstalledAudioContext);
+    }
+    return {
+        instances,
+        restore() {
+            for (const [key, prev] of [
+                ["AudioContext", prevStd],
+                ["webkitAudioContext", prevWebkit],
+            ]) {
+                if (prev)
+                    Object.defineProperty(target, key, prev);
+                else
+                    delete target[key];
+            }
+        },
+    };
+}

package/dist/fancy-ui/sources/README.md

@@ -0,0 +1,189 @@
+# Sources
+
+The citations under an answer, as a pill you can ignore and a set of cards you can scan. Collapsed, it is a stack of monograms and a count; open, it is one card per document — title, host, and the line worth reading.
+
+## Components
+
+- `Sources` — the root. Holds the citation set and the open state, publishes context.
+- `SourcesTrigger` — the collapsed pill: monogram stack, count, chevron.
+- `SourcesList` — the expanding region of cards.
+- `SourceCard` — one citation. Works on its own, anywhere.
+
+The parts read the root through context, so they can sit anywhere inside it — directly in the root, or nested a few components deep in your own wrapper — without the sources or the open state being threaded down as props.
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { Sources } from "fancy-ui-svelte";
+
+	const sources = [
+		{
+			id: "s1",
+			title: "Designing citation surfaces",
+			url: "https://docs.example.dev/patterns/citations",
+			snippet: "A citation is a promise that the answer can be checked.",
+		},
+	];
+</script>
+
+<p>{answer}</p>
+<Sources {sources} />
+```
+
+That is the whole component. With no `children`, the root renders its own trigger and list, so the bare form is the one most answers want.
+
+### Composing it yourself
+
+Pass `children` and you place the parts — reordered, wrapped, or with only one of them present:
+
+```svelte
+<script lang="ts">
+	import { Sources, SourcesTrigger, SourcesList } from "fancy-ui-svelte";
+
+	let open = $state(false);
+</script>
+
+<Sources {sources} bind:open onToggle={(next) => track("sources", next)}>
+	<SourcesTrigger label="Checked against 4 papers" />
+	<SourcesList>
+		{#snippet item(source, index)}
+			<a href={source.url}>{index + 1}. {source.title}</a>
+		{/snippet}
+	</SourcesList>
+</Sources>
+```
+
+### `SourceCard` on its own
+
+The card has no context dependency at all, so it works anywhere a single citation needs rendering — a hover preview over an inline citation, a "cited by" rail, a search result:
+
+```svelte
+<script lang="ts">
+	import { SourceCard } from "fancy-ui-svelte";
+</script>
+
+<SourceCard source={sources[0]} />
+```
+
+It is the only part that behaves this way. The trigger and the list also survive being rendered outside a root — the pill reads `0 sources` and does nothing, the list renders empty and stays open — but there is no reason to do that on purpose.
+
+## Props
+
+### Sources
+
+| Prop       | Type                      | Default     | Description                                                  |
+| ---------- | ------------------------- | ----------- | ------------------------------------------------------------ |
+| `sources`  | `SourceData[]`            | —           | The documents backing the answer, in reading order. Required |
+| `open`     | `boolean`                 | `false`     | Whether the list is expanded. Bindable                       |
+| `onToggle` | `(open: boolean) => void` | `undefined` | Called when the pill is clicked, with the state it moved to  |
+| `children` | `Snippet`                 | `undefined` | Replaces the default trigger-and-list composition entirely   |
+| `class`    | `string`                  | `undefined` | Additional CSS classes                                       |
+| `ref`      | `HTMLDivElement \| null`  | `null`      | Bindable reference to the root `<div>`                       |
+
+`onToggle` fires only when the pill is clicked. Driving `open` yourself — through the binding or the prop — changes the state without calling it, which is what lets a caller tell "the reader opened this" apart from "I opened this".
+
+### SourcesTrigger
+
+| Prop    | Type     | Default     | Description                                                        |
+| ------- | -------- | ----------- | ------------------------------------------------------------------ |
+| `label` | `string` | `undefined` | Overrides the count line. Defaults to `4 sources`, singular at one |
+| `class` | `string` | `undefined` | Additional CSS classes                                             |
+
+### SourcesList
+
+| Prop    | Type                            | Default     | Description                                              |
+| ------- | ------------------------------- | ----------- | -------------------------------------------------------- |
+| `item`  | `Snippet<[SourceData, number]>` | `undefined` | Replaces the default card. Gets the source and its index |
+| `class` | `string`                        | `undefined` | Additional CSS classes, on the grid                      |
+
+### SourceCard
+
+| Prop     | Type         | Default     | Description                                       |
+| -------- | ------------ | ----------- | ------------------------------------------------- |
+| `source` | `SourceData` | —           | The document being cited. Required                |
+| `icon`   | `Snippet`    | `undefined` | Replaces the monogram: a favicon you host, a logo |
+| `class`  | `string`     | `undefined` | Additional CSS classes                            |
+
+## The data
+
+Every part reads the shared `SourceData` shape:
+
+```ts
+interface SourceData {
+	id: string;
+	title: string;
+	url: string;
+	snippet?: string;
+	domain?: string;
+}
+```
+
+Only `title` always renders. `domain` is shown when given and otherwise derived from `url` (minus the `www.`), so a caller who wants `the standards body` under a title can say so instead of getting `www.example.org`. A source with no usable `url` renders as a plain card rather than a link — a citation with nowhere to go is still worth showing, it just must not pretend to be clickable.
+
+## The context contract
+
+The root publishes this under `SOURCES_CONTEXT_KEY`:
+
+```ts
+interface SourcesContext {
+	readonly open: { readonly current: boolean };
+	readonly count: number;
+	readonly sources: readonly SourceData[];
+	readonly listId: string;
+	toggle(): void;
+}
+```
+
+Everything is a getter over the root's own props, so a part that reads it inside a reactive scope updates with the root. `listId` is the id the list puts on its region and the trigger points `aria-controls` at, which is the only way two sibling components can agree on one.
+
+Both the key and the type are exported, so you can build your own parts:
+
+```svelte
+<script lang="ts">
+	import { getContext } from "svelte";
+	import { SOURCES_CONTEXT_KEY, type SourcesContext } from "fancy-ui-svelte";
+
+	const sources = getContext<SourcesContext | undefined>(SOURCES_CONTEXT_KEY);
+</script>
+
+<button onclick={() => sources?.toggle()}>{sources?.count ?? 0} references</button>
+```
+
+Read it as optional. Every shipped part does, so a part rendered outside a root degrades instead of throwing.
+
+## Styling
+
+| Custom property              | Default                                              | Effect                                   |
+| ---------------------------- | ---------------------------------------------------- | ---------------------------------------- |
+| `--ft-sources-min-column`    | `13rem`                                              | Narrowest a card column may get          |
+| `--ft-sources-gap`           | `0.5rem`                                             | Space between cards                      |
+| `--ft-sources-card-bg`       | `color-mix(in oklab, currentColor 3%, transparent)`  | Card fill                                |
+| `--ft-sources-card-hover-bg` | `color-mix(in oklab, currentColor 7%, transparent)`  | Card and pill fill on hover              |
+| `--ft-sources-card-border`   | `var(--color-border, …)`                             | Card and pill border                     |
+| `--ft-sources-trigger-bg`    | `transparent`                                        | Pill fill at rest                        |
+| `--ft-sources-chip-bg`       | `color-mix(in oklab, currentColor 12%, transparent)` | Monogram fill                            |
+| `--ft-sources-chip-fg`       | `inherit`                                            | Monogram letter colour                   |
+| `--ft-sources-chip-ring`     | `var(--color-background, canvas)`                    | Ring cutting the stacked monograms apart |
+
+Set them on the component, or on any ancestor:
+
+```svelte
+<div style="--ft-sources-min-column: 100%; --ft-sources-chip-bg: var(--color-primary);">
+	<Sources {sources} />
+</div>
+```
+
+Setting `--ft-sources-min-column` to `100%` is how you force the single-column stack a narrow chat needs.
+
+## Implementation Notes
+
+- The list expands with `grid-template-rows: 0fr → 1fr`, which is the only way to transition an auto height without measuring anything. The inner wrapper does the clipping.
+- The collapsed region is `inert`. The cards are links, so leaving them reachable would drop a keyboard into content nobody can see.
+- Cards flow into `repeat(auto-fill, minmax(--ft-sources-min-column, 1fr))`, so the same list is a stack in a chat column and a grid in a document, with no breakpoint to configure.
+- The entrance stagger hangs off a class rather than mount, because the cards never unmount — collapsing is a height transition over live DOM, so re-adding the class is the only thing that can replay it. The delay is clamped at the seventh card: past a handful, a stagger stops reading as sequence and starts reading as lag.
+- Everything that moves — the expansion, the chevron, the stagger, the hover tints — lives inside `@media (prefers-reduced-motion: no-preference)`. Reduced motion gets the same states, instantly.
+- The monogram is a letter, never a favicon. Loading real favicons would mean a request from every reader's browser to every cited site — a tracking beacon nobody asked for, and a broken image the moment a site is gone. Pass `icon` if you host your own.
+- The letter is taken with the spread rather than `charAt`, so a title starting outside the BMP yields a whole character instead of half a surrogate pair.
+- Links carry `rel="noopener noreferrer nofollow ugc"` and `target="_blank"`: a model chose the destination, not the author of the page it sits on, and the tab it opens has no business reaching back into the app.
+- The trigger's monogram stack is `aria-hidden`. It is decoration; every name in it is spelled out in the list below.