solid-drift 0.23.0 → 0.25.0

package/README.md

@@ -1473,6 +1473,67 @@ const beat = createHapticBeat(haptic, {
 - `createHapticBeat(haptic, options?)` returns `{ playing, bpm, step, start, stop, toggle, setBpm }`. The 16-step pattern uses `"x"` for a hit, `"X"` for an accent, anything else for a rest; steps run as 16th notes at `bpm` (live-changeable via `setBpm`), the downbeat fires immediately on `start()`, and `onStep(i)` reports each step index. `hapticBeatPresets` ships `heartbeat`, `metronome`, `ticks`, and `pulse`.
 - Haptics are tactile, not visual, so they fire under reduced motion too; the `enabled` switch is the way to offer quiet. Everything is a no-op where vibration is unsupported, and SSR-safe.
 
+### Bottom sheet
+
+A draggable bottom sheet built on `createDrag`: the user pulls it up by a handle (or the sheet itself) and on release it springs to the nearest snap point, projected forward by the release velocity like a native sheet. Dragging below the lowest snap (or a fast downward flick) dismisses it when `dismissible`.
+
+```tsx
+import { createBottomSheet } from "solid-drift"
+
+let sheet!: HTMLDivElement
+let handle!: HTMLDivElement
+const bs = createBottomSheet(() => handle, {
+  snapPoints: [0.4, 1],       // fractions of the sheet's own height
+  measureRef: () => sheet,    // measure the sheet, not the handle
+  onOpenChange: (open) => setScrimVisible(open),
+})
+
+<div
+  ref={sheet}
+  style={{
+    position: "fixed", left: "0", right: "0", bottom: "0",
+    transform: `translateY(${bs.y()}px)`,
+  }}
+>
+  <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+  <div>Sheet content</div>
+</div>
+<button onClick={() => bs.openSheet()}>Open</button>
+```
+
+- `createBottomSheet(ref, options?)` returns `{ open, snapIndex, y, status, openSheet, close, snapTo }`. `y()` is the current translateY in pixels; `status()` is `idle`, `dragging`, or `settling`; `snapIndex()` is the snap-point index or -1 when dismissed.
+- `snapPoints` are visible height fractions (`1` fully open); values are clamped to [0, 1] and sorted ascending, an empty array falls back to `[1]`. Default `[0.5, 1]`; `initialSnap` (default the fullest) picks the point `openSheet()` opens at.
+- While the pointer is down the sheet tracks 1:1 with light rubber-banding past the fully-open top and the dismissed bottom. On release, the target is the nearest snap to `y + velocity * 0.18`; dismissal happens past the midpoint between the lowest snap and closed, or on a downward flick over 700 px/s. Snap travel uses a spring (`options.spring`, default stiffness 400 / damping 40).
+- Bind `ref` to the drag handle when the sheet body scrolls (keeps drag and scroll from fighting), to the sheet root otherwise. The moving element gets `translateY(y())`; the drag target needs `touch-action: none`. Starts dismissed on the server (SSR-safe); under reduced motion it jumps straight to snap targets.
+
+### Streaming
+
+Token-by-token chat over OpenAI, Anthropic, Meta's Llama API, or your own provider, plus a low-level fetch-based SSE client for any event stream.
+
+```tsx
+import { createChatModel } from "solid-drift"
+
+const chat = createChatModel({
+  provider: "openai",
+  apiKey: () => localStorage.getItem("openai_key") ?? "",
+  model: "gpt-4o-mini",
+  system: "You are a concise assistant.",
+})
+
+// In your component:
+<For each={chat.messages()}>
+  {(m) => <div class={m.role}>{m.content}</div>}
+</For>
+<button onClick={() => chat.send(input())} disabled={chat.status() === "streaming"}>
+  Send
+</button>
+```
+
+- `createChatModel(options)` returns `{ messages, streamingText, status, error, send, stop, reset }`. `send(content)` appends the user message and streams the reply into a live assistant message, so UI bound to `messages()` renders token by token; `status()` is `idle`, `streaming`, or `error`. `stop()` aborts and keeps the partial reply; `send()` while streaming is ignored.
+- `provider` is `"openai"`, `"anthropic"`, `"meta"`, or a custom `{ kind: "custom", stream, parseDelta }`. OpenAI and Meta (Llama API via `/compat/v1`, OpenAI-compatible) use Bearer auth and `data:` chunks terminated by `[DONE]`; Anthropic uses `x-api-key` plus `anthropic-version: 2023-06-01`, a top-level `system` prompt, and `content_block_delta` text deltas (required `maxTokens` defaults to 1024).
+- Honest limitation: api.anthropic.com does not send CORS headers for browser origins, so from a browser Anthropic must go through your own server route or proxy; point `baseUrl` at it. For production with any provider, prefer a server route that holds the key and set `baseUrl` to it so keys never ship to the browser.
+- `createSSE(url, options?)` is a fetch-based event-stream client (`{ status, events, lastEvent, error, connect, disconnect }`): unlike `EventSource` it supports any method and custom headers, parses the full SSE framing (named events, multi-line data, comments, chunk splits), and leaves reconnection manual via `connect()`. SSR-safe: nothing connects until `connect()` (or `autoConnect`) runs on the client.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export { createSlotMachine, type SlotMachineControls, type SlotMachineOptions, t
 export { createStagger } from "./stagger.js";
 export { createDebounced, createThrottled, createLocalStorage, type LocalStorageOptions, type LocalStorageControls, createMediaQuery, createClickOutside, type ClickOutsideOptions, createScrollLock, type ScrollLockControls, createInfiniteScroll, type InfiniteScrollOptions, } from "./dom.js";
 export { createHaptic, hapticPatterns, type HapticOptions, type HapticControls, type HapticPattern, createHapticBeat, hapticBeatPresets, type HapticBeatOptions, type HapticBeatControls, } from "./haptic.js";
+export { createBottomSheet, type BottomSheetOptions, type BottomSheetControls, } from "./sheet.js";
 export { createHorizontalScroll, type HorizontalScrollOptions, type HorizontalScrollResult, } from "./horizontal.js";
 export { createScrub, type ScrubKeyframe, type ScrubOptions } from "./scrub.js";
 export { createScrollColor, type ScrollColorStop, type ScrollColorOptions, type ScrollColorFormat, createScrollTracking, type ScrollTrackingOptions, createScrollLine, type ScrollLineOptions, type ScrollLineStyle, type ScrollLineAxis, type ScrollLineOrigin, } from "./scrollfx.js";
@@ -39,3 +40,5 @@ export { createTxLifecycle, createTicker, createMintReveal, createConnectButton,
 export type { TxState, TxStatusInput, TxLifecycleOptions, TxLifecycleControls, TickerOptions, TickerControls, MintRevealStatus, MintRevealOptions, MintRevealControls, ConnectButtonOptions, ConnectButtonStatus, ConnectButtonControls, AgentTxState, AgentTxProposal, AgentTxOptions, AgentTxControls, } from "./web3.js";
 export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS, createChain, createTokenPrice, createPriceChange, createPriceCompare, createGasPrice, createBalance, createTxReceipt, createBlockNumber, createChainlinkPrice, createNFTMetadata, createENS, createIdenticon, } from "./web3data.js";
 export type { PollStatus, PollOptions, PollControls, ChainInfo, TokenPrice, TokenPriceOptions, PriceChangeOptions, GasPriceOptions, GasPriceData, BalanceOptions, BalanceData, TxReceiptData, TxReceiptOptions, BlockNumberOptions, ChainlinkPriceOptions, NFTMetadata, NFTMetadataOptions, ENSOptions, IdenticonOptions, } from "./web3data.js";
+export { createSSEParser, createSSE, createChatModel, } from "./stream.js";
+export type { SSEEvent, StreamStatus, SSEOptions, SSEControls, ChatMessage, ChatProviderKind, CustomChatProvider, ChatModelOptions, ChatModelControls, } from "./stream.js";

package/dist/index.js

@@ -16,6 +16,7 @@ export { createSlotMachine, createRedPacket, createConfetti, createEmojiBurst, c
 export { createStagger } from "./stagger.js";
 export { createDebounced, createThrottled, createLocalStorage, createMediaQuery, createClickOutside, createScrollLock, createInfiniteScroll, } from "./dom.js";
 export { createHaptic, hapticPatterns, createHapticBeat, hapticBeatPresets, } from "./haptic.js";
+export { createBottomSheet, } from "./sheet.js";
 export { createHorizontalScroll, } from "./horizontal.js";
 export { createScrub } from "./scrub.js";
 export { createScrollColor, createScrollTracking, createScrollLine, } from "./scrollfx.js";
@@ -35,3 +36,4 @@ export { createDrag, createSwipe, } from "./gesture.js";
 export { createStreamReveal, createAgentState, parseDriftSpec, createSpecPlayer, DriftSpecError, } from "./ai.js";
 export { createTxLifecycle, createTicker, createMintReveal, createConnectButton, createAgentTx, } from "./web3.js";
 export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS, createChain, createTokenPrice, createPriceChange, createPriceCompare, createGasPrice, createBalance, createTxReceipt, createBlockNumber, createChainlinkPrice, createNFTMetadata, createENS, createIdenticon, } from "./web3data.js";
+export { createSSEParser, createSSE, createChatModel, } from "./stream.js";

package/dist/sheet.d.ts

@@ -0,0 +1,99 @@
+import { type Accessor } from "solid-js";
+import { type DragStatus } from "./gesture.js";
+import type { SpringOptions } from "./spring.js";
+type MaybeElement = () => Element | null | undefined;
+export interface BottomSheetOptions {
+    /**
+     * Snap points as fractions of the sheet's own height. `1` is fully
+     * open, `0.4` shows 40% of the sheet. Values are clamped to
+     * [0, 1] and sorted ascending; an empty array falls back to [1].
+     * Default `[0.5, 1]`.
+     */
+    snapPoints?: number[];
+    /**
+     * Index into `snapPoints` opened by `openSheet()` with no argument.
+     * Default is the last point (fully open).
+     */
+    initialSnap?: number;
+    /**
+     * Dragging below the lowest snap dismisses the sheet on release.
+     * Default true.
+     */
+    dismissible?: boolean;
+    /** Spring physics for snap animations. Default `{ stiffness: 400, damping: 40 }`. */
+    spring?: SpringOptions;
+    /**
+     * Element used to measure the sheet height. Defaults to the drag
+     * ref. Pass the sheet root here when the drag ref is a handle, so
+     * snap fractions apply to the sheet and not the handle.
+     */
+    measureRef?: MaybeElement;
+    /** Called when the sheet opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+export interface BottomSheetControls {
+    /** Whether the sheet is open (not dismissed). */
+    open: Accessor<boolean>;
+    /** Index into `snapPoints`, or -1 when dismissed. */
+    snapIndex: Accessor<number>;
+    /**
+     * Current translateY in pixels. Drive the sheet's transform with
+     * this: `transform: translateY(${y()}px)`.
+     */
+    y: Accessor<number>;
+    /** `idle`, `dragging` while the pointer is down, `settling` while snapping. */
+    status: Accessor<DragStatus>;
+    /** Open the sheet at a snap point (default the fullest). */
+    openSheet: (index?: number) => void;
+    /** Dismiss the sheet below the screen. */
+    close: () => void;
+    /** Snap to a point by index (opens the sheet if dismissed). */
+    snapTo: (index: number) => void;
+}
+/**
+ * A draggable bottom sheet built on `createDrag`.
+ *
+ * The sheet is a fixed, bottom-anchored panel the user drags by a
+ * handle (or the sheet itself). On release it snaps to the nearest
+ * snap point, projected forward by the release velocity like a
+ * native sheet; a downward drag past the lowest point (or a fast
+ * downward flick) dismisses it when `dismissible`.
+ *
+ * The drag gesture itself, pointer tracking, release velocity, and
+ * reduced-motion behavior come from `createDrag`; this primitive
+ * adds the snap-point semantics on top. While the pointer is down
+ * the sheet tracks 1:1 with light rubber-banding past the top and
+ * bottom edges; on release it springs to the chosen point.
+ *
+ * Bind the `ref` to the drag handle when the sheet body scrolls
+ * (a handle keeps drag and scroll from fighting); bind it to the
+ * sheet root for non-scrolling sheets. Either way the moving
+ * element gets `transform: translateY(${y()}px)` and the drag
+ * target gets `touch-action: none`. When the drag ref is a handle,
+ * pass the sheet root as `options.measureRef` so snap fractions
+ * are measured against the sheet.
+ *
+ * SSR-safe: starts dismissed with `y()` at 0 on the server.
+ *
+ * ```tsx
+ * let sheet!: HTMLDivElement
+ * let handle!: HTMLDivElement
+ * const bs = createBottomSheet(() => handle, {
+ *   snapPoints: [0.4, 1],
+ *   measureRef: () => sheet,
+ * })
+ * <div
+ *   ref={sheet}
+ *   style={{
+ *     position: "fixed", left: "0", right: "0", bottom: "0",
+ *     transform: `translateY(${bs.y()}px)`,
+ *   }}
+ * >
+ *   <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+ *   <div>Sheet content</div>
+ * </div>
+ * <button onClick={() => bs.openSheet()}>Open</button>
+ * ```
+ */
+export declare function createBottomSheet(ref: MaybeElement, options?: BottomSheetOptions): BottomSheetControls;
+export {};

package/dist/sheet.js

@@ -0,0 +1,219 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { createDrag, } from "./gesture.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * A draggable bottom sheet built on `createDrag`.
+ *
+ * The sheet is a fixed, bottom-anchored panel the user drags by a
+ * handle (or the sheet itself). On release it snaps to the nearest
+ * snap point, projected forward by the release velocity like a
+ * native sheet; a downward drag past the lowest point (or a fast
+ * downward flick) dismisses it when `dismissible`.
+ *
+ * The drag gesture itself, pointer tracking, release velocity, and
+ * reduced-motion behavior come from `createDrag`; this primitive
+ * adds the snap-point semantics on top. While the pointer is down
+ * the sheet tracks 1:1 with light rubber-banding past the top and
+ * bottom edges; on release it springs to the chosen point.
+ *
+ * Bind the `ref` to the drag handle when the sheet body scrolls
+ * (a handle keeps drag and scroll from fighting); bind it to the
+ * sheet root for non-scrolling sheets. Either way the moving
+ * element gets `transform: translateY(${y()}px)` and the drag
+ * target gets `touch-action: none`. When the drag ref is a handle,
+ * pass the sheet root as `options.measureRef` so snap fractions
+ * are measured against the sheet.
+ *
+ * SSR-safe: starts dismissed with `y()` at 0 on the server.
+ *
+ * ```tsx
+ * let sheet!: HTMLDivElement
+ * let handle!: HTMLDivElement
+ * const bs = createBottomSheet(() => handle, {
+ *   snapPoints: [0.4, 1],
+ *   measureRef: () => sheet,
+ * })
+ * <div
+ *   ref={sheet}
+ *   style={{
+ *     position: "fixed", left: "0", right: "0", bottom: "0",
+ *     transform: `translateY(${bs.y()}px)`,
+ *   }}
+ * >
+ *   <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+ *   <div>Sheet content</div>
+ * </div>
+ * <button onClick={() => bs.openSheet()}>Open</button>
+ * ```
+ */
+export function createBottomSheet(ref, options = {}) {
+    const { snapPoints: snapPointsOption, initialSnap: initialSnapOption, dismissible = true, spring = {}, measureRef, onOpenChange, } = options;
+    // Snap points are visible height fractions, ascending. Values are
+    // clamped to [0, 1] and sorted; an empty list falls back to [1]
+    // (a single fully-open snap).
+    const snapPoints = (snapPointsOption?.length ? [...snapPointsOption] : [1])
+        .map((p) => Math.min(1, Math.max(0, p)))
+        .sort((a, b) => a - b);
+    const initialSnap = initialSnapOption ?? snapPoints.length - 1;
+    const [open, setOpen] = createSignal(false);
+    const [snapIndex, setSnapIndex] = createSignal(-1);
+    const [y, setY] = createSignal(0);
+    const [snapping, setSnapping] = createSignal(false);
+    // Sheet height in px, measured lazily from the element.
+    let height = 0;
+    const measure = () => {
+        const el = (measureRef ?? ref)();
+        if (el && typeof el.offsetHeight === "number") {
+            const h = el.offsetHeight;
+            if (h > 0)
+                height = h;
+        }
+        return height;
+    };
+    const snapY = (index) => height * (1 - snapPoints[index]);
+    const closedY = () => height;
+    // Snap animation: the same semi-implicit Euler spring the gesture
+    // primitives use.
+    let cancelSnap = null;
+    const animateTo = (target) => {
+        cancelSnap?.();
+        cancelSnap = null;
+        if (prefersReducedMotion()) {
+            setY(target);
+            setSnapping(false);
+            return;
+        }
+        const { stiffness = 400, damping = 40 } = spring;
+        let current = untrack(y);
+        let v = 0;
+        let last = now();
+        setSnapping(true);
+        const task = (t) => {
+            const dt = Math.min(Math.max((t - last) / 1000, 0), 0.064);
+            last = t;
+            v += (-stiffness * (current - target) - damping * v) * dt;
+            current += v * dt;
+            setY(current);
+            if (Math.abs(current - target) < 0.5 && Math.abs(v) < 20) {
+                setY(target);
+                setSnapping(false);
+                cancelSnap = null;
+                return false;
+            }
+            return true;
+        };
+        cancelSnap = schedule(task);
+    };
+    onCleanup(() => cancelSnap?.());
+    const openAt = (index) => {
+        measure();
+        const i = Math.max(0, Math.min(snapPoints.length - 1, index));
+        if (!untrack(open)) {
+            setOpen(true);
+            onOpenChange?.(true);
+        }
+        setSnapIndex(i);
+        animateTo(snapY(i));
+    };
+    const close = () => {
+        measure();
+        if (untrack(open)) {
+            setOpen(false);
+            onOpenChange?.(false);
+        }
+        setSnapIndex(-1);
+        animateTo(closedY());
+    };
+    // The underlying gesture: pointer tracking and release velocity.
+    // Its own y is only ever used as a per-grab delta source; the
+    // sheet position lives in `y` above.
+    let dragBase = 0;
+    let sheetBase = 0;
+    const settleFromRelease = (info) => {
+        measure();
+        const releaseY = untrack(y);
+        const projected = releaseY + info.velocityY * 0.18;
+        const lowest = snapY(0);
+        const dismissLine = (lowest + height) / 2;
+        if (dismissible &&
+            (projected >= dismissLine ||
+                (info.velocityY > 700 && projected > lowest))) {
+            close();
+            return;
+        }
+        let best = 0;
+        let bestDist = Math.abs(snapY(0) - projected);
+        for (let i = 1; i < snapPoints.length; i++) {
+            const d = Math.abs(snapY(i) - projected);
+            if (d < bestDist) {
+                bestDist = d;
+                best = i;
+            }
+        }
+        openAt(best);
+    };
+    const drag = createDrag(ref, {
+        axis: "y",
+        momentum: false, // the sheet chooses its own snap target
+        onDragStart: () => {
+            cancelSnap?.();
+            cancelSnap = null;
+            setSnapping(false);
+            measure();
+        },
+        onDragEnd: settleFromRelease,
+    });
+    // 1:1 tracking while the pointer is down, with rubber-banding past
+    // the fully-open top and the dismissed bottom. The grab bases are
+    // captured on the transition into "dragging" inside this effect:
+    // writes from event handlers flush effects synchronously, so the
+    // effect runs during setStatus("dragging"), before onDragStart.
+    // Capturing here keeps the bases correct under any scheduling.
+    let prevDragStatus = "idle";
+    createEffect(() => {
+        const s = drag.status();
+        if (s === "dragging" && prevDragStatus !== "dragging") {
+            dragBase = drag.y();
+            sheetBase = untrack(y);
+        }
+        prevDragStatus = s;
+        if (s !== "dragging")
+            return;
+        const raw = sheetBase + (drag.y() - dragBase);
+        const h = height;
+        let next = raw;
+        if (next < 0)
+            next = next * 0.3;
+        else if (next > h)
+            next = h + (next - h) * 0.3;
+        setY(next);
+    });
+    const status = () => {
+        if (drag.status() === "dragging")
+            return "dragging";
+        return snapping() ? "settling" : "idle";
+    };
+    // Client-only: park the dismissed sheet below the screen once the
+    // element (and its height) exists.
+    if (typeof window !== "undefined") {
+        createEffect(() => {
+            const el = ref();
+            const mel = (measureRef ?? ref)();
+            if (!el || !mel)
+                return;
+            const h = measure();
+            if (!untrack(open) && untrack(snapIndex) === -1)
+                setY(h);
+        });
+    }
+    return {
+        open,
+        snapIndex,
+        y,
+        status,
+        openSheet: (index = initialSnap) => openAt(index),
+        close,
+        snapTo: openAt,
+    };
+}

package/dist/stream.d.ts

@@ -0,0 +1,177 @@
+import { type Accessor } from "solid-js";
+/** One parsed Server-Sent Event. */
+export interface SSEEvent {
+    /** Event name; defaults to "message" when the stream sets none. */
+    event: string;
+    /** Payload: data lines joined with newlines. */
+    data: string;
+    /** Last `id:` field seen, if any. */
+    id?: string;
+}
+/**
+ * Feed raw text chunks through the SSE framing rules and call
+ * `onEvent` for each dispatched event. Handles events split across
+ * chunk boundaries, multi-line `data:` payloads, and `:` comments.
+ */
+export declare function createSSEParser(onEvent: (event: SSEEvent) => void): (chunk: string) => void;
+type FetchFn = typeof fetch;
+/** Connection state of a stream. */
+export type StreamStatus = "idle" | "connecting" | "open" | "closed" | "error";
+export interface SSEOptions {
+    /** HTTP method. Default "GET". */
+    method?: string;
+    /** Extra headers, or a function returning them per connection. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /** JSON-encoded request body (for POST-style SSE endpoints). */
+    body?: unknown;
+    /** Only surface events with this name. */
+    event?: string;
+    /** Called for each parsed event (after the name filter). */
+    onEvent?: (event: SSEEvent) => void;
+    /** Called when the stream opens (first byte accepted). */
+    onOpen?: () => void;
+    /** Called when the stream ends cleanly. */
+    onDone?: () => void;
+    /** Called on connection or HTTP errors. */
+    onError?: (error: Error) => void;
+    /** Connect immediately on creation. Default true. */
+    autoConnect?: boolean;
+    /** Fetch implementation (for tests or custom transports). */
+    fetchFn?: FetchFn;
+}
+export interface SSEControls {
+    /** Connection state. */
+    status: Accessor<StreamStatus>;
+    /** All parsed events received on this connection. */
+    events: Accessor<SSEEvent[]>;
+    /** The most recent event, if any. */
+    lastEvent: Accessor<SSEEvent | null>;
+    /** The last error, if any. */
+    error: Accessor<Error | null>;
+    /** Open (or re-open) the stream. */
+    connect: () => void;
+    /** Close the stream and abort the request. */
+    disconnect: () => void;
+}
+/**
+ * A fetch-based Server-Sent Events client.
+ *
+ * Unlike `EventSource`, this works with any HTTP method and custom
+ * headers, so it can reach authenticated or POST-style SSE endpoints.
+ * There is no automatic reconnection: a dropped stream moves to
+ * "closed" (or "error") and `connect()` re-opens it manually.
+ *
+ * SSR-safe: nothing connects until `connect()` runs (or
+ * `autoConnect` fires on the client).
+ *
+ * ```ts
+ * const sse = createSSE("https://api.example.com/events", {
+ *   headers: { Authorization: `Bearer ${token}` },
+ *   onEvent: (ev) => console.log(ev.event, ev.data),
+ * });
+ * sse.disconnect();
+ * ```
+ */
+export declare function createSSE(url: string | (() => string), options?: SSEOptions): SSEControls;
+/** A single chat turn. */
+export interface ChatMessage {
+    id: string;
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+/** Built-in provider kinds. */
+export type ChatProviderKind = "openai" | "anthropic" | "meta";
+/**
+ * Custom streaming provider. `stream` opens the request and returns
+ * the raw Response; `parseDelta` maps each SSE data payload to text
+ * (appended to the reply) or a done flag.
+ */
+export interface CustomChatProvider {
+    kind: "custom";
+    stream: (messages: ChatMessage[], context: {
+        signal: AbortSignal;
+        fetchFn: FetchFn;
+    }) => Promise<Response>;
+    parseDelta: (data: string, event?: string) => {
+        text?: string;
+        done?: boolean;
+    };
+}
+export interface ChatModelOptions {
+    /**
+     * Provider. Built-in kinds:
+     * - `"openai"`: chat completions, `data:` chunks, `[DONE]` terminator.
+     * - `"anthropic"`: messages API, `content_block_delta` text deltas.
+     *   Note: api.anthropic.com does not send CORS headers for browser
+     *   origins, so from a browser you must call it through your own
+     *   server route or proxy (set `baseUrl` to that proxy).
+     * - `"meta"`: Llama API, OpenAI-compatible via /compat/v1.
+     * - custom `{ kind: "custom", stream, parseDelta }`.
+     */
+    provider: ChatProviderKind | CustomChatProvider;
+    /** API key, or a function returning it. Sent as Bearer (openai/meta) or x-api-key (anthropic). */
+    apiKey?: string | (() => string | undefined);
+    /** Model name, e.g. "gpt-4o-mini", "claude-sonnet-4-20250514". */
+    model: string;
+    /** Override the API root. Defaults per provider kind. */
+    baseUrl?: string;
+    /** System prompt, sent as a system message (top-level `system` for anthropic). */
+    system?: string;
+    /** Sampling temperature, passed through when set. */
+    temperature?: number;
+    /** Max output tokens. Default 1024. Required by the anthropic API. */
+    maxTokens?: number;
+    /** Extra headers merged into the request. */
+    headers?: Record<string, string>;
+    /** Fetch implementation (for tests or custom transports). */
+    fetchFn?: FetchFn;
+    /** Called with the finished assistant message. */
+    onFinish?: (message: ChatMessage) => void;
+    /** Called on request or stream errors. */
+    onError?: (error: Error) => void;
+}
+export interface ChatModelControls {
+    /** Full conversation, including the in-progress reply. */
+    messages: Accessor<ChatMessage[]>;
+    /** The reply text streamed so far (empty when idle). */
+    streamingText: Accessor<string>;
+    /** `idle`, `streaming`, or `error`. */
+    status: Accessor<"idle" | "streaming" | "error">;
+    /** The last error, if any. */
+    error: Accessor<Error | null>;
+    /** Send a user message and stream the reply. Ignored while streaming. */
+    send: (content: string) => Promise<void>;
+    /** Abort the in-flight reply, keeping the partial text. */
+    stop: () => void;
+    /** Clear the conversation and abort any in-flight reply. */
+    reset: () => void;
+}
+/**
+ * Streaming chat over OpenAI, Anthropic, Meta (Llama API), or a
+ * custom provider.
+ *
+ * `send()` appends the user message, opens the provider stream, and
+ * appends text deltas to a live assistant message as they arrive, so
+ * UI bound to `messages()` renders the reply token by token. Pairs
+ * well with `createTyping` for a typewriter reveal.
+ *
+ * Keys stay in your hands: pass `apiKey` directly, or a function
+ * reading it from your own store. For production, prefer calling
+ * through your own server route and pointing `baseUrl` at it so
+ * keys never ship to the browser.
+ *
+ * SSR-safe: nothing connects until `send()` is called.
+ *
+ * ```ts
+ * const chat = createChatModel({
+ *   provider: "openai",
+ *   apiKey: () => localStorage.getItem("openai_key") ?? "",
+ *   model: "gpt-4o-mini",
+ *   system: "You are a concise assistant.",
+ *   onFinish: (msg) => console.log("done:", msg.content.length),
+ * });
+ * await chat.send("What is a signal?");
+ * ```
+ */
+export declare function createChatModel(options: ChatModelOptions): ChatModelControls;
+export {};

package/dist/stream.js

@@ -0,0 +1,430 @@
+import { createSignal, onCleanup } from "solid-js";
+/**
+ * Feed raw text chunks through the SSE framing rules and call
+ * `onEvent` for each dispatched event. Handles events split across
+ * chunk boundaries, multi-line `data:` payloads, and `:` comments.
+ */
+export function createSSEParser(onEvent) {
+    let buffer = "";
+    let event = "message";
+    let data = [];
+    let id;
+    const dispatch = () => {
+        if (data.length === 0 && event === "message") {
+            event = "message";
+            id = undefined;
+            return;
+        }
+        onEvent({ event, data: data.join("\n"), ...(id ? { id } : {}) });
+        event = "message";
+        data = [];
+        id = undefined;
+    };
+    return (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf("\n")) >= 0) {
+            let line = buffer.slice(0, nl);
+            buffer = buffer.slice(nl + 1);
+            if (line.endsWith("\r"))
+                line = line.slice(0, -1);
+            if (line === "") {
+                dispatch();
+                continue;
+            }
+            if (line.startsWith(":"))
+                continue; // comment / keep-alive
+            const colon = line.indexOf(":");
+            let field = line;
+            let value = "";
+            if (colon >= 0) {
+                field = line.slice(0, colon);
+                value = line.slice(colon + 1);
+                if (value.startsWith(" "))
+                    value = value.slice(1);
+            }
+            if (field === "event")
+                event = value;
+            else if (field === "data")
+                data.push(value);
+            else if (field === "id")
+                id = value;
+            // "retry:" is noted but reconnection stays manual: call connect().
+        }
+    };
+}
+/**
+ * Read a fetch Response body as SSE, dispatching parsed events.
+ * Resolves when the stream ends cleanly; rejects on HTTP errors.
+ */
+async function pumpSSE(response, onEvent, signal) {
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Stream request failed: ${response.status} ${response.statusText}${body ? ` - ${body.slice(0, 200)}` : ""}`);
+    }
+    const feed = createSSEParser(onEvent);
+    const reader = response.body?.getReader();
+    if (!reader)
+        return;
+    const decoder = new TextDecoder();
+    try {
+        for (;;) {
+            if (signal.aborted)
+                return;
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            feed(decoder.decode(value, { stream: true }));
+        }
+    }
+    finally {
+        feed(decoder.decode());
+        reader.releaseLock();
+    }
+}
+/**
+ * A fetch-based Server-Sent Events client.
+ *
+ * Unlike `EventSource`, this works with any HTTP method and custom
+ * headers, so it can reach authenticated or POST-style SSE endpoints.
+ * There is no automatic reconnection: a dropped stream moves to
+ * "closed" (or "error") and `connect()` re-opens it manually.
+ *
+ * SSR-safe: nothing connects until `connect()` runs (or
+ * `autoConnect` fires on the client).
+ *
+ * ```ts
+ * const sse = createSSE("https://api.example.com/events", {
+ *   headers: { Authorization: `Bearer ${token}` },
+ *   onEvent: (ev) => console.log(ev.event, ev.data),
+ * });
+ * sse.disconnect();
+ * ```
+ */
+export function createSSE(url, options = {}) {
+    const { method = "GET", headers, body, event: eventFilter, onEvent, onOpen, onDone, onError, autoConnect = true, fetchFn, } = options;
+    const [status, setStatus] = createSignal("idle");
+    const [events, setEvents] = createSignal([]);
+    const [lastEvent, setLastEvent] = createSignal(null);
+    const [error, setError] = createSignal(null);
+    let controller = null;
+    const disconnect = () => {
+        controller?.abort();
+        controller = null;
+        if (status() === "connecting" || status() === "open") {
+            setStatus("closed");
+        }
+    };
+    const connect = () => {
+        var _a;
+        disconnect();
+        const target = typeof url === "function" ? url() : url;
+        const fetchImpl = fetchFn ?? (typeof fetch !== "undefined" ? fetch : null);
+        if (!fetchImpl) {
+            const err = new Error("createSSE: no fetch implementation available");
+            setError(err);
+            setStatus("error");
+            onError?.(err);
+            return;
+        }
+        controller = new AbortController();
+        const signal = controller.signal;
+        setError(null);
+        setStatus("connecting");
+        const resolvedHeaders = typeof headers === "function" ? headers() : (headers ?? {});
+        const init = { method, headers: resolvedHeaders, signal };
+        if (body !== undefined) {
+            init.body = typeof body === "string" ? body : JSON.stringify(body);
+            (_a = init.headers)["Content-Type"] ?? (_a["Content-Type"] = "application/json");
+        }
+        void (async () => {
+            try {
+                const response = await fetchImpl(target, init);
+                if (signal.aborted)
+                    return;
+                setStatus("open");
+                onOpen?.();
+                await pumpSSE(response, (ev) => {
+                    if (eventFilter && ev.event !== eventFilter)
+                        return;
+                    setEvents((prev) => [...prev, ev]);
+                    setLastEvent(ev);
+                    onEvent?.(ev);
+                }, signal);
+                if (signal.aborted)
+                    return;
+                setStatus("closed");
+                onDone?.();
+            }
+            catch (err) {
+                if (signal.aborted)
+                    return;
+                const e = err instanceof Error ? err : new Error(String(err));
+                setError(e);
+                setStatus("error");
+                onError?.(e);
+            }
+        })();
+    };
+    onCleanup(disconnect);
+    if (autoConnect && typeof window !== "undefined")
+        connect();
+    return { status, events, lastEvent, error, connect, disconnect };
+}
+let chatMessageCounter = 0;
+const nextMessageId = () => `msg_${++chatMessageCounter}_${Date.now()}`;
+const defaultBaseUrl = (kind) => {
+    if (kind === "anthropic")
+        return "https://api.anthropic.com";
+    if (kind === "meta")
+        return "https://api.llama.com/compat/v1";
+    return "https://api.openai.com/v1";
+};
+function buildBuiltinRequest(kind, options, history, signal, fetchImpl) {
+    const base = (options.baseUrl ?? defaultBaseUrl(kind)).replace(/\/$/, "");
+    const key = typeof options.apiKey === "function" ? options.apiKey() : options.apiKey;
+    const extraHeaders = options.headers ?? {};
+    const temperature = options.temperature;
+    const maxTokens = options.maxTokens ?? 1024;
+    if (kind === "anthropic") {
+        const systemText = options.system ??
+            history.find((m) => m.role === "system")?.content;
+        const apiMessages = history
+            .filter((m) => m.role !== "system")
+            .map((m) => ({ role: m.role, content: m.content }));
+        const init = {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                ...(key ? { "x-api-key": key } : {}),
+                "anthropic-version": "2023-06-01",
+                ...extraHeaders,
+            },
+            body: JSON.stringify({
+                model: options.model,
+                max_tokens: maxTokens,
+                ...(systemText ? { system: systemText } : {}),
+                ...(temperature !== undefined ? { temperature } : {}),
+                messages: apiMessages,
+                stream: true,
+            }),
+            signal,
+        };
+        return {
+            url: `${base}/v1/messages`,
+            init,
+            parseDelta: (data, event) => {
+                if (event === "message_stop")
+                    return { done: true };
+                if (event === "error") {
+                    let message = "Anthropic stream error";
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (parsed.error?.message)
+                            message = parsed.error.message;
+                    }
+                    catch {
+                        if (data.trim())
+                            message = `Anthropic stream error: ${data.slice(0, 200)}`;
+                    }
+                    throw new Error(message);
+                }
+                if (event !== "content_block_delta")
+                    return {};
+                try {
+                    const parsed = JSON.parse(data);
+                    if (parsed.delta?.type === "text_delta" && parsed.delta.text) {
+                        return { text: parsed.delta.text };
+                    }
+                }
+                catch {
+                    // Ignore malformed delta payloads.
+                }
+                return {};
+            },
+        };
+    }
+    // openai + meta: OpenAI-compatible chat completions.
+    const init = {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(key ? { Authorization: `Bearer ${key}` } : {}),
+            ...extraHeaders,
+        },
+        body: JSON.stringify({
+            model: options.model,
+            messages: [
+                ...(options.system
+                    ? [{ role: "system", content: options.system }]
+                    : history
+                        .filter((m) => m.role === "system")
+                        .map((m) => ({ role: m.role, content: m.content }))),
+                ...history
+                    .filter((m) => m.role !== "system")
+                    .map((m) => ({ role: m.role, content: m.content })),
+            ],
+            ...(temperature !== undefined ? { temperature } : {}),
+            stream: true,
+        }),
+        signal,
+    };
+    return {
+        url: `${base}/chat/completions`,
+        init,
+        parseDelta: (data) => {
+            if (data.trim() === "[DONE]")
+                return { done: true };
+            let parsed;
+            try {
+                parsed = JSON.parse(data);
+            }
+            catch {
+                return {}; // ignore malformed chunks
+            }
+            if (parsed.error?.message)
+                throw new Error(parsed.error.message);
+            const text = parsed.choices?.[0]?.delta?.content;
+            return text ? { text } : {};
+        },
+    };
+}
+/**
+ * Streaming chat over OpenAI, Anthropic, Meta (Llama API), or a
+ * custom provider.
+ *
+ * `send()` appends the user message, opens the provider stream, and
+ * appends text deltas to a live assistant message as they arrive, so
+ * UI bound to `messages()` renders the reply token by token. Pairs
+ * well with `createTyping` for a typewriter reveal.
+ *
+ * Keys stay in your hands: pass `apiKey` directly, or a function
+ * reading it from your own store. For production, prefer calling
+ * through your own server route and pointing `baseUrl` at it so
+ * keys never ship to the browser.
+ *
+ * SSR-safe: nothing connects until `send()` is called.
+ *
+ * ```ts
+ * const chat = createChatModel({
+ *   provider: "openai",
+ *   apiKey: () => localStorage.getItem("openai_key") ?? "",
+ *   model: "gpt-4o-mini",
+ *   system: "You are a concise assistant.",
+ *   onFinish: (msg) => console.log("done:", msg.content.length),
+ * });
+ * await chat.send("What is a signal?");
+ * ```
+ */
+export function createChatModel(options) {
+    const [messages, setMessages] = createSignal(options.system
+        ? [{ id: nextMessageId(), role: "system", content: options.system }]
+        : []);
+    const [streamingText, setStreamingText] = createSignal("");
+    const [status, setStatus] = createSignal("idle");
+    const [error, setError] = createSignal(null);
+    let controller = null;
+    const stop = () => {
+        controller?.abort();
+        controller = null;
+        if (status() === "streaming")
+            setStatus("idle");
+    };
+    const reset = () => {
+        stop();
+        setError(null);
+        setStreamingText("");
+        setMessages(options.system
+            ? [{ id: nextMessageId(), role: "system", content: options.system }]
+            : []);
+    };
+    const send = async (content) => {
+        if (status() === "streaming")
+            return;
+        const fetchImpl = options.fetchFn ??
+            (typeof fetch !== "undefined" ? fetch : null);
+        if (!fetchImpl) {
+            const err = new Error("createChatModel: no fetch implementation available");
+            setError(err);
+            setStatus("error");
+            options.onError?.(err);
+            return;
+        }
+        const userMessage = {
+            id: nextMessageId(),
+            role: "user",
+            content,
+        };
+        const assistantMessage = {
+            id: nextMessageId(),
+            role: "assistant",
+            content: "",
+        };
+        const history = [...messages(), userMessage];
+        setMessages([...history, assistantMessage]);
+        setStreamingText("");
+        setError(null);
+        setStatus("streaming");
+        controller = new AbortController();
+        const signal = controller.signal;
+        const assistantId = assistantMessage.id;
+        const appendText = (text) => {
+            setStreamingText((prev) => prev + text);
+            setMessages((prev) => prev.map((m) => m.id === assistantId ? { ...m, content: m.content + text } : m));
+        };
+        try {
+            let response;
+            let parseDelta;
+            const provider = options.provider;
+            if (typeof provider === "object" && provider.kind === "custom") {
+                response = await provider.stream(history, { signal, fetchFn: fetchImpl });
+                parseDelta = provider.parseDelta;
+            }
+            else {
+                const kind = provider;
+                const built = buildBuiltinRequest(kind, options, history, signal, fetchImpl);
+                parseDelta = built.parseDelta;
+                response = await fetchImpl(built.url, built.init);
+            }
+            if (signal.aborted)
+                return;
+            let finished = false;
+            await pumpSSE(response, (ev) => {
+                if (finished)
+                    return;
+                let parsed;
+                try {
+                    parsed = parseDelta(ev.data, ev.event);
+                }
+                catch (e) {
+                    throw e instanceof Error ? e : new Error(String(e));
+                }
+                if (parsed.text)
+                    appendText(parsed.text);
+                if (parsed.done)
+                    finished = true;
+            }, signal);
+            if (signal.aborted)
+                return;
+            setStatus("idle");
+            const final = messages().find((m) => m.id === assistantId);
+            if (final)
+                options.onFinish?.(final);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                setStatus("idle");
+                return;
+            }
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            setStatus("error");
+            options.onError?.(e);
+        }
+        finally {
+            controller = null;
+        }
+    };
+    onCleanup(stop);
+    return { messages, streamingText, status, error, send, stop, reset };
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.23.0"
+  "version": "0.25.0"
 }