@horon-ai/react 0.1.0 → 0.1.2

package/src/components/document-extract-panel.tsx

@@ -4,52 +4,97 @@ import { type ComponentProps, type ReactNode, useMemo, useState } from "react";
 import { cn } from "../lib/cn";
 import { PanelPillTabs } from "./bot-instructions-panel";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+/** Strips a section's own `className` so the panel can merge its classes with the caller's. */
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes merged last onto the element. */
+  className?: string;
+};
 
+/** Row state of a plain field: `filled` reads fine, `check` marks a value the extractor is unsure about. */
 export type ExtractFieldStatus = "filled" | "check";
 
+/** One extracted scalar value: one row in the Fields view and one entry in the JSON view. */
 export type ExtractField = {
+  /** Stable identity; confirming a row records this id and drives the footer counters. */
   id: string;
+  /** Row label on the left, 100px wide; also the key in the JSON view. */
   label: string;
+  /** The read value, shown truncated in a button-sized pill. */
   value: string;
   /** Field type shown at the row end, for example `Text` or `Date`. */
   type?: string;
+  /** `check` marks the value for confirmation: the row takes the danger border and a "Check" caption. */
   status?: ExtractFieldStatus;
 };
 
+/** One extracted table: a labelled block with a header row and body rows instead of a single value. */
 export type ExtractTable = {
+  /** Stable identity, counted like a field in the footer. */
   id: string;
+  /** Row label above the table. */
   label: string;
+  /** Field type shown at the row end, such as `Table`. */
   type?: string;
-  columns: { label: string; align?: "start" | "end"; width?: number }[];
+  /** Column definitions, in order; a cell reads its column by index. */
+  columns: {
+    /** Column heading, `caption` secondary text. */
+    label: string;
+    /** Cell alignment; `end` right-aligns numbers. */
+    align?: "start" | "end";
+    /** Fixed column width in px; a column without it shares the free width. */
+    width?: number;
+  }[];
+  /** Body rows; each inner array is one row, matched to `columns` by index. */
   rows: string[][];
 };
 
+/** A labelled section of the Fields view, grouped under a dot and a heading. */
 export type ExtractGroup = {
+  /** Stable identity for the React key. */
   id: string;
+  /** Section heading, `label-md` primary text. */
   label: string;
+  /** Fields and tables of this section, in display order. */
   fields: (ExtractField | ExtractTable)[];
 };
 
+/** Props for {@link DocumentExtractPanel}: the sheet to view, the extracted groups and the footer actions. */
 export type DocumentExtractPanelProps = WithClass<Omit<ComponentProps<"section">, "title">> & {
+  /** Document name in the viewer toolbar; `label-md` primary text, truncated. */
   fileName: string;
+  /** Page indicator at the right of the toolbar. @default "1 / 1" */
   pageLabel?: string;
   /** The paper sheet content. Wrap fields in `ExtractHighlight` to outline what was read. */
   sheet: ReactNode;
+  /** Extracted sections, in display order; the same data feeds the Fields, JSON and Schema views. */
   groups: ExtractGroup[];
+  /** Starting zoom the toolbar shows; 70 draws the sheet at its design size (scale 1) and the range is 30–150. @default 70 */
   defaultZoom?: number;
-  bot?: { initial: string; name: string; elapsed?: string };
+  /** Bot credited in the footer; without it the footer shows no attribution. */
+  bot?: {
+    /** One-letter mark on the 20px brand square. */
+    initial: string;
+    /** Bot name, `caption` secondary text. */
+    name: string;
+    /** Optional run time appended as "· 12s". */
+    elapsed?: string;
+  };
+  /** Fires when the Extract button is pressed; the panel also bumps its run counter, which remounts the active view and replays its entry animation. */
   onExtract?: () => void;
+  /** Fires after Accept all has queued the confirmation of every row, so the confirmed marks land on the next render. */
   onAcceptAll?: () => void;
   /** Makes the file name actionable; without it the name is a plain label. */
   onOpenFile?: () => void;
 };
 
+/** Lowest and highest zoom the toolbar allows, and the step of one press. */
 const ZOOM_MIN = 30;
 const ZOOM_MAX = 150;
 const ZOOM_STEP = 10;
+/** The fit zoom: 100% of the sheet box is drawn at this percent, so the default 70 shows it at its design size. */
 const ZOOM_FIT = 70;
 
+/** Outline colours for `ExtractHighlight`: brand-family tints for reads, neutral and ink for notes and marks. */
 const highlightTone = {
   sky: "border-accent-sky-500-90 bg-accent-sky-500-12",
   brand: "border-accent-sky-700-90 bg-accent-sky-700-12",
@@ -62,7 +107,10 @@ export function ExtractHighlight({
   tone = "sky",
   className,
   ...props
-}: WithClass<ComponentProps<"div">> & { tone?: keyof typeof highlightTone }) {
+}: WithClass<ComponentProps<"div">> & {
+  /** Outline and fill pair: `sky` for a normal read, `brand` for a highlighted one, `neutral` and `ink` for notes. @default "sky" */
+  tone?: keyof typeof highlightTone;
+}) {
   return (
     <div
       className={cn("flex flex-col gap-px rounded-sm border-[1.2px] px-1 py-0.5", highlightTone[tone], className)}
@@ -79,7 +127,12 @@ function isChecked(field: ExtractField, resolved: Set<string>) {
   return field.status === "check" && !resolved.has(field.id);
 }
 
-function Divider({ vertical }: { vertical?: boolean }) {
+/** One hairline between the panel's regions; `vertical` draws it as a column rule for the split layout. */
+// prettier-ignore
+function Divider({ vertical }: {
+  /** Draws a column rule instead of a row rule. */
+  vertical?: boolean;
+}) {
   return (
     <div
       role="separator"
@@ -95,6 +148,31 @@ function stepClass() {
 /**
  * Document extract panel (Paper `YUT-1` / `GWP-0`): a viewer with zoom controls on the left and the extracted
  * fields on the right, with Fields / JSON / Schema views, a per-row confirmation check and an Accept all footer.
+ *
+ * Laid out with container queries, not the viewport: the two columns stack below the 4xl container width and
+ * split above it, with the viewer column fixed at 540px. Zoom runs 30–150 in steps of 10, "Fit" returns to 70
+ * (the sheet's design size), and the sheet is scaled from its top edge, so it never reflows. A field with
+ * `status: "check"` renders as a button that confirms that one row; Accept all confirms every row at once.
+ * The footer counts filled and unresolved rows, keeps a dot per field and credits the bot when `bot` is set.
+ *
+ * @example
+ * ```tsx
+ * <DocumentExtractPanel
+ *   fileName="invoice-0424.pdf"
+ *   groups={[
+ *     {
+ *       id: "vendor",
+ *       label: "Vendor",
+ *       fields: [
+ *         { id: "name", label: "Name", value: "Northwind Supply", type: "Text" },
+ *         { id: "due", label: "Due", value: "Oct 24, 2026", type: "Date", status: "check" },
+ *       ],
+ *     },
+ *   ]}
+ *   sheet={<h1 className="text-title-md">Northwind Supply</h1>}
+ *   onAcceptAll={() => saveExtraction()}
+ * />
+ * ```
  */
 export function DocumentExtractPanel({
   fileName,

package/src/components/empty-state.tsx

@@ -2,17 +2,36 @@ import type { ReactNode } from "react";
 
 import { cn } from "../lib/cn";
 
+/** Props for {@link EmptyState}: an optional illustration, the copy and one action. */
 export type EmptyStateProps = {
-  /** 140px illustration, such as a mascot pose. */
+  /** 140px illustration, such as a mascot pose. The slot is square and the child is stretched to fill it. */
   illustration?: ReactNode;
+  /** Heading, rendered as a `title-md` balanced paragraph. */
   title: ReactNode;
+  /** Supporting copy under the heading, `body-md` secondary text across the full column width. */
   description?: ReactNode;
   /** Action under the text, usually a `Button`. */
   action?: ReactNode;
+  /** Extra classes on the column, merged after the width, spacing and entry animation. */
   className?: string;
 };
 
-/** Figma `Empty state` (64:485): centered 140px mascot, title-md heading, body-md text, action. */
+/**
+ * Figma `Empty state` (64:485): centered 140px mascot, title-md heading, body-md text, action.
+ *
+ * A 360px-max column with a rise-in animation and no border or fill, so it drops into a card, a panel body
+ * or an empty table area without drawing its own surface.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   illustration={<img src="/mascots/horon-mascot-welcome.webp" alt="" />}
+ *   title="Meet your first bot"
+ *   description="Give it a role and a task. It keeps working after you close the laptop."
+ *   action={<Button>Create a bot</Button>}
+ * />
+ * ```
+ */
 export function EmptyState({ illustration, title, description, action, className }: EmptyStateProps) {
   return (
     <div

package/src/components/field.tsx

@@ -4,8 +4,12 @@ import { createContext, useContext, type ComponentProps } from "react";
 import { cn } from "../lib/cn";
 import type { ControlSize } from "../lib/size";
 
-type WithClass<T> = Omit<T, "className"> & { className?: string };
+type WithClass<T> = Omit<T, "className"> & {
+  /** Extra classes appended after the part's own classes. */
+  className?: string;
+};
 
+/** `md` outside a `Field`, so a part rendered on its own keeps the default rung rather than throwing. */
 const FieldSizeContext = createContext<ControlSize>("md");
 
 const gapClass: Record<ControlSize, string> = {
@@ -26,12 +30,38 @@ const metaClass: Record<ControlSize, string> = {
   lg: "text-body-sm",
 };
 
-/** Figma `Field examples` (58:163): label, control and help text, 6/8/10px apart. */
+/**
+ * Figma `Field examples` (58:163): label, control and help text, 6/8/10px apart.
+ *
+ * Wraps Base UI's `Field.Root`, a vertical stack (`max-w-full`, left aligned) whose gaps and text
+ * rungs follow `size` through context, so `FieldLabel`, `FieldDescription` and `FieldError` match the
+ * control without repeating the size. `invalid` (or Base UI's own validation) marks the control inside
+ * the field invalid, and the control's box paints its danger border from that.
+ *
+ * @example
+ * ```tsx
+ * import { Field, FieldDescription, FieldError, FieldLabel, Input } from "@horon-ai/react";
+ *
+ * function EmailField() {
+ *   return (
+ *     <Field size="md">
+ *       <FieldLabel htmlFor="email">Email</FieldLabel>
+ *       <Input id="email" type="email" placeholder="you@example.com" />
+ *       <FieldDescription>We only use it to sign you in.</FieldDescription>
+ *       <FieldError>Enter a valid address.</FieldError>
+ *     </Field>
+ *   );
+ * }
+ * ```
+ */
 export function Field({
   size = "md",
   className,
   ...props
-}: WithClass<Omit<ComponentProps<typeof BaseField.Root>, "size">> & { size?: ControlSize }) {
+}: WithClass<Omit<ComponentProps<typeof BaseField.Root>, "size">> & {
+  /** Control rung shared by every part; sets the gap (6/8/10px) and the label and meta type scales. @default "md" */
+  size?: ControlSize;
+}) {
   return (
     <FieldSizeContext.Provider value={size}>
       <BaseField.Root
@@ -42,6 +72,11 @@ export function Field({
   );
 }
 
+/**
+ * Part of {@link Field}. The control's label (`Field.Label`): `label-sm/md/lg` from the field's size,
+ * primary text, and the disabled colour when its control is disabled. Give it `htmlFor` matching the
+ * control's `id`, which is also what makes clicking the text focus the control.
+ */
 export function FieldLabel({ className, ...props }: WithClass<ComponentProps<typeof BaseField.Label>>) {
   const size = useContext(FieldSizeContext);
   return (
@@ -52,11 +87,22 @@ export function FieldLabel({ className, ...props }: WithClass<ComponentProps<typ
   );
 }
 
+/**
+ * Part of {@link Field}. The help line under the control (`Field.Description`) in secondary text:
+ * `caption` at sm and md, `body-sm` at lg. Always full width so the copy wraps inside the field, and
+ * Base UI wires it to the control as the description for assistive tech.
+ */
 export function FieldDescription({ className, ...props }: WithClass<ComponentProps<typeof BaseField.Description>>) {
   const size = useContext(FieldSizeContext);
   return <BaseField.Description className={cn(metaClass[size], "w-full text-text-secondary", className)} {...props} />;
 }
 
+/**
+ * Part of {@link Field}. The validation message (`Field.Error`) in `text-text-danger` at the field's
+ * meta rung. It stays mounted only while it should show: Base UI renders it when the enclosing field is
+ * invalid, or when `match` is set, and keeps it mounted through its exit — the row collapses from `1fr`
+ * to `0fr` as it fades, so the parts below glide up instead of jumping.
+ */
 export function FieldError({ className, children, ...props }: WithClass<ComponentProps<typeof BaseField.Error>>) {
   const size = useContext(FieldSizeContext);
   // Base UI keeps the message mounted through its exit (`data-ending-style`), so the row can close

package/src/components/file-drop.tsx

@@ -4,26 +4,61 @@ import { type ComponentProps, type DragEvent, type ReactNode, useId, useState }
 import { cn } from "../lib/cn";
 import { Spinner } from "./spinner";
 
+/**
+ * How the drop target is painted: `solid` fills it with the raised surface (`bg-bg-surface`), `glass`
+ * leaves it transparent on the veil so imagery behind shows through.
+ */
 export type FileDropSurface = "solid" | "glass";
 
+/** Props of {@link FileDrop}: the native file input attributes plus the target's own state. */
 export type FileDropProps = Omit<ComponentProps<"input">, "className" | "type" | "children" | "onDrop"> & {
-  /** Label next to the icon. */
+  /** Label next to the icon. @default "Drop files here or click to upload" */
   label?: ReactNode;
   /** Shows a spinner in place of the icon while files upload. */
   uploading?: boolean;
   /** Danger rim for a rejected file. */
   rejected?: boolean;
-  /** Called with the dropped files. */
+  /** Called with the dropped or picked files, in picker order; fires on both drop and native file input change. */
   onFiles?: (files: File[]) => void;
-  /** `solid` (default) fills the target with the raised surface; `glass` puts it on the veil over imagery. */
+  /** `solid` (default) fills the target with the raised surface; `glass` puts it on the veil over imagery. @default "solid" */
   surface?: FileDropSurface;
+  /** Extra classes for the label that forms the target. */
   className?: string;
 };
 
 /**
  * Paper `File drop` (1VWI-0): a 1.5px dashed r10 target, icon 16 and a 13/18 500 label centred with gap 8.
- * Dragging swaps the dashes for a 1px brand rim; no shake or bounce. Solid fills with the raised surface,
+ * Dragging keeps the dashed edge and repaints it in the brand border, adds a 1px inset brand rim and, on
+ * `solid`, shifts the fill to `bg-bg-subtle`; no shake or bounce. Solid fills with the raised surface,
  * glass sits on the veil (`veil-drop`) and keeps the dashed border as its only outline.
+ *
+ * The target is a `<label>` around a screen-reader-only `<input type="file">`, so a click opens the native
+ * picker and the control stays keyboard reachable; the focus ring is drawn on the label through
+ * `has-[:focus-visible]`. Drops land in `onFiles` with `DataTransfer.files`, and the input's change event
+ * also calls `onFiles` before forwarding `onChange`. While `uploading`, the icon becomes a spinner, the
+ * input is disabled and drops are ignored; `rejected` paints a danger rim. The target is capped at 550px
+ * and never wider than its parent.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { FileDrop } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [uploading, setUploading] = useState(false);
+ *   return (
+ *     <FileDrop
+ *       accept=".pdf,.png"
+ *       label="Drop contracts here or click to upload"
+ *       uploading={uploading}
+ *       onFiles={(files) => {
+ *         setUploading(true);
+ *         void upload(files).finally(() => setUploading(false));
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function FileDrop({
   label = "Drop files here or click to upload",

package/src/components/filter-bar.tsx

@@ -1,20 +1,29 @@
 import { type ComponentProps, type ReactNode, useRef, useState } from "react";
 
 import { cn } from "../lib/cn";
-import { useActiveIndicator } from "../lib/use-active-indicator";
+import { useActiveIndicator } from "../hooks/use-active-indicator";
 
+/** One option in a `FilterBar`. */
 export type FilterBarItem = {
+  /** Stable value reported through `onValueChange` and compared with `value`. */
   value: string;
+  /** Visible chip text; normally a short noun such as `All` or `Agents`. */
   label: ReactNode;
-  /** Count shown after the label, such as 4. */
+  /** Count shown after the label, such as 4. Omit to hide the slot. */
   count?: number;
+  /** Disables just this option: 40% opacity, not clickable. */
   disabled?: boolean;
 };
 
+/** Props of {@link FilterBar}: the options and the selection, controlled or uncontrolled. */
 export type FilterBarProps = Omit<ComponentProps<"div">, "onChange" | "defaultValue"> & {
+  /** Options in display order; the first one is the initial selection when `defaultValue` is omitted. */
   items: FilterBarItem[];
+  /** Controlled selection. Pass `onValueChange` to hear about clicks. */
   value?: string;
+  /** Initial selection when uncontrolled. @default items[0].value */
   defaultValue?: string;
+  /** Called with the clicked option's `value`; clicks on the already-selected option still fire. */
   onValueChange?: (value: string) => void;
 };
 
@@ -22,6 +31,34 @@ export type FilterBarProps = Omit<ComponentProps<"div">, "onChange" | "defaultVa
  * Paper `Filter bar` (Agents N2): a 5% ink pill track with 30px options; the selected option sits on a sliding 10% ink pill.
  * The pills never wrap, so a screen too narrow for all of them scrolls the track sideways instead of widening the page.
  * The track keeps its intrinsic width (and so stays centred by its parent) unless that width exceeds the box.
+ *
+ * Selection is controlled through `value` or uncontrolled from `defaultValue`, which falls back to the first
+ * item. The group is a `radiogroup` labelled by `aria-label` (`Filter` when omitted), each option a
+ * `<button role="radio" aria-checked>`; the background pill is measured by the active option and hides when
+ * none matches, and it lands without animating on the first paint. There is no roving tab index: every enabled
+ * option is a tab stop, and Space or Enter selects it.
+ *
+ * @example
+ * ```tsx
+ * import { useState } from "react";
+ * import { FilterBar } from "@horon-ai/react";
+ *
+ * function Example() {
+ *   const [scope, setScope] = useState("all");
+ *   return (
+ *     <FilterBar
+ *       aria-label="Scope"
+ *       value={scope}
+ *       onValueChange={setScope}
+ *       items={[
+ *         { value: "all", label: "All", count: 12 },
+ *         { value: "agents", label: "Agents", count: 4 },
+ *         { value: "archived", label: "Archived", disabled: true },
+ *       ]}
+ *     />
+ *   );
+ * }
+ * ```
  */
 export function FilterBar({
   items,

package/src/components/flue-background.tsx

@@ -1,45 +1,89 @@
-import { type CSSProperties, useEffect, useRef, useSyncExternalStore } from "react";
+import { type CSSProperties, useEffect, useRef } from "react";
 
+import { useColorScheme } from "../hooks/use-color-scheme";
 import { cn } from "../lib/cn";
 
+/**
+ * Every knob the fragment shader reads. Each key becomes a uniform named `u` plus the capitalised key
+ * (`speed` → `uSpeed`), and a hex string is uploaded as a `vec3`, so add a field here and a matching
+ * uniform in the shader or it silently does nothing. `cursor` and `maxDpr` are engine keys instead: they
+ * never become uniforms and are skipped when uniforms are bound.
+ */
 export type FlueConfig = {
+  /** Flat ground color, hex. Painted on the wrapper, so it is also the fallback when WebGL2 is unavailable. */
   bgColor: string;
+  /** Faintest ramp stop, a near-ground tint that only the thinnest smoke reaches. */
   colorA: string;
+  /** Second ramp stop: the first visible blue of the plume. */
   colorB: string;
+  /** Third ramp stop: the dense body of the plume. */
   colorC: string;
+  /** Densest ramp stop, also the glow color at high density. */
   colorD: string;
+  /** Zoom of the base noise field; larger values make the smoke finer and busier. */
   scale: number;
+  /** Time multiplier, so the drift speed follows it. Larger values scroll faster. */
   speed: number;
+  /** Vertical advection added to the curl field per second, the internal flow of the plume. */
   flow: number;
+  /** Gain of each fbm octave (0..1); lower values keep the coarse shape dominant. */
   roughness: number;
+  /** Frequency step between fbm octaves; larger values add detail at smaller and smaller scale. */
   lacunarity: number;
+  /** Zoom of the density field: larger values make individual wisps smaller. */
   smokeScale: number;
+  /** Amount of curl-noise displacement; higher values swirl the smoke more. */
   curl: number;
+  /** Zoom of the curl potential field, so the swirls themselves change size. */
   curlScale: number;
+  /** Upward drift of the smoke in uv per second. */
   rise: number;
+  /** Vertical frequency multiplier for the density field; larger values compress the wisps vertically. */
   slender: number;
+  /** Half-width (uv) of the vertical corridor the plume is allowed to fill. */
   width: number;
+  /** How much the corridor widens from the bottom to the top of the frame. */
   spread: number;
+  /** How far the pointer's x pushes the top of the plume sideways. */
   lean: number;
+  /** Overall density multiplier before the threshold. */
   density: number;
+  /** Gain around `midpoint`: higher values give a harder edge between ground and smoke. */
   contrast: number;
+  /** Threshold (0..1) where smoke starts to show; higher values leave more of the ground bare. */
   midpoint: number;
+  /** Strength of the `colorD` bloom on the densest part, added as `pow(f, 4)`. */
   glow: number;
+  /** Smoothstep width, over the density value, at which the ground gives way to the ramp; 0 floors at 0.01. */
   sink: number;
+  /** Film-grain strength; 0 turns grain off. */
   grain: number;
+  /** Grain refresh multiplier (24 steps per second at 1); 0 holds one static grain field. */
   grainAnim: number;
+  /** Triangle-dither amplitude added to every channel to stop gradient banding. */
   dither: number;
+  /** Corner darkening; multiplied by the squared uv distance from the centre. */
   vignette: number;
   /** 1 lets the smoke follow the real pointer; 0 (default) ignores it and a slow virtual pointer sways the smoke. */
   cursor: number;
+  /** Radius (uv) of the pointer trail's gaussian falloff. */
   pointerRadius: number;
+  /** How strongly the pointer's velocity drags the smoke along, through the trail. */
   draft: number;
+  /** How much the pointer trail brightens the density, added as `trail * 0.30 * this`. */
   pointerStrength: number;
+  /** How far the whole field shifts against the pointer, in uv. */
   parallax: number;
+  /** Device-pixel-ratio cap for the canvas; 1 halves the pixel count on a 2x screen and keeps the fill cheap. */
   maxDpr: number;
 };
 
-/** The Horon sky palette for Flue. Recolour through these values only, never the shader. */
+/**
+ * The Horon sky palette for Flue. Recolour through these values only, never the shader.
+ *
+ * It is a complete `FlueConfig`, so it doubles as the base every variant tunes on top of, and its
+ * `cursor: 0` / `maxDpr: 1` keep the default cheap: a still-ish plume at 1x pixel density.
+ */
 export const FLUE_SKY: FlueConfig = {
   bgColor: "#eef3f8",
   colorA: "#e3ecf6",
@@ -76,7 +120,12 @@ export const FLUE_SKY: FlueConfig = {
   maxDpr: 1,
 };
 
-/** The night palette for dark mode: near-black ground and blue smoke. Same motion as `FLUE_SKY`. */
+/**
+ * The night palette for dark mode: near-black ground and blue smoke. Same motion as `FLUE_SKY`.
+ *
+ * Only the five colors and `glow` differ; every other number is inherited, so light and dark read as the
+ * same plume in two lights.
+ */
 export const FLUE_NIGHT: FlueConfig = {
   ...FLUE_SKY,
   bgColor: "#050608",
@@ -90,9 +139,18 @@ export const FLUE_NIGHT: FlueConfig = {
 /** Where the smoke is drawn; each place tunes the motion and colour on top of `FLUE_SKY` / `FLUE_NIGHT`. */
 export type FlueVariant = "default" | "sidebar" | "auth";
 
-type FlueTuning = { light: Partial<FlueConfig>; dark: Partial<FlueConfig>; tint: string };
+/** One variant's overrides: values layered over the base palette per scheme, plus the tint laid on top. */
+type FlueTuning = {
+  /** Overrides applied on top of `FLUE_SKY` in light mode. */
+  light: Partial<FlueConfig>;
+  /** Overrides applied on top of `FLUE_NIGHT` in dark mode. */
+  dark: Partial<FlueConfig>;
+  /** Classes for the tint div over the smoke; `""` adds none, and it yields to `tintClassName`. */
+  tint: string;
+};
 
 /**
+ * - `default`: no motion overrides, under a regular glass tint in light mode and none in dark.
  * - `sidebar`: a narrow, tall column under the sidebar's glass. The glass blurs the detail away, so the smoke
  *   is calmer and larger, kept low in the column so the nav labels at the top sit on the quiet part. The canvas
  *   paints above the sidebar's own fill, so in light mode the variant lays the thick glass (80% white) over the
@@ -133,21 +191,6 @@ const FLUE_VARIANTS: Record<FlueVariant, FlueTuning> = {
   },
 };
 
-/** Follows the `.dark` class on <html>, the switch the theme uses. */
-function subscribeScheme(onChange: () => void): () => void {
-  const observer = new MutationObserver(onChange);
-  observer.observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
-  return () => observer.disconnect();
-}
-
-function useDarkScheme(): boolean {
-  return useSyncExternalStore(
-    subscribeScheme,
-    () => document.documentElement.classList.contains("dark"),
-    () => false,
-  );
-}
-
 const ENGINE_KEYS = new Set(["cursor", "maxDpr"]);
 
 const VERT = `#version 300 es
@@ -202,10 +245,13 @@ function activate(gl: WebGL2RenderingContext, program: WebGLProgram): void {
   gl[USE_PROGRAM](program);
 }
 
+/** Props of {@link FlueBackground}: placement, which variant, and per-instance shader overrides. */
 export type FlueBackgroundProps = {
+  /** Extra classes for the wrapper, which is already `absolute inset-0 -z-10 overflow-hidden`. */
   className?: string;
+  /** Inline styles for the wrapper; `backgroundColor` is set from the resolved `bgColor` before these apply. */
   style?: CSSProperties;
-  /** `sidebar` under the sidebar glass, `auth` behind the sign-in screen, `default` otherwise. */
+  /** `sidebar` under the sidebar glass, `auth` behind the sign-in screen, `default` otherwise. @default "default" */
   variant?: FlueVariant;
   /** Overrides on top of the variant's `FLUE_SKY` (light) or `FLUE_NIGHT` (dark) tuning. */
   config?: Partial<FlueConfig>;
@@ -218,10 +264,34 @@ export type FlueBackgroundProps = {
  * It fills its positioned parent behind the content (the parent needs `isolate`) and falls
  * back to the flat `bgColor` when WebGL2 is missing. Reduced motion draws a single still frame.
  * Light mode paints the white-and-sky `FLUE_SKY`; dark mode paints the black-and-blue `FLUE_NIGHT`.
+ *
+ * The wrapper is `absolute inset-0 -z-10`, `pointer-events-none` and `aria-hidden`, with a tint div over the
+ * canvas, so it never intercepts input and the content above it stays readable. Settings resolve as palette +
+ * variant tuning + `config`; the effect is keyed by their JSON, so changing `config` rebuilds the program.
+ * Drawing pauses while the canvas is off-screen (`IntersectionObserver`) or the tab is hidden, and the
+ * device-pixel ratio is capped by `maxDpr`. `cursor: 0` (the default) swaps the real pointer for a slow
+ * virtual one that wanders on two incommensurate sines, so a pointerless panel still breathes; `cursor: 1`
+ * follows the real pointer. A context lost
+ * by a previous run leaves the flat color instead of throwing, and cleanup frees this run's GL objects
+ * without dropping the shared context.
+ *
+ * @example
+ * ```tsx
+ * import { FlueBackground } from "@horon-ai/react";
+ *
+ * function Sidebar() {
+ *   return (
+ *     <div className="relative isolate min-h-96 overflow-hidden rounded-xl bg-bg-default">
+ *       <FlueBackground variant="sidebar" config={{ speed: 0.5 }} />
+ *       <nav className="relative p-6 text-text-primary">Navigation</nav>
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 export function FlueBackground({ className, style, variant = "default", config, tintClassName }: FlueBackgroundProps) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
-  const dark = useDarkScheme();
+  const dark = useColorScheme() === "dark";
   const tuning = FLUE_VARIANTS[variant];
   const settings = { ...(dark ? FLUE_NIGHT : FLUE_SKY), ...(dark ? tuning.dark : tuning.light), ...config };
   const key = JSON.stringify(settings);