@shogo-ai/voice 1.4.1

package/dist/organicParticlesShaders-DIva0vBO.d.ts

@@ -0,0 +1,693 @@
+import { UIMessage } from 'ai';
+
+/**
+ * Shared option / result types for `useVoiceConversation` across
+ * platforms. The web hook ([packages/sdk/src/voice/react]) and the
+ * native hook ([packages/sdk/src/voice/native]) both export their own
+ * `UseVoiceConversationOptions` / `UseVoiceConversationResult`
+ * types — typically by re-exporting `BaseVoiceConversationOptions` /
+ * `BaseVoiceConversationResult` from this module — so consumers can
+ * import them from whichever subpath they're using.
+ */
+interface BaseVoiceConversationOptions {
+    /** Name of the companion the user is talking to (passed as a dynamic variable). */
+    characterName: string;
+    /** Server path that mints an 11Labs signed URL for this user. Default: `/api/voice/signed-url`. */
+    signedUrlPath?: string;
+    /** Server path the built-in `add_memory` tool POSTs to. Default: `/api/memory/add`. */
+    memoryAddPath?: string;
+    /** Server path used to auto-inject memory context. Default: `/api/memory/retrieve`. */
+    memoryRetrievePath?: string;
+    /** Server path the transcript is POSTed to when the session ends. Default: `/api/memory/ingest`. */
+    transcriptIngestPath?: string;
+    /** Disable the built-in memory context auto-injection. Default: `true` (enabled). */
+    autoInjectMemory?: boolean;
+    /** Disable the built-in `add_memory` client tool. Default: `true` (enabled). */
+    includeMemoryTool?: boolean;
+    /**
+     * Additional client tools merged onto `add_memory`. Tools defined here with
+     * the name `add_memory` override the built-in implementation.
+     */
+    clientTools?: Record<string, (params: Record<string, unknown>) => Promise<string> | string>;
+    /**
+     * Called once per session with the accumulated transcript when the session
+     * disconnects. Defaults to POST `transcriptIngestPath`; set this to suppress
+     * or replace that behaviour.
+     */
+    onTranscript?: (transcript: string) => void | Promise<void>;
+    /**
+     * Credentials mode for built-in fetch calls.
+     *
+     * - Defaults to `same-origin` in the legacy cookie path.
+     * - Defaults to `omit` when `shogoApiKey` is provided (bearer auth is
+     *   self-contained and you don't want browsers to attach unrelated
+     *   third-party cookies cross-origin).
+     * - Explicit values always win — pass `'include'` to carry both a cookie
+     *   and the bearer in a hybrid same-origin app.
+     */
+    fetchCredentials?: RequestCredentials;
+    /**
+     * Shogo API key (`shogo_sk_*`) used to authenticate voice routes. When
+     * provided, the hook attaches `Authorization: Bearer <key>` to the
+     * signed-URL fetch and memory fetches, and appends `?projectId=` to
+     * the signed-URL path. Either `shogoApiKey` or a session cookie must
+     * be resolvable by the server — both may be passed; the server's
+     * `apiKeyOrSession` middleware picks bearer first.
+     */
+    shogoApiKey?: string;
+    /**
+     * Project id (Shogo's `projectId`). Required alongside `shogoApiKey`
+     * for Mode B voice. The server uses it to look up / provision the
+     * project's ElevenLabs agent and resolve the workspace.
+     */
+    projectId?: string;
+    /**
+     * Optional named agent to talk to. Forwarded as `?agentName=` on
+     * the signed-URL fetch and resolved server-side to a project-scoped
+     * `ProjectAgent` row (created via `shogo deploy`). When omitted,
+     * the server resolves the project's `default` agent.
+     *
+     * The same `agentName` reaches the same persona via
+     * `useChatConversation({ agentName })` — voice and chat are two
+     * transports for one agent record.
+     */
+    agentName?: string;
+    /** Called on connection errors. */
+    onError?: (error: unknown) => void;
+    /** Called on each message (user or agent) for debugging / custom UI. */
+    onMessage?: (message: {
+        source: string;
+        message: string;
+    }) => void;
+    /**
+     * Stable conversation id used to correlate this voice session with
+     * a sibling text thread (see `BaseChatConversationOptions.conversationId`).
+     *
+     * When set, forwarded to ElevenLabs as a `conversation_id` dynamic
+     * variable so the agent's prompt can reference it (`{{conversation_id}}`),
+     * and surfaced on `BaseVoiceConversationResult.conversationId` so a
+     * single bridge component can read the same value from either hook.
+     *
+     * Independent of the convai-side conversation id — see
+     * `BaseVoiceConversationResult.convaiConversationId` for that. The
+     * caller-supplied value wins on `result.conversationId` so consumers
+     * who keep their own thread store don't have to special-case the
+     * default. Optional; when omitted, `result.conversationId` mirrors
+     * the convai conversation id once the session connects.
+     */
+    conversationId?: string;
+    /**
+     * Extra dynamic variables forwarded to ElevenLabs at session start.
+     * Merged on top of the SDK's built-in variables — `character_name`,
+     * `user_context`, and `conversation_id` (when supplied) always win
+     * on collision so consumers can't accidentally override them.
+     *
+     * Typical use: surface per-user fields from the consumer's own
+     * `Companion` row (display name, relationship stage, custom greeting
+     * tokens) so the agent's prompt can reference them via
+     * `{{var_name}}`. Variables also need to be declared in the agent's
+     * `dynamic_variable_placeholders` (set at deploy time) for EL to
+     * pick up the value.
+     *
+     * Non-string values are coerced via `String(...)` before being
+     * forwarded; `null` / `undefined` values are silently dropped.
+     */
+    dynamicVariables?: Record<string, unknown> | null;
+}
+interface BaseVoiceConversationResult {
+    /**
+     * Begin a new session. Requests microphone permission and fetches a
+     * signed URL.
+     *
+     * `suppressFirstMessage` mirrors the option on `restart()` — when
+     * `true`, the new session is opened with `overrides.agent.firstMessage = ''`
+     * so the agent skips its opening greeting. Useful when the consumer
+     * is programmatically reconnecting (e.g. to deliver a one-shot spoken
+     * summary) and does not want to hear the configured intro.
+     */
+    start: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** End the current session (if any). */
+    end: () => void;
+    /**
+     * Tear down the active session and immediately reconnect. Primarily
+     * used as a programmatic barge-in: ElevenLabs doesn't expose a public
+     * `interrupt()` on `useConversation`, so stopping the agent mid-
+     * utterance requires a fast disconnect + reconnect. When
+     * `suppressFirstMessage` is `true` (the default), the new session is
+     * started with `overrides.agent.firstMessage = ''` so the agent does
+     * not replay its intro. The accumulated transcript is preserved
+     * across the reconnect gap.
+     */
+    restart: (options?: {
+        suppressFirstMessage?: boolean;
+    }) => Promise<void>;
+    /** `'disconnected' | 'connecting' | 'connected'`. */
+    status: 'disconnected' | 'connecting' | 'connected';
+    /** Whether the agent is currently speaking. */
+    isSpeaking: boolean;
+    /** Whether the agent is currently listening. */
+    isListening: boolean;
+    /** Whether the microphone is currently muted (input audio is gated off). */
+    isMuted: boolean;
+    /**
+     * Toggle the microphone mute state without tearing down the session.
+     * Wraps `@elevenlabs/react` (or `@elevenlabs/react-native`)'s
+     * `setMuted`, which in turn calls `conversation.setMicMuted()`.
+     * Muting does not end the WebSocket or release the underlying media
+     * stream; it simply stops input audio from being forwarded to the
+     * server.
+     */
+    setMuted: (isMuted: boolean) => void;
+    /** For consumers who want to drive their own visualisation / lipsync. */
+    getOutputByteFrequencyData: () => Uint8Array | null;
+    /** Imperatively send a contextual update (e.g. "user navigated to X"). */
+    sendContextualUpdate: (text: string) => void;
+    /**
+     * Imperatively inject a user-role message, forcing the agent to take
+     * its next turn immediately (rather than waiting for the human to
+     * speak). Useful for out-of-band prompts like "please summarise what
+     * just happened". The injected text is *not* spoken aloud — the agent
+     * treats it as if the user said it.
+     */
+    sendUserMessage: (text: string) => void;
+    /**
+     * Low-level signal that the user is active (typing, clicking) so the
+     * agent doesn't try to fill silence. Used as a fallback nudge when we
+     * want to keep the session "warm" without forcing a full turn.
+     */
+    sendUserActivity: () => void;
+    /**
+     * Stable conversation id for cross-transport correlation. Returns the
+     * caller-supplied `BaseVoiceConversationOptions.conversationId` when
+     * one was provided; otherwise mirrors the convai conversation id once
+     * the session connects (and is `null` while disconnected).
+     *
+     * Pass this same value to `useChatConversation({ conversationId })`
+     * to stitch a text thread onto the same logical conversation.
+     */
+    conversationId: string | null;
+    /**
+     * The convai-side conversation id reported by ElevenLabs on connect.
+     * Always reflects the underlying transport id (or `null` while
+     * disconnected) regardless of whether the consumer supplied an id.
+     * Useful for log correlation against ElevenLabs dashboards even
+     * when the consumer is using their own ids on `conversationId`.
+     */
+    convaiConversationId: string | null;
+}
+
+/**
+ * Shared option / result types for `useChatConversation` across
+ * platforms.
+ *
+ * The text-chat hook is the audio-free sibling of
+ * `useVoiceConversation` (see `./types.ts`): it talks to the same
+ * underlying agent persona, reuses the same auth surface
+ * (`shogoApiKey` + `projectId` or session cookie), and exposes the
+ * same client-tool registration shape — but the wire transport is a
+ * plain streaming HTTP POST instead of an ElevenLabs Convai WebSocket.
+ *
+ * Why a separate `Base*ChatConversation*` instead of overloading the
+ * voice option types: the audio-vs-text wire differences (no
+ * `signedUrlPath`, no transcript persistence flush, no
+ * `firstMessage`/`characterName` dynamic variables, no `setMuted`,
+ * etc.) are large enough that conflating them produces a worse public
+ * API. Instead, both `Base*` shapes deliberately share the auth /
+ * `projectId` / `conversationId` fields verbatim so consumers can
+ * thread a single config object through both hooks in a "shared
+ * agent, two transports" app — see `packages/sdk/README.md` §"Voice
+ * + text bridge" for the canonical pattern.
+ *
+ * Web (`packages/sdk/src/voice/react/useChatConversation.ts`) and
+ * native (`packages/sdk/src/voice/native/useChatConversation.ts`) both
+ * re-export `BaseChatConversation*` as their own concrete option /
+ * result types so consumers can import whichever subpath matches
+ * their platform without crossing the platform boundary.
+ */
+
+/**
+ * Tool implementation surface accepted by `useChatConversation`.
+ * Mirrors `ClientToolFn` in `./memory.ts` (which the voice hook uses)
+ * so the same tool map drops cleanly into both hooks.
+ *
+ * Tools are resolved client-side: the server route declares each tool
+ * WITHOUT an `execute` function, the model produces a tool-call event,
+ * and the hook calls into this map and POSTs the result back via
+ * `addToolOutput`. Any returned string is forwarded to the agent as
+ * the tool result; thrown errors are surfaced as `output-error`.
+ */
+type ChatClientToolFn = (params: Record<string, unknown>) => string | Promise<string>;
+/** Status surface mirroring `@ai-sdk/react`'s `useChat().status`. */
+type ChatConversationStatus = 'ready' | 'submitted' | 'streaming' | 'error';
+/**
+ * Per-tool wire spec sent to the server as part of the request body.
+ *
+ * The server re-declares each tool to the model so it can produce
+ * tool-call events. Unlike voice (where the agent is provisioned with
+ * its tools server-side once), text consumers register tools per
+ * client because the same agent prompt may want to drive different
+ * client-resident effects on different surfaces. We accept a
+ * JSON-Schema-shaped descriptor here — the SDK does not depend on
+ * `zod` so consumers are free to write the schemas inline.
+ *
+ * The server validates the descriptor before passing it to the model
+ * and rejects unknown shapes; see `apps/api/src/routes/chat.ts`.
+ */
+interface ChatToolDescriptor {
+    /** Stable tool name (must match the key under `clientTools`). */
+    name: string;
+    /** Free-form description handed to the model. */
+    description: string;
+    /**
+     * JSON Schema for the tool's input. Keep this small — long schemas
+     * inflate every turn's prompt. `type: 'object'` with a flat
+     * `properties` map covers ~all real cases.
+     */
+    inputSchema: Record<string, unknown>;
+}
+interface BaseChatConversationOptions {
+    /**
+     * Streaming chat endpoint URL. Defaults to `'/api/chat/turn'` (the
+     * route shipped in `apps/api`). Override to point at a custom
+     * deployment or to embed query params other than `projectId` /
+     * `conversationId`.
+     *
+     * The hook appends `?projectId=` and `?conversationId=` to whatever
+     * value is supplied here, so a `?foo=bar` already on the URL is
+     * preserved.
+     */
+    api?: string;
+    /**
+     * Shogo API key (`shogo_sk_*`). When set, attached as
+     * `Authorization: Bearer <key>` on every request and
+     * `?projectId=` is appended. Mirrors the option of the same name
+     * on `BaseVoiceConversationOptions`.
+     */
+    shogoApiKey?: string;
+    /**
+     * Project id. Required when `shogoApiKey` is set so the server can
+     * resolve the project's persona prompt, memory, and tool allowlist.
+     * Mirrors `BaseVoiceConversationOptions.projectId`.
+     */
+    projectId?: string;
+    /**
+     * Optional named agent to converse with. Appended to the chat URL
+     * as `?agentName=` and resolved server-side to a project-scoped
+     * `ProjectAgent` row whose `systemPrompt` / `model` / tool
+     * allowlist drive this turn. When omitted, the server resolves the
+     * project's `default` agent (or falls back to its built-in
+     * persona for projects predating the agents table).
+     *
+     * The same `agentName` reaches the same persona via
+     * `useVoiceConversation({ agentName })` — voice and chat are two
+     * transports for one agent record.
+     */
+    agentName?: string;
+    /**
+     * Stable conversation id used by the consumer to correlate this
+     * text thread with a sibling voice session (see
+     * `BaseVoiceConversationResult.conversationId`). The value is
+     * forwarded to the server in the request body so durable transcripts
+     * land under the same row, and is appended to the URL as
+     * `?conversationId=` for log correlation.
+     *
+     * Optional — if omitted, the server treats each turn as a free-
+     * standing thread (state-via-`messages`-array). Most consumers want
+     * to set this to keep voice + text under one logical conversation.
+     */
+    conversationId?: string;
+    /**
+     * Initial messages used to seed the in-memory thread on first
+     * mount. Useful for cross-modality merging (e.g. seed with the
+     * voice transcript before opening text), prefilling a greeting, or
+     * resuming a stored thread. Forwarded to `useChat({ messages })`.
+     *
+     * Subsequent updates should go through `setMessages(...)` on the
+     * returned hook surface — changing `initialMessages` after first
+     * render does NOT replay them.
+     */
+    initialMessages?: UIMessage[];
+    /**
+     * Client-side tool implementations keyed by tool name. The
+     * companion `tools` descriptor list is what the server registers
+     * with the model on each turn; the keys must match.
+     */
+    clientTools?: Record<string, ChatClientToolFn>;
+    /**
+     * Tool descriptors forwarded to the server in the request body.
+     * Empty / undefined ships the request without any tools (the
+     * server's default agent persona still runs, just with no tool
+     * surface). Required when `clientTools` is non-empty — the server
+     * needs both halves to declare the tool to the model.
+     */
+    tools?: ChatToolDescriptor[];
+    /**
+     * Credentials mode for `fetch`. Defaults to `'same-origin'` on
+     * web (matches `useShogoVoice`), `'omit'` on native when
+     * `shogoApiKey` is set or `'include'` otherwise (matches
+     * `useShogoVoice` native defaults).
+     */
+    fetchCredentials?: RequestCredentials;
+    /**
+     * Stable id forwarded to `useChat({ id })`. Only used to keep the
+     * AI-SDK chat instance keyed across re-renders / route changes; not
+     * sent on the wire. Defaults to a value derived from
+     * `conversationId` (or a per-mount fallback).
+     */
+    id?: string;
+    /** Called on transport / model errors. */
+    onError?: (error: unknown) => void;
+    /**
+     * Per-user dynamic variables forwarded with each chat turn. Mirrors
+     * the option of the same name on `BaseVoiceConversationOptions` so a
+     * single config object can drive both hooks.
+     *
+     * V1 plumbs this through to the request body — server-side rendering
+     * into the system prompt is not yet wired up. Treat it as forwards-
+     * compatible: setting the value today is safe and lets the server
+     * pick it up once support lands without a SDK bump.
+     */
+    dynamicVariables?: Record<string, unknown> | null;
+}
+interface BaseChatConversationResult {
+    /** Live message list mirroring `useChat().messages`. */
+    messages: UIMessage[];
+    /**
+     * Send a new user turn. Resolves once the request leaves the
+     * client; the returned promise does NOT wait for the assistant
+     * stream to finish — observe `messages` / `status` for that.
+     */
+    sendMessage: (text: string) => Promise<void>;
+    /**
+     * Replace the current in-memory thread. Useful for hydrating from
+     * a persisted store, seeding with a sibling voice transcript, or
+     * surgically rewriting an earlier turn. Forwarded directly to
+     * `useChat().setMessages`.
+     */
+    setMessages: (messages: UIMessage[]) => void;
+    /**
+     * Append a synthetic assistant message without making a model
+     * call. Use for prefilling a deterministic first-turn greeting,
+     * surfacing a heartbeat from a sibling voice session as if the
+     * agent had spoken it, etc. Generates an id locally; the message
+     * is NOT echoed to the server.
+     */
+    appendAssistantMessage: (text: string) => void;
+    /**
+     * Append a synthetic user message without dispatching a turn.
+     * Symmetric counterpart to `appendAssistantMessage` — useful for
+     * merging a voice transcript turn into the text thread without
+     * round-tripping through the model.
+     */
+    appendUserMessage: (text: string) => void;
+    /** Current request lifecycle. See `ChatConversationStatus`. */
+    status: ChatConversationStatus;
+    /**
+     * The `conversationId` the hook is currently using. Returns the
+     * caller-supplied option verbatim, or `null` when none was set.
+     * Provided so a single bridge component can read the value from
+     * either hook without juggling default-vs-override logic.
+     */
+    conversationId: string | null;
+}
+
+/**
+ * Configuration surface for the `OrganicSphere` audio-reactive
+ * visualization. All values are plain numbers / strings / null so the
+ * whole object is JSON-serializable — save it, transport it, paste it
+ * into a preset library.
+ *
+ * The sphere renders four eased "variations" driven by frequency bands:
+ *
+ *   low    → modulates time-evolution speed (drift + noise phase)
+ *   volume → drives `uDisplacementStrength` (how far each vertex pushes
+ *            out from the sphere surface)
+ *   medium → drives `uFresnelMultiplier` (how bright the lighting pass
+ *            gets near silhouette edges)
+ *   high   → drives `uDistortionStrength` (large-scale warping of the
+ *            underlying position field before displacement)
+ *
+ * Each variation has a resting `idle` value used when audio is off, a
+ * `gain` multiplier applied to the band level, a `floor` minimum while
+ * audio is playing, and separate attack / decay easing rates.
+ *
+ * Use `resolveOrganicSphereConfig(partial)` to merge a partial override
+ * into the defaults; `OrganicSphere` does this internally so consumers
+ * can pass any subset.
+ */
+interface BandReactivity {
+    /** Resting target used when no audio source is connected. */
+    idle: number;
+    /** Multiplier applied to the normalized band level (0–1) while audio plays. */
+    gain: number;
+    /** Minimum target while audio is playing, before easing. */
+    floor: number;
+    /**
+     * Easing rate when the target rises above `current` (snappier attack
+     * at higher values; per-ms-of-frame delta, not per-frame).
+     */
+    attack: number;
+    /** Easing rate when the target falls below `current` (per-ms). */
+    decay: number;
+}
+interface OrganicSphereConfig {
+    /** Color of light A (default is a deep Shogo burnt orange). */
+    lightAColor: string;
+    /** Color of light B (default is a warm Shogo amber). */
+    lightBColor: string;
+    /** Intensity multiplier for light A. Higher = brighter contribution. */
+    lightAIntensity: number;
+    /** Intensity multiplier for light B. */
+    lightBIntensity: number;
+    /**
+     * Rim-highlight color. `null` falls back to `lightBColor`, which keeps
+     * the silhouette monochromatic and impossible to wash out to white.
+     */
+    rimColor: string | null;
+    /**
+     * Fresnel value above which the rim starts contributing. Higher →
+     * tighter rim; lower → rim bleeds across more of the surface.
+     */
+    rimThreshold: number;
+    /** Exponent on the rim falloff curve. Higher → sharper edge. */
+    rimPower: number;
+    /** Spatial frequency of the distortion noise (`uDistortionFrequency`). */
+    distortionFrequency: number;
+    /** Spatial frequency of the displacement noise (`uDisplacementFrequency`). */
+    displacementFrequency: number;
+    /** Fresnel offset — shifts where the rim and lighting gradient peak. */
+    fresnelOffset: number;
+    /** Fresnel power — steepens or softens the lighting gradient. */
+    fresnelPower: number;
+    /**
+     * Volume variation → `uDisplacementStrength`. Driven by the loudest
+     * of the first three bands (`max(l0, l1, l2)`).
+     */
+    volume: BandReactivity;
+    /** Mid-band variation → `uFresnelMultiplier`. Driven by `l1`. */
+    medium: BandReactivity;
+    /** High-band variation → `uDistortionStrength`. Driven by `l2`. */
+    high: BandReactivity;
+    /**
+     * Low-band variation → time evolution speed (how fast the noise
+     * offset scrolls). Driven by `l0`.
+     */
+    low: BandReactivity;
+    /** Camera z-position. Larger = more zoomed out. */
+    cameraZ: number;
+    /** Vertical field-of-view in degrees. */
+    fov: number;
+    /**
+     * Seed used to derive the initial "wander" offset phase, so identical
+     * audio produces identical visuals across playbacks. Any integer is
+     * fine; change it to roll a different starting pose. When `active`
+     * flips from `false` → `true`, the sphere resets to this phase.
+     */
+    seed: number;
+    /**
+     * Sphere mesh subdivisions. Higher = smoother displacement, more GPU
+     * cost. Changing at runtime triggers a scene rebuild.
+     */
+    subdivisions: number;
+    /**
+     * Device-pixel-ratio cap. `null` picks `min(devicePixelRatio, 2)`.
+     * Set to `1` for lower-end devices.
+     */
+    maxPixelRatio: number | null;
+    /**
+     * Scene clear color. `null` keeps the canvas fully transparent so the
+     * sphere blends into the host UI.
+     */
+    backgroundColor: string | null;
+}
+/**
+ * Preset tuned for Shogo's Voice Mode hero — warm Shogo orange palette,
+ * rim tied to `lightBColor`, camera zoomed back so the sphere reads
+ * "contained" rather than "looming", reactivity values copied from
+ * Bruno Simon's upstream `organic-sphere` demo so silhouettes animate
+ * faithfully.
+ */
+declare const DEFAULT_ORGANIC_SPHERE_CONFIG: OrganicSphereConfig;
+/**
+ * Merge a partial override into `DEFAULT_ORGANIC_SPHERE_CONFIG`, doing a
+ * shallow merge on the root + per-band merge on `volume/medium/high/low`
+ * so consumers only need to specify what they want to change.
+ */
+declare function resolveOrganicSphereConfig(partial?: Partial<OrganicSphereConfig>): OrganicSphereConfig;
+
+/**
+ * Configuration surface for the `OrganicParticles` audio-reactive
+ * visualization — a particle-cloud sibling of `OrganicSphere`.
+ *
+ * Shares the same `BandReactivity` shape and four-band model
+ * (volume / medium / high / low) as the sphere, so audio-tuning muscle
+ * memory carries over. What changes is the cloud-specific fields:
+ *
+ *   volume → radial displacement (how far the cloud bursts outward)
+ *   medium → particle size boost (how puffy each point renders)
+ *   high   → swirl strength (how much the cloud twists)
+ *   low    → time evolution speed (noise phase drift)
+ *
+ * Like `OrganicSphereConfig`, everything is JSON-serializable.
+ */
+
+interface OrganicParticlesConfig {
+    /**
+     * Number of particles. Changing this rebuilds the scene. Sweet spot
+     * for visual density without frame-drop is 20k–80k on a modern GPU.
+     */
+    count: number;
+    /**
+     * Inner / outer radius of the seeded spawn shell. Particles are
+     * uniformly distributed between these two radii so the cloud has
+     * perceptible thickness rather than sitting on a single sphere.
+     */
+    innerRadius: number;
+    outerRadius: number;
+    /** Spatial frequency of the Perlin noise warp. */
+    noiseFrequency: number;
+    /** Strength of the noise warp. */
+    noiseStrength: number;
+    /**
+     * Constant per-ms Y-axis rotation applied to the whole cloud,
+     * independent of audio. `0` (default) means the cloud is perfectly
+     * still when no audio plays. Positive = spin right, negative = left.
+     */
+    rotationBias: number;
+    /**
+     * Rate (per ms) at which `uTime` advances the per-particle swirl
+     * angle in the shader, independent of audio. `0` (default) = swirl
+     * only responds to audio high-band + particle height.
+     */
+    swirlTimeRate: number;
+    /**
+     * Rate (per ms) at which `uTime` advances while the cloud is idle
+     * (i.e. `active === false`). Lets the Perlin noise field keep
+     * shimmering subtly when nothing is playing so the cloud doesn't feel
+     * dead. `0` = fully frozen when paused. Default `0.0001` ≈ one full
+     * noise period every ~10 s — perceptible but not distracting.
+     */
+    idleNoiseRate: number;
+    /** Base particle size (before audio boost / perspective scaling). */
+    sizeBase: number;
+    /**
+     * Edge softness of each particle sprite, in [0, 1]. `0` = hard disc,
+     * `1` = heavy feather/plasma. ~0.6 reads as "nebula".
+     */
+    softness: number;
+    /** Overall opacity multiplier. */
+    opacity: number;
+    /** Color at the cloud core (low `vHeat`). */
+    colorCool: string;
+    /** Color at the cloud fringe (high `vHeat`). */
+    colorHot: string;
+    /** volume → radial displacement push. */
+    volume: BandReactivity;
+    /** medium → per-particle size boost. */
+    medium: BandReactivity;
+    /** high → swirl / twist amount. */
+    high: BandReactivity;
+    /** low → time evolution speed. */
+    low: BandReactivity;
+    cameraZ: number;
+    fov: number;
+    /**
+     * Seed used to generate the initial particle positions AND the wander
+     * phase. Same seed + same audio → same visual across playbacks.
+     */
+    seed: number;
+    /** `null` picks `min(devicePixelRatio, 2)`. */
+    maxPixelRatio: number | null;
+    /** Scene clear color. `null` = transparent. */
+    backgroundColor: string | null;
+}
+/**
+ * Preset tuned to match the Shogo warm-orange palette used by
+ * `DEFAULT_ORGANIC_SPHERE_CONFIG`, so the two modes read as siblings.
+ * Count/size defaults target 60fps on mid-tier GPUs.
+ */
+declare const DEFAULT_ORGANIC_PARTICLES_CONFIG: OrganicParticlesConfig;
+/**
+ * Merge a partial override into `DEFAULT_ORGANIC_PARTICLES_CONFIG`,
+ * with per-band shallow merges for `volume/medium/high/low`.
+ */
+declare function resolveOrganicParticlesConfig(partial?: Partial<OrganicParticlesConfig>): OrganicParticlesConfig;
+
+/**
+ * GLSL shaders for the `OrganicSphere` audio-reactive visualization.
+ *
+ * Ported from Bruno Simon's open-source "organic-sphere" demo
+ * (https://github.com/brunosimon/organic-sphere — no license declared
+ * in the upstream repo at time of vendoring; treat as MIT-spirit
+ * reference code per the author's public body of work). The original
+ * uses a glslify `#pragma require` for the Perlin noise partial; we
+ * inline the partial here so the bundle is self-contained and the
+ * host app does not need a GLSL bundler plugin.
+ *
+ * The Perlin 3D/4D noise is Stefan Gustavson's classic implementation
+ * (public domain — see https://github.com/stegu/webgl-noise).
+ */
+/**
+ * Classic Perlin 4D noise (Stefan Gustavson). Inlined, used by every
+ * organic-* vertex shader in this module. Exported so sibling shader
+ * files (e.g. `organicParticlesShaders.ts`) can concatenate it without
+ * re-vendoring the implementation.
+ */
+declare const PERLIN_4D = "\nvec4 permute(vec4 x){return mod(((x*34.0)+1.0)*x, 289.0);}\nvec4 taylorInvSqrt(vec4 r){return 1.79284291400159 - 0.85373472095314 * r;}\nvec4 fade(vec4 t) {return t*t*t*(t*(t*6.0-15.0)+10.0);}\n\nfloat perlin4d(vec4 P){\n  vec4 Pi0 = floor(P);\n  vec4 Pi1 = Pi0 + 1.0;\n  Pi0 = mod(Pi0, 289.0);\n  Pi1 = mod(Pi1, 289.0);\n  vec4 Pf0 = fract(P);\n  vec4 Pf1 = Pf0 - 1.0;\n  vec4 ix = vec4(Pi0.x, Pi1.x, Pi0.x, Pi1.x);\n  vec4 iy = vec4(Pi0.yy, Pi1.yy);\n  vec4 iz0 = vec4(Pi0.zzzz);\n  vec4 iz1 = vec4(Pi1.zzzz);\n  vec4 iw0 = vec4(Pi0.wwww);\n  vec4 iw1 = vec4(Pi1.wwww);\n\n  vec4 ixy = permute(permute(ix) + iy);\n  vec4 ixy0 = permute(ixy + iz0);\n  vec4 ixy1 = permute(ixy + iz1);\n  vec4 ixy00 = permute(ixy0 + iw0);\n  vec4 ixy01 = permute(ixy0 + iw1);\n  vec4 ixy10 = permute(ixy1 + iw0);\n  vec4 ixy11 = permute(ixy1 + iw1);\n\n  vec4 gx00 = ixy00 / 7.0;\n  vec4 gy00 = floor(gx00) / 7.0;\n  vec4 gz00 = floor(gy00) / 6.0;\n  gx00 = fract(gx00) - 0.5;\n  gy00 = fract(gy00) - 0.5;\n  gz00 = fract(gz00) - 0.5;\n  vec4 gw00 = vec4(0.75) - abs(gx00) - abs(gy00) - abs(gz00);\n  vec4 sw00 = step(gw00, vec4(0.0));\n  gx00 -= sw00 * (step(0.0, gx00) - 0.5);\n  gy00 -= sw00 * (step(0.0, gy00) - 0.5);\n\n  vec4 gx01 = ixy01 / 7.0;\n  vec4 gy01 = floor(gx01) / 7.0;\n  vec4 gz01 = floor(gy01) / 6.0;\n  gx01 = fract(gx01) - 0.5;\n  gy01 = fract(gy01) - 0.5;\n  gz01 = fract(gz01) - 0.5;\n  vec4 gw01 = vec4(0.75) - abs(gx01) - abs(gy01) - abs(gz01);\n  vec4 sw01 = step(gw01, vec4(0.0));\n  gx01 -= sw01 * (step(0.0, gx01) - 0.5);\n  gy01 -= sw01 * (step(0.0, gy01) - 0.5);\n\n  vec4 gx10 = ixy10 / 7.0;\n  vec4 gy10 = floor(gx10) / 7.0;\n  vec4 gz10 = floor(gy10) / 6.0;\n  gx10 = fract(gx10) - 0.5;\n  gy10 = fract(gy10) - 0.5;\n  gz10 = fract(gz10) - 0.5;\n  vec4 gw10 = vec4(0.75) - abs(gx10) - abs(gy10) - abs(gz10);\n  vec4 sw10 = step(gw10, vec4(0.0));\n  gx10 -= sw10 * (step(0.0, gx10) - 0.5);\n  gy10 -= sw10 * (step(0.0, gy10) - 0.5);\n\n  vec4 gx11 = ixy11 / 7.0;\n  vec4 gy11 = floor(gx11) / 7.0;\n  vec4 gz11 = floor(gy11) / 6.0;\n  gx11 = fract(gx11) - 0.5;\n  gy11 = fract(gy11) - 0.5;\n  gz11 = fract(gz11) - 0.5;\n  vec4 gw11 = vec4(0.75) - abs(gx11) - abs(gy11) - abs(gz11);\n  vec4 sw11 = step(gw11, vec4(0.0));\n  gx11 -= sw11 * (step(0.0, gx11) - 0.5);\n  gy11 -= sw11 * (step(0.0, gy11) - 0.5);\n\n  vec4 g0000 = vec4(gx00.x,gy00.x,gz00.x,gw00.x);\n  vec4 g1000 = vec4(gx00.y,gy00.y,gz00.y,gw00.y);\n  vec4 g0100 = vec4(gx00.z,gy00.z,gz00.z,gw00.z);\n  vec4 g1100 = vec4(gx00.w,gy00.w,gz00.w,gw00.w);\n  vec4 g0010 = vec4(gx10.x,gy10.x,gz10.x,gw10.x);\n  vec4 g1010 = vec4(gx10.y,gy10.y,gz10.y,gw10.y);\n  vec4 g0110 = vec4(gx10.z,gy10.z,gz10.z,gw10.z);\n  vec4 g1110 = vec4(gx10.w,gy10.w,gz10.w,gw10.w);\n  vec4 g0001 = vec4(gx01.x,gy01.x,gz01.x,gw01.x);\n  vec4 g1001 = vec4(gx01.y,gy01.y,gz01.y,gw01.y);\n  vec4 g0101 = vec4(gx01.z,gy01.z,gz01.z,gw01.z);\n  vec4 g1101 = vec4(gx01.w,gy01.w,gz01.w,gw01.w);\n  vec4 g0011 = vec4(gx11.x,gy11.x,gz11.x,gw11.x);\n  vec4 g1011 = vec4(gx11.y,gy11.y,gz11.y,gw11.y);\n  vec4 g0111 = vec4(gx11.z,gy11.z,gz11.z,gw11.z);\n  vec4 g1111 = vec4(gx11.w,gy11.w,gz11.w,gw11.w);\n\n  vec4 norm00 = taylorInvSqrt(vec4(dot(g0000, g0000), dot(g0100, g0100), dot(g1000, g1000), dot(g1100, g1100)));\n  g0000 *= norm00.x; g0100 *= norm00.y; g1000 *= norm00.z; g1100 *= norm00.w;\n\n  vec4 norm01 = taylorInvSqrt(vec4(dot(g0001, g0001), dot(g0101, g0101), dot(g1001, g1001), dot(g1101, g1101)));\n  g0001 *= norm01.x; g0101 *= norm01.y; g1001 *= norm01.z; g1101 *= norm01.w;\n\n  vec4 norm10 = taylorInvSqrt(vec4(dot(g0010, g0010), dot(g0110, g0110), dot(g1010, g1010), dot(g1110, g1110)));\n  g0010 *= norm10.x; g0110 *= norm10.y; g1010 *= norm10.z; g1110 *= norm10.w;\n\n  vec4 norm11 = taylorInvSqrt(vec4(dot(g0011, g0011), dot(g0111, g0111), dot(g1011, g1011), dot(g1111, g1111)));\n  g0011 *= norm11.x; g0111 *= norm11.y; g1011 *= norm11.z; g1111 *= norm11.w;\n\n  float n0000 = dot(g0000, Pf0);\n  float n1000 = dot(g1000, vec4(Pf1.x, Pf0.yzw));\n  float n0100 = dot(g0100, vec4(Pf0.x, Pf1.y, Pf0.zw));\n  float n1100 = dot(g1100, vec4(Pf1.xy, Pf0.zw));\n  float n0010 = dot(g0010, vec4(Pf0.xy, Pf1.z, Pf0.w));\n  float n1010 = dot(g1010, vec4(Pf1.x, Pf0.y, Pf1.z, Pf0.w));\n  float n0110 = dot(g0110, vec4(Pf0.x, Pf1.yz, Pf0.w));\n  float n1110 = dot(g1110, vec4(Pf1.xyz, Pf0.w));\n  float n0001 = dot(g0001, vec4(Pf0.xyz, Pf1.w));\n  float n1001 = dot(g1001, vec4(Pf1.x, Pf0.yz, Pf1.w));\n  float n0101 = dot(g0101, vec4(Pf0.x, Pf1.y, Pf0.z, Pf1.w));\n  float n1101 = dot(g1101, vec4(Pf1.xy, Pf0.z, Pf1.w));\n  float n0011 = dot(g0011, vec4(Pf0.xy, Pf1.zw));\n  float n1011 = dot(g1011, vec4(Pf1.x, Pf0.y, Pf1.zw));\n  float n0111 = dot(g0111, vec4(Pf0.x, Pf1.yzw));\n  float n1111 = dot(g1111, Pf1);\n\n  vec4 fade_xyzw = fade(Pf0);\n  vec4 n_0w = mix(vec4(n0000, n1000, n0100, n1100), vec4(n0001, n1001, n0101, n1101), fade_xyzw.w);\n  vec4 n_1w = mix(vec4(n0010, n1010, n0110, n1110), vec4(n0011, n1011, n0111, n1111), fade_xyzw.w);\n  vec4 n_zw = mix(n_0w, n_1w, fade_xyzw.z);\n  vec2 n_yzw = mix(n_zw.xy, n_zw.zw, fade_xyzw.y);\n  float n_xyzw = mix(n_yzw.x, n_yzw.y, fade_xyzw.x);\n  return 2.2 * n_xyzw;\n}\n";
+declare const ORGANIC_SPHERE_VERTEX_SHADER = "\n#define M_PI 3.1415926535897932384626433832795\n\nuniform vec3 uLightAColor;\nuniform vec3 uLightAPosition;\nuniform float uLightAIntensity;\nuniform vec3 uLightBColor;\nuniform vec3 uLightBPosition;\nuniform float uLightBIntensity;\n\nuniform vec2 uSubdivision;\n\nuniform vec3 uOffset;\n\nuniform float uDistortionFrequency;\nuniform float uDistortionStrength;\nuniform float uDisplacementFrequency;\nuniform float uDisplacementStrength;\n\nuniform float uFresnelOffset;\nuniform float uFresnelMultiplier;\nuniform float uFresnelPower;\n\nuniform vec3  uRimColor;\nuniform float uRimThreshold;\nuniform float uRimPower;\n\nuniform float uTime;\n\nvarying vec3 vColor;\n\n\nvec4 permute(vec4 x){return mod(((x*34.0)+1.0)*x, 289.0);}\nvec4 taylorInvSqrt(vec4 r){return 1.79284291400159 - 0.85373472095314 * r;}\nvec4 fade(vec4 t) {return t*t*t*(t*(t*6.0-15.0)+10.0);}\n\nfloat perlin4d(vec4 P){\n  vec4 Pi0 = floor(P);\n  vec4 Pi1 = Pi0 + 1.0;\n  Pi0 = mod(Pi0, 289.0);\n  Pi1 = mod(Pi1, 289.0);\n  vec4 Pf0 = fract(P);\n  vec4 Pf1 = Pf0 - 1.0;\n  vec4 ix = vec4(Pi0.x, Pi1.x, Pi0.x, Pi1.x);\n  vec4 iy = vec4(Pi0.yy, Pi1.yy);\n  vec4 iz0 = vec4(Pi0.zzzz);\n  vec4 iz1 = vec4(Pi1.zzzz);\n  vec4 iw0 = vec4(Pi0.wwww);\n  vec4 iw1 = vec4(Pi1.wwww);\n\n  vec4 ixy = permute(permute(ix) + iy);\n  vec4 ixy0 = permute(ixy + iz0);\n  vec4 ixy1 = permute(ixy + iz1);\n  vec4 ixy00 = permute(ixy0 + iw0);\n  vec4 ixy01 = permute(ixy0 + iw1);\n  vec4 ixy10 = permute(ixy1 + iw0);\n  vec4 ixy11 = permute(ixy1 + iw1);\n\n  vec4 gx00 = ixy00 / 7.0;\n  vec4 gy00 = floor(gx00) / 7.0;\n  vec4 gz00 = floor(gy00) / 6.0;\n  gx00 = fract(gx00) - 0.5;\n  gy00 = fract(gy00) - 0.5;\n  gz00 = fract(gz00) - 0.5;\n  vec4 gw00 = vec4(0.75) - abs(gx00) - abs(gy00) - abs(gz00);\n  vec4 sw00 = step(gw00, vec4(0.0));\n  gx00 -= sw00 * (step(0.0, gx00) - 0.5);\n  gy00 -= sw00 * (step(0.0, gy00) - 0.5);\n\n  vec4 gx01 = ixy01 / 7.0;\n  vec4 gy01 = floor(gx01) / 7.0;\n  vec4 gz01 = floor(gy01) / 6.0;\n  gx01 = fract(gx01) - 0.5;\n  gy01 = fract(gy01) - 0.5;\n  gz01 = fract(gz01) - 0.5;\n  vec4 gw01 = vec4(0.75) - abs(gx01) - abs(gy01) - abs(gz01);\n  vec4 sw01 = step(gw01, vec4(0.0));\n  gx01 -= sw01 * (step(0.0, gx01) - 0.5);\n  gy01 -= sw01 * (step(0.0, gy01) - 0.5);\n\n  vec4 gx10 = ixy10 / 7.0;\n  vec4 gy10 = floor(gx10) / 7.0;\n  vec4 gz10 = floor(gy10) / 6.0;\n  gx10 = fract(gx10) - 0.5;\n  gy10 = fract(gy10) - 0.5;\n  gz10 = fract(gz10) - 0.5;\n  vec4 gw10 = vec4(0.75) - abs(gx10) - abs(gy10) - abs(gz10);\n  vec4 sw10 = step(gw10, vec4(0.0));\n  gx10 -= sw10 * (step(0.0, gx10) - 0.5);\n  gy10 -= sw10 * (step(0.0, gy10) - 0.5);\n\n  vec4 gx11 = ixy11 / 7.0;\n  vec4 gy11 = floor(gx11) / 7.0;\n  vec4 gz11 = floor(gy11) / 6.0;\n  gx11 = fract(gx11) - 0.5;\n  gy11 = fract(gy11) - 0.5;\n  gz11 = fract(gz11) - 0.5;\n  vec4 gw11 = vec4(0.75) - abs(gx11) - abs(gy11) - abs(gz11);\n  vec4 sw11 = step(gw11, vec4(0.0));\n  gx11 -= sw11 * (step(0.0, gx11) - 0.5);\n  gy11 -= sw11 * (step(0.0, gy11) - 0.5);\n\n  vec4 g0000 = vec4(gx00.x,gy00.x,gz00.x,gw00.x);\n  vec4 g1000 = vec4(gx00.y,gy00.y,gz00.y,gw00.y);\n  vec4 g0100 = vec4(gx00.z,gy00.z,gz00.z,gw00.z);\n  vec4 g1100 = vec4(gx00.w,gy00.w,gz00.w,gw00.w);\n  vec4 g0010 = vec4(gx10.x,gy10.x,gz10.x,gw10.x);\n  vec4 g1010 = vec4(gx10.y,gy10.y,gz10.y,gw10.y);\n  vec4 g0110 = vec4(gx10.z,gy10.z,gz10.z,gw10.z);\n  vec4 g1110 = vec4(gx10.w,gy10.w,gz10.w,gw10.w);\n  vec4 g0001 = vec4(gx01.x,gy01.x,gz01.x,gw01.x);\n  vec4 g1001 = vec4(gx01.y,gy01.y,gz01.y,gw01.y);\n  vec4 g0101 = vec4(gx01.z,gy01.z,gz01.z,gw01.z);\n  vec4 g1101 = vec4(gx01.w,gy01.w,gz01.w,gw01.w);\n  vec4 g0011 = vec4(gx11.x,gy11.x,gz11.x,gw11.x);\n  vec4 g1011 = vec4(gx11.y,gy11.y,gz11.y,gw11.y);\n  vec4 g0111 = vec4(gx11.z,gy11.z,gz11.z,gw11.z);\n  vec4 g1111 = vec4(gx11.w,gy11.w,gz11.w,gw11.w);\n\n  vec4 norm00 = taylorInvSqrt(vec4(dot(g0000, g0000), dot(g0100, g0100), dot(g1000, g1000), dot(g1100, g1100)));\n  g0000 *= norm00.x; g0100 *= norm00.y; g1000 *= norm00.z; g1100 *= norm00.w;\n\n  vec4 norm01 = taylorInvSqrt(vec4(dot(g0001, g0001), dot(g0101, g0101), dot(g1001, g1001), dot(g1101, g1101)));\n  g0001 *= norm01.x; g0101 *= norm01.y; g1001 *= norm01.z; g1101 *= norm01.w;\n\n  vec4 norm10 = taylorInvSqrt(vec4(dot(g0010, g0010), dot(g0110, g0110), dot(g1010, g1010), dot(g1110, g1110)));\n  g0010 *= norm10.x; g0110 *= norm10.y; g1010 *= norm10.z; g1110 *= norm10.w;\n\n  vec4 norm11 = taylorInvSqrt(vec4(dot(g0011, g0011), dot(g0111, g0111), dot(g1011, g1011), dot(g1111, g1111)));\n  g0011 *= norm11.x; g0111 *= norm11.y; g1011 *= norm11.z; g1111 *= norm11.w;\n\n  float n0000 = dot(g0000, Pf0);\n  float n1000 = dot(g1000, vec4(Pf1.x, Pf0.yzw));\n  float n0100 = dot(g0100, vec4(Pf0.x, Pf1.y, Pf0.zw));\n  float n1100 = dot(g1100, vec4(Pf1.xy, Pf0.zw));\n  float n0010 = dot(g0010, vec4(Pf0.xy, Pf1.z, Pf0.w));\n  float n1010 = dot(g1010, vec4(Pf1.x, Pf0.y, Pf1.z, Pf0.w));\n  float n0110 = dot(g0110, vec4(Pf0.x, Pf1.yz, Pf0.w));\n  float n1110 = dot(g1110, vec4(Pf1.xyz, Pf0.w));\n  float n0001 = dot(g0001, vec4(Pf0.xyz, Pf1.w));\n  float n1001 = dot(g1001, vec4(Pf1.x, Pf0.yz, Pf1.w));\n  float n0101 = dot(g0101, vec4(Pf0.x, Pf1.y, Pf0.z, Pf1.w));\n  float n1101 = dot(g1101, vec4(Pf1.xy, Pf0.z, Pf1.w));\n  float n0011 = dot(g0011, vec4(Pf0.xy, Pf1.zw));\n  float n1011 = dot(g1011, vec4(Pf1.x, Pf0.y, Pf1.zw));\n  float n0111 = dot(g0111, vec4(Pf0.x, Pf1.yzw));\n  float n1111 = dot(g1111, Pf1);\n\n  vec4 fade_xyzw = fade(Pf0);\n  vec4 n_0w = mix(vec4(n0000, n1000, n0100, n1100), vec4(n0001, n1001, n0101, n1101), fade_xyzw.w);\n  vec4 n_1w = mix(vec4(n0010, n1010, n0110, n1110), vec4(n0011, n1011, n0111, n1111), fade_xyzw.w);\n  vec4 n_zw = mix(n_0w, n_1w, fade_xyzw.z);\n  vec2 n_yzw = mix(n_zw.xy, n_zw.zw, fade_xyzw.y);\n  float n_xyzw = mix(n_yzw.x, n_yzw.y, fade_xyzw.x);\n  return 2.2 * n_xyzw;\n}\n\n\nvec3 getDisplacedPosition(vec3 _position)\n{\n  vec3 distoredPosition = _position;\n  distoredPosition += perlin4d(vec4(distoredPosition * uDistortionFrequency + uOffset, uTime)) * uDistortionStrength;\n\n  float perlinStrength = perlin4d(vec4(distoredPosition * uDisplacementFrequency + uOffset, uTime));\n\n  vec3 displacedPosition = _position;\n  displacedPosition += normalize(_position) * perlinStrength * uDisplacementStrength;\n\n  return displacedPosition;\n}\n\nvoid main()\n{\n  vec3 displacedPosition = getDisplacedPosition(position);\n  vec4 viewPosition = viewMatrix * vec4(displacedPosition, 1.0);\n  gl_Position = projectionMatrix * viewPosition;\n\n  float distanceA = (M_PI * 2.0) / uSubdivision.x;\n  float distanceB = M_PI / uSubdivision.x;\n\n  vec3 biTangent = cross(normal, tangent.xyz);\n\n  vec3 positionA = position + tangent.xyz * distanceA;\n  vec3 displacedPositionA = getDisplacedPosition(positionA);\n\n  vec3 positionB = position + biTangent.xyz * distanceB;\n  vec3 displacedPositionB = getDisplacedPosition(positionB);\n\n  vec3 computedNormal = cross(displacedPositionA - displacedPosition.xyz, displacedPositionB - displacedPosition.xyz);\n  computedNormal = normalize(computedNormal);\n\n  vec3 viewDirection = normalize(displacedPosition.xyz - cameraPosition);\n  float fresnel = uFresnelOffset + (1.0 + dot(viewDirection, computedNormal)) * uFresnelMultiplier;\n  fresnel = pow(max(0.0, fresnel), uFresnelPower);\n\n  float lightAIntensity = max(0.0, - dot(computedNormal.xyz, normalize(- uLightAPosition))) * uLightAIntensity;\n  float lightBIntensity = max(0.0, - dot(computedNormal.xyz, normalize(- uLightBPosition))) * uLightBIntensity;\n\n  // Clamp mix factors to [0, 1] so a high lightIntensity*fresnel (common on\n  // displacement peaks and loud audio) cannot extrapolate past the orange\n  // light color and saturate R, producing yellow-white hotspots.\n  vec3 color = vec3(0.0);\n  color = mix(color, uLightAColor, clamp(lightAIntensity * fresnel, 0.0, 1.0));\n  color = mix(color, uLightBColor, clamp(lightBIntensity * fresnel, 0.0, 1.0));\n  color = mix(color, uRimColor, clamp(pow(max(0.0, fresnel - uRimThreshold), uRimPower), 0.0, 1.0));\n\n  vColor = color;\n}\n";
+declare const ORGANIC_SPHERE_FRAGMENT_SHADER = "\nvarying vec3 vColor;\n\nvoid main()\n{\n  gl_FragColor = vec4(vColor, 1.0);\n}\n";
+
+/**
+ * GLSL shaders for the `OrganicParticles` audio-reactive visualization —
+ * a sibling of `OrganicSphere` that replaces the solid mesh with a
+ * spherical cloud of point-sprite particles whose radial displacement,
+ * swirl, size, and color gradient are driven by the same four frequency
+ * bands.
+ *
+ * The Perlin 4D noise is shared with the sphere shader via the re-usable
+ * `PERLIN_4D` partial so we only vendor Stefan Gustavson's implementation
+ * once.
+ */
+/**
+ * Vertex shader. Reads a static `aBasePosition` (on a deterministic
+ * seeded sphere) plus a per-particle `aSeed` (0–1) for subtle variation,
+ * then:
+ *   1. Displaces each particle radially by Perlin noise + audio volume.
+ *   2. Twists the cloud around the Y axis by an amount driven by audio
+ *      high-band (`uSwirl`).
+ *   3. Writes `vHeat` in [0, 1] for the fragment to mix between the two
+ *      tint colors.
+ *   4. Sizes the point sprite by distance (perspective) + audio medium.
+ */
+declare const ORGANIC_PARTICLES_VERTEX_SHADER = "\n\nvec4 permute(vec4 x){return mod(((x*34.0)+1.0)*x, 289.0);}\nvec4 taylorInvSqrt(vec4 r){return 1.79284291400159 - 0.85373472095314 * r;}\nvec4 fade(vec4 t) {return t*t*t*(t*(t*6.0-15.0)+10.0);}\n\nfloat perlin4d(vec4 P){\n  vec4 Pi0 = floor(P);\n  vec4 Pi1 = Pi0 + 1.0;\n  Pi0 = mod(Pi0, 289.0);\n  Pi1 = mod(Pi1, 289.0);\n  vec4 Pf0 = fract(P);\n  vec4 Pf1 = Pf0 - 1.0;\n  vec4 ix = vec4(Pi0.x, Pi1.x, Pi0.x, Pi1.x);\n  vec4 iy = vec4(Pi0.yy, Pi1.yy);\n  vec4 iz0 = vec4(Pi0.zzzz);\n  vec4 iz1 = vec4(Pi1.zzzz);\n  vec4 iw0 = vec4(Pi0.wwww);\n  vec4 iw1 = vec4(Pi1.wwww);\n\n  vec4 ixy = permute(permute(ix) + iy);\n  vec4 ixy0 = permute(ixy + iz0);\n  vec4 ixy1 = permute(ixy + iz1);\n  vec4 ixy00 = permute(ixy0 + iw0);\n  vec4 ixy01 = permute(ixy0 + iw1);\n  vec4 ixy10 = permute(ixy1 + iw0);\n  vec4 ixy11 = permute(ixy1 + iw1);\n\n  vec4 gx00 = ixy00 / 7.0;\n  vec4 gy00 = floor(gx00) / 7.0;\n  vec4 gz00 = floor(gy00) / 6.0;\n  gx00 = fract(gx00) - 0.5;\n  gy00 = fract(gy00) - 0.5;\n  gz00 = fract(gz00) - 0.5;\n  vec4 gw00 = vec4(0.75) - abs(gx00) - abs(gy00) - abs(gz00);\n  vec4 sw00 = step(gw00, vec4(0.0));\n  gx00 -= sw00 * (step(0.0, gx00) - 0.5);\n  gy00 -= sw00 * (step(0.0, gy00) - 0.5);\n\n  vec4 gx01 = ixy01 / 7.0;\n  vec4 gy01 = floor(gx01) / 7.0;\n  vec4 gz01 = floor(gy01) / 6.0;\n  gx01 = fract(gx01) - 0.5;\n  gy01 = fract(gy01) - 0.5;\n  gz01 = fract(gz01) - 0.5;\n  vec4 gw01 = vec4(0.75) - abs(gx01) - abs(gy01) - abs(gz01);\n  vec4 sw01 = step(gw01, vec4(0.0));\n  gx01 -= sw01 * (step(0.0, gx01) - 0.5);\n  gy01 -= sw01 * (step(0.0, gy01) - 0.5);\n\n  vec4 gx10 = ixy10 / 7.0;\n  vec4 gy10 = floor(gx10) / 7.0;\n  vec4 gz10 = floor(gy10) / 6.0;\n  gx10 = fract(gx10) - 0.5;\n  gy10 = fract(gy10) - 0.5;\n  gz10 = fract(gz10) - 0.5;\n  vec4 gw10 = vec4(0.75) - abs(gx10) - abs(gy10) - abs(gz10);\n  vec4 sw10 = step(gw10, vec4(0.0));\n  gx10 -= sw10 * (step(0.0, gx10) - 0.5);\n  gy10 -= sw10 * (step(0.0, gy10) - 0.5);\n\n  vec4 gx11 = ixy11 / 7.0;\n  vec4 gy11 = floor(gx11) / 7.0;\n  vec4 gz11 = floor(gy11) / 6.0;\n  gx11 = fract(gx11) - 0.5;\n  gy11 = fract(gy11) - 0.5;\n  gz11 = fract(gz11) - 0.5;\n  vec4 gw11 = vec4(0.75) - abs(gx11) - abs(gy11) - abs(gz11);\n  vec4 sw11 = step(gw11, vec4(0.0));\n  gx11 -= sw11 * (step(0.0, gx11) - 0.5);\n  gy11 -= sw11 * (step(0.0, gy11) - 0.5);\n\n  vec4 g0000 = vec4(gx00.x,gy00.x,gz00.x,gw00.x);\n  vec4 g1000 = vec4(gx00.y,gy00.y,gz00.y,gw00.y);\n  vec4 g0100 = vec4(gx00.z,gy00.z,gz00.z,gw00.z);\n  vec4 g1100 = vec4(gx00.w,gy00.w,gz00.w,gw00.w);\n  vec4 g0010 = vec4(gx10.x,gy10.x,gz10.x,gw10.x);\n  vec4 g1010 = vec4(gx10.y,gy10.y,gz10.y,gw10.y);\n  vec4 g0110 = vec4(gx10.z,gy10.z,gz10.z,gw10.z);\n  vec4 g1110 = vec4(gx10.w,gy10.w,gz10.w,gw10.w);\n  vec4 g0001 = vec4(gx01.x,gy01.x,gz01.x,gw01.x);\n  vec4 g1001 = vec4(gx01.y,gy01.y,gz01.y,gw01.y);\n  vec4 g0101 = vec4(gx01.z,gy01.z,gz01.z,gw01.z);\n  vec4 g1101 = vec4(gx01.w,gy01.w,gz01.w,gw01.w);\n  vec4 g0011 = vec4(gx11.x,gy11.x,gz11.x,gw11.x);\n  vec4 g1011 = vec4(gx11.y,gy11.y,gz11.y,gw11.y);\n  vec4 g0111 = vec4(gx11.z,gy11.z,gz11.z,gw11.z);\n  vec4 g1111 = vec4(gx11.w,gy11.w,gz11.w,gw11.w);\n\n  vec4 norm00 = taylorInvSqrt(vec4(dot(g0000, g0000), dot(g0100, g0100), dot(g1000, g1000), dot(g1100, g1100)));\n  g0000 *= norm00.x; g0100 *= norm00.y; g1000 *= norm00.z; g1100 *= norm00.w;\n\n  vec4 norm01 = taylorInvSqrt(vec4(dot(g0001, g0001), dot(g0101, g0101), dot(g1001, g1001), dot(g1101, g1101)));\n  g0001 *= norm01.x; g0101 *= norm01.y; g1001 *= norm01.z; g1101 *= norm01.w;\n\n  vec4 norm10 = taylorInvSqrt(vec4(dot(g0010, g0010), dot(g0110, g0110), dot(g1010, g1010), dot(g1110, g1110)));\n  g0010 *= norm10.x; g0110 *= norm10.y; g1010 *= norm10.z; g1110 *= norm10.w;\n\n  vec4 norm11 = taylorInvSqrt(vec4(dot(g0011, g0011), dot(g0111, g0111), dot(g1011, g1011), dot(g1111, g1111)));\n  g0011 *= norm11.x; g0111 *= norm11.y; g1011 *= norm11.z; g1111 *= norm11.w;\n\n  float n0000 = dot(g0000, Pf0);\n  float n1000 = dot(g1000, vec4(Pf1.x, Pf0.yzw));\n  float n0100 = dot(g0100, vec4(Pf0.x, Pf1.y, Pf0.zw));\n  float n1100 = dot(g1100, vec4(Pf1.xy, Pf0.zw));\n  float n0010 = dot(g0010, vec4(Pf0.xy, Pf1.z, Pf0.w));\n  float n1010 = dot(g1010, vec4(Pf1.x, Pf0.y, Pf1.z, Pf0.w));\n  float n0110 = dot(g0110, vec4(Pf0.x, Pf1.yz, Pf0.w));\n  float n1110 = dot(g1110, vec4(Pf1.xyz, Pf0.w));\n  float n0001 = dot(g0001, vec4(Pf0.xyz, Pf1.w));\n  float n1001 = dot(g1001, vec4(Pf1.x, Pf0.yz, Pf1.w));\n  float n0101 = dot(g0101, vec4(Pf0.x, Pf1.y, Pf0.z, Pf1.w));\n  float n1101 = dot(g1101, vec4(Pf1.xy, Pf0.z, Pf1.w));\n  float n0011 = dot(g0011, vec4(Pf0.xy, Pf1.zw));\n  float n1011 = dot(g1011, vec4(Pf1.x, Pf0.y, Pf1.zw));\n  float n0111 = dot(g0111, vec4(Pf0.x, Pf1.yzw));\n  float n1111 = dot(g1111, Pf1);\n\n  vec4 fade_xyzw = fade(Pf0);\n  vec4 n_0w = mix(vec4(n0000, n1000, n0100, n1100), vec4(n0001, n1001, n0101, n1101), fade_xyzw.w);\n  vec4 n_1w = mix(vec4(n0010, n1010, n0110, n1110), vec4(n0011, n1011, n0111, n1111), fade_xyzw.w);\n  vec4 n_zw = mix(n_0w, n_1w, fade_xyzw.z);\n  vec2 n_yzw = mix(n_zw.xy, n_zw.zw, fade_xyzw.y);\n  float n_xyzw = mix(n_yzw.x, n_yzw.y, fade_xyzw.x);\n  return 2.2 * n_xyzw;\n}\n\n\nattribute vec3 aBasePosition;\nattribute float aSeed;\n\nuniform float uTime;\nuniform float uNoiseFrequency;\nuniform float uNoiseStrength;\nuniform float uDisplacement;\nuniform float uSwirl;\nuniform float uSwirlTimeRate;\nuniform float uSizeBase;\nuniform float uSizeAudio;\nuniform float uPixelRatio;\n\nvarying float vHeat;\nvarying float vSeed;\n\nvoid main() {\n  vec3 pos = aBasePosition;\n\n  // 4D Perlin sampled in particle space. The 4th axis is time so the\n  // cloud evolves over time without tiling.\n  float n = perlin4d(vec4(pos * uNoiseFrequency, uTime));\n\n  // Per-particle phase so the cloud doesn't breathe in lockstep.\n  float phaseShift = (aSeed - 0.5) * 0.5;\n  float breath = sin(uTime * 0.0008 + aSeed * 6.2831) * 0.5 + 0.5;\n\n  // Outward push: noise + audio-driven displacement, scaled by seed so\n  // some particles dart further than others on the same beat.\n  vec3 radial = normalize(pos);\n  float push = n * uNoiseStrength + uDisplacement * (0.6 + aSeed * 0.8) + breath * 0.05;\n  pos += radial * push;\n\n  // Twist around Y. Amount scales with height so the cloud spirals\n  // rather than rigid-rotating. uSwirlTimeRate is 0 by default so the\n  // swirl is driven by audio (uSwirl) alone; crank it for a constant\n  // drift.\n  float swirlAngle = pos.y * uSwirl + uTime * uSwirlTimeRate + phaseShift;\n  float c = cos(swirlAngle);\n  float s = sin(swirlAngle);\n  pos.xz = mat2(c, -s, s, c) * pos.xz;\n\n  vec4 mvPos = modelViewMatrix * vec4(pos, 1.0);\n  gl_Position = projectionMatrix * mvPos;\n\n  // Point size: base + audio boost, gently perspective-attenuated. At\n  // the default camera (z ~= 3.84) a uSizeBase of 1 renders roughly one\n  // device pixel \u2014 intentionally tiny so 40k+ additively-blended points\n  // read as fine dust rather than a solid blob.\n  float size = uSizeBase + uSizeAudio * (0.5 + aSeed);\n  gl_PointSize = max(1.0, size * uPixelRatio * (2.0 / max(0.1, -mvPos.z)));\n\n  // Heat: 0 at core, 1 at fringe. Used by the fragment to lerp color.\n  vHeat = clamp((length(pos) - 0.4) / 1.4, 0.0, 1.0);\n  vSeed = aSeed;\n}\n";
+/**
+ * Fragment shader. Draws each particle as a soft disc that mixes between
+ * the cool and hot tint based on `vHeat`, with per-particle noise-free
+ * alpha shaping for a plasma-dust feel. Paired with additive blending
+ * and no depth-write for a glowing cloud that doesn't self-occlude.
+ */
+declare const ORGANIC_PARTICLES_FRAGMENT_SHADER = "\nprecision mediump float;\n\nuniform vec3 uColorCool;\nuniform vec3 uColorHot;\nuniform float uOpacity;\nuniform float uSoftness;\n\nvarying float vHeat;\nvarying float vSeed;\n\nvoid main() {\n  vec2 centered = gl_PointCoord - vec2(0.5);\n  float distSq = dot(centered, centered);\n  if (distSq > 0.25) discard;\n\n  // Soft circular falloff. uSoftness in [0.5, 1] controls how hard the\n  // edge is: 0.5 = sharp disc, 1 = feathered blob.\n  float innerR = 0.25 * (1.0 - uSoftness);\n  float alpha = smoothstep(0.25, innerR, distSq);\n\n  // Warm/cool gradient, with a tiny seed-based tint wobble so the cloud\n  // doesn't look banded.\n  float wobble = (vSeed - 0.5) * 0.15;\n  vec3 color = mix(uColorCool, uColorHot, clamp(vHeat + wobble, 0.0, 1.0));\n\n  gl_FragColor = vec4(color, alpha * uOpacity);\n}\n";
+
+export { type BaseVoiceConversationOptions as B, type ChatClientToolFn as C, DEFAULT_ORGANIC_PARTICLES_CONFIG as D, type OrganicSphereConfig as O, PERLIN_4D as P, type BaseVoiceConversationResult as a, type BaseChatConversationOptions as b, type BaseChatConversationResult as c, type OrganicParticlesConfig as d, type BandReactivity as e, type ChatConversationStatus as f, type ChatToolDescriptor as g, DEFAULT_ORGANIC_SPHERE_CONFIG as h, ORGANIC_PARTICLES_FRAGMENT_SHADER as i, ORGANIC_PARTICLES_VERTEX_SHADER as j, ORGANIC_SPHERE_FRAGMENT_SHADER as k, ORGANIC_SPHERE_VERTEX_SHADER as l, resolveOrganicSphereConfig as m, resolveOrganicParticlesConfig as r };