@danxbot/ui 3.7.0 → 3.9.0

package/dist/pure.js

@@ -0,0 +1,17 @@
+function u(r) {
+  if (!Number.isFinite(r) || r < 0) return "";
+  if (r < 1024) return `${r} B`;
+  const t = ["KB", "MB", "GB", "TB"];
+  let i = r / 1024, e = 0;
+  for (; i >= 1024 && e < t.length - 1; )
+    i /= 1024, e += 1;
+  return `${i < 10 ? i.toFixed(1) : Math.round(i)} ${t[e]}`;
+}
+function n(r) {
+  return Number.isFinite(r) ? r < 1e3 ? String(Math.round(r)) : r < 1e6 ? `${Number((r / 1e3).toFixed(1))}k` : `${Number((r / 1e6).toFixed(1))}M` : "—";
+}
+export {
+  u as formatBytes,
+  n as formatTokens
+};
+//# sourceMappingURL=pure.js.map

package/dist/pure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pure.js","sources":["../src/lib/format.ts"],"sourcesContent":["/* ----------------------------------------------------------------------------\n   NUMBERS, TURNED INTO THE STRINGS PEOPLE READ.\n\n   These lived inside the components that needed them first — `formatBytes` in\n   `chat/Attachment.tsx`, `formatTokens` in `chat/ContextMeter.tsx` — which was\n   fine right up until somebody outside a component wanted one. The package\n   exports a single entry, so importing `formatBytes` into an application's own\n   formatting layer dragged React and every component in this library into a\n   layer that is deliberately framework-free.\n\n   They are here because they are DECISIONS, not utilities: how much precision\n   a reader can act on, and where a rounded figure stops telling the truth. Two\n   places rendering the same quantity to different precision is the defect this\n   file prevents — see each function for the call it makes.\n\n   NOTHING IN THIS FILE MAY IMPORT REACT, directly or transitively. It is the\n   whole content of the `@danxbot/ui/pure` entry; `src/pure.ts` states the\n   contract and `pure-entry.test.ts` enforces it against both the source graph\n   and the built artifact.\n   -------------------------------------------------------------------------- */\n\n/** Binary units, because these are file sizes and every OS reports them this way. */\nexport function formatBytes(bytes: number): string {\n  if (!Number.isFinite(bytes) || bytes < 0) return \"\";\n  if (bytes < 1024) return `${bytes} B`;\n  const units = [\"KB\", \"MB\", \"GB\", \"TB\"];\n  let value = bytes / 1024;\n  let unit = 0;\n  while (value >= 1024 && unit < units.length - 1) {\n    value /= 1024;\n    unit += 1;\n  }\n  /* One decimal below 10 and none above: \"1.4 MB\" is useful precision,\n     \"847.3 KB\" is noise on a number nobody acts on. */\n  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;\n}\n\n/**\n * 241_600 → \"241.6k\".\n *\n * One decimal all the way to 1M, and exact below 1k. Unlike a file size — where\n * a tenth of a kilobyte is noise on a number nobody acts on — the tenth here is\n * the digit that moves while you work: at 1M capacity, a whole percent is\n * 10_000 tokens, so rounding to \"242k\" holds a figure still for several\n * exchanges and makes a live meter look frozen.\n */\nexport function formatTokens(tokens: number): string {\n  if (!Number.isFinite(tokens)) return \"—\";\n  if (tokens < 1_000) return String(Math.round(tokens));\n  if (tokens < 1_000_000) return `${Number((tokens / 1_000).toFixed(1))}k`;\n  return `${Number((tokens / 1_000_000).toFixed(1))}M`;\n}\n"],"names":["formatBytes","bytes","units","value","unit","formatTokens","tokens"],"mappings":"AAsBO,SAASA,EAAYC,GAAuB;AACjD,MAAI,CAAC,OAAO,SAASA,CAAK,KAAKA,IAAQ,EAAG,QAAO;AACjD,MAAIA,IAAQ,KAAM,QAAO,GAAGA,CAAK;AACjC,QAAMC,IAAQ,CAAC,MAAM,MAAM,MAAM,IAAI;AACrC,MAAIC,IAAQF,IAAQ,MAChBG,IAAO;AACX,SAAOD,KAAS,QAAQC,IAAOF,EAAM,SAAS;AAC5C,IAAAC,KAAS,MACTC,KAAQ;AAIV,SAAO,GAAGD,IAAQ,KAAKA,EAAM,QAAQ,CAAC,IAAI,KAAK,MAAMA,CAAK,CAAC,IAAID,EAAME,CAAI,CAAC;AAC5E;AAWO,SAASC,EAAaC,GAAwB;AACnD,SAAK,OAAO,SAASA,CAAM,IACvBA,IAAS,MAAc,OAAO,KAAK,MAAMA,CAAM,CAAC,IAChDA,IAAS,MAAkB,GAAG,QAAQA,IAAS,KAAO,QAAQ,CAAC,CAAC,CAAC,MAC9D,GAAG,QAAQA,IAAS,KAAW,QAAQ,CAAC,CAAC,CAAC,MAHZ;AAIvC;"}

package/dist/types/components/Badge.d.ts

@@ -58,8 +58,36 @@ declare const badge: import("tailwind-variants").TVReturnType<{
         false: "";
     };
 }, undefined>>;
+/**
+ * What a badge needs in order to be removable, in one object.
+ *
+ * ONE PROP RATHER THAN TWO, and the label being a required FIELD is the point:
+ * a dismiss control with no accessible name is not expressible. An icon carries
+ * no text, and a row of filter chips is exactly where "Remove" spoken five
+ * times distinguishes nothing — the same argument that makes `IconButton.label`
+ * required. `SettingRow`'s `readOnly: { reason }` uses the same shape for the
+ * same reason: an explanation that is part of the type cannot be forgotten.
+ *
+ * Name what it removes ("Remove the infra filter"), not the picture ("Close").
+ */
+export interface BadgeDismiss {
+    label: string;
+    onDismiss: () => void;
+}
 export interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badge> {
     icon?: ReactNode;
+    /**
+     * Makes the badge a chip you can take off — a trailing × after the label.
+     *
+     * Absent means a plain label, which is what every existing badge is: an ×
+     * nobody asked for is a destructive control appearing inside a caption.
+     *
+     * NOT FOR A BADGE INSIDE A BUTTON. `StatusSelect` renders its Badge as the
+     * body of a trigger, and a `<button>` inside a `<button>` is invalid and
+     * unreachable by keyboard. A dismissible badge belongs on a surface, not in
+     * a control.
+     */
+    dismiss?: BadgeDismiss;
     /**
      * Ping the dot outward — for genuinely LIVE states only (running, connected,
      * streaming). A pulse on a static label is the badge equivalent of a blinking
@@ -69,5 +97,5 @@ export interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProp
     pulse?: boolean;
     ref?: Ref<HTMLSpanElement>;
 }
-export declare function Badge({ className, tone, size, dot, icon, pulse, children, ref, ...props }: BadgeProps): import("react").JSX.Element;
+export declare function Badge({ className, tone, size, dot, icon, pulse, dismiss, children, ref, ...props }: BadgeProps): import("react").JSX.Element;
 export { badge as badgeVariants };

package/dist/types/components/StatusSelect.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import { type ReactNode } from "react";
 import { type BadgeProps } from "./Badge";
 export interface StatusOption<Value extends string = string> {
     value: Value;
@@ -9,6 +9,29 @@ export interface StatusOption<Value extends string = string> {
     dot?: boolean;
     /** Reserved for a genuinely live state — see `Badge`'s own `pulse` doc. */
     pulse?: boolean;
+    /**
+     * Why this status cannot be chosen HERE. Absent means it can.
+     *
+     * The option is still listed, still carries its own tone and label, and is
+     * still what the trigger shows when the record is sitting in it — it simply
+     * never accepts. That is the difference between a status the consumer does
+     * not assign and a status the consumer does not have, and only one of them
+     * belongs out of the list.
+     *
+     * Written for the person who would have picked it — "the pipeline enters
+     * this stage on its own", not "not allowed". It is rendered under the badge
+     * rather than only dimming the row, and attached to the row as its
+     * description, so the refusal is never mute. Same call `IconButton`'s
+     * `disabledReason` makes, and it is `aria-disabled` there for the same
+     * reason: a natively disabled control cannot be reached to be asked why.
+     *
+     * AN EMPTY STRING THROWS, matching `Step.blocked` rather than
+     * `KanbanLane.refusal`. There the reason is supporting detail on a lane that
+     * is already visibly refusing; here the sentence IS the mechanism, and an
+     * empty one produces exactly the dead row with nothing beside it that this
+     * prop exists to prevent.
+     */
+    refusal?: string;
 }
 export interface StatusSelectProps<Value extends string = string> {
     value: Value;
@@ -18,6 +41,14 @@ export interface StatusSelectProps<Value extends string = string> {
     /** Accessible name for the trigger — there is no visible label otherwise. */
     "aria-label"?: string;
     disabled?: boolean;
+    /**
+     * What the trigger says when `value` matches no option — a state that is
+     * always a mistake somewhere, so this is the wording of the report rather
+     * than a label anyone should be seeing.
+     *
+     * Defaults to "Unknown". It is NOT the raw value: see the component body.
+     */
+    placeholder?: ReactNode;
     className?: string;
 }
-export declare function StatusSelect<Value extends string = string>({ value, options, onValueChange, size, "aria-label": ariaLabel, disabled, className, }: StatusSelectProps<Value>): import("react").JSX.Element;
+export declare function StatusSelect<Value extends string = string>({ value, options, onValueChange, size, "aria-label": ariaLabel, disabled, placeholder, className, }: StatusSelectProps<Value>): import("react").JSX.Element;

package/dist/types/components/Table.d.ts

@@ -40,13 +40,38 @@ export interface DataTableProps<TData> {
      */
     pageSize?: number;
     emptyState?: ReactNode;
+    /**
+     * An extra class for the rows a consumer needs to mark — "this figure could
+     * not be read from the source document", "this record is superseded". Return
+     * `undefined` for the rows that are unremarkable.
+     *
+     * WHY A HOOK AND NOT A `tone` UNION. The reasons a row deserves a tint are
+     * the consumer's domain and there is no useful shortlist of them; a fixed set
+     * would be wrong for the second consumer and every one after. This is the
+     * same call `getRowId` makes about identity.
+     *
+     * THE CLASS IS APPLIED LAST, so it beats the density, zebra and selection
+     * styling the table picked — `cn` is tailwind-merge, and the last conflicting
+     * utility wins. That is deliberate: a tint that loses to the zebra fill is a
+     * tint nobody sees. It also means a background handed over here REPLACES the
+     * row's hover fill, so pass the hover with it (`bg-warning-subtle
+     * hover:bg-warning-subtle-hover`) if the row should still respond.
+     *
+     * `index` is the row's position in `data`, not on the current page — the same
+     * number `getRowId` receives, so the two never disagree about which row is
+     * being talked about.
+     *
+     * NOT CALLED FOR SKELETON ROWS. A skeleton stands in for a record nobody has
+     * yet, so there is nothing to classify and nothing to hand over.
+     */
+    getRowClassName?: (row: TData, index: number) => string | undefined;
     onRowClick?: (row: TData) => void;
     /** Rendered above the table; receives the table instance for counts/filters. */
     toolbar?: (table: TanstackTable<TData>) => ReactNode;
     className?: string;
     getRowId?: (row: TData, index: number) => string;
 }
-export declare function DataTable<TData>({ data, columns, density, selectable, maxHeight, zebra, loading, refreshing, loadingRows, pageSize, emptyState, onRowClick, toolbar, className, getRowId, }: DataTableProps<TData>): import("react").JSX.Element;
+export declare function DataTable<TData>({ data, columns, density, selectable, maxHeight, zebra, loading, refreshing, loadingRows, pageSize, emptyState, getRowClassName, onRowClick, toolbar, className, getRowId, }: DataTableProps<TData>): import("react").JSX.Element;
 export declare function TableEmptyState({ icon, title, description, action, }: {
     icon?: ReactNode;
     title?: string;

package/dist/types/components/Toggle.d.ts

@@ -3,6 +3,8 @@ import { Toggle as BaseToggle } from "@base-ui/react/toggle";
 import { ToggleGroup as BaseToggleGroup } from "@base-ui/react/toggle-group";
 import { Toolbar as BaseToolbar } from "@base-ui/react/toolbar";
 import { type VariantProps } from "tailwind-variants";
+import { type ButtonProps } from "./Button";
+import { type InputProps } from "./Input";
 declare const toggle: import("tailwind-variants").TVReturnType<{
     size: {
         sm: "h-control-sm px-2.5 text-xs";
@@ -62,4 +64,64 @@ export declare function Toolbar({ className, children, ref, ...props }: ToolbarP
 export declare function ToolbarSeparator({ className }: {
     className?: string;
 }): import("react").JSX.Element;
+export interface ToolbarButtonProps extends Omit<BaseToolbar.Button.Props, "className" | "nativeButton">, Pick<ButtonProps, "variant" | "size" | "iconOnly"> {
+    className?: string;
+    ref?: Ref<HTMLButtonElement>;
+}
+/**
+ * A button that is part of the toolbar's rotation.
+ *
+ * It wears `buttonVariants` — the same recipe `Button` compiles — rather than a
+ * second class list, so the two can never drift apart. It is not `Button`
+ * itself because the registration has to own the element: Base UI needs to put
+ * its own `tabIndex` and key handling on the rendered node, and the
+ * `focusableWhenDisabled` behaviour below depends on NOT setting the native
+ * `disabled` attribute, which `Button` sets unconditionally.
+ *
+ * `ghost` at `sm` by default — the right resting state in a row of controls,
+ * the same default `IconButton` picks. A row of solid buttons reads as a row of
+ * primary actions, which no toolbar is.
+ *
+ * ANYTHING ALREADY BUILT ON `Button` GOES IN THROUGH `render`, which is what
+ * keeps this from becoming a second button component:
+ * `<ToolbarButton render={<IconButton icon={…} label="Bold" />} />` registers
+ * exactly the same, keeps the tooltip and the `disabledReason`, and never
+ * duplicates a variant table.
+ */
+export declare function ToolbarButton({ variant, size, iconOnly, className, children, ref, ...props }: ToolbarButtonProps): import("react").JSX.Element;
+export interface ToolbarInputProps extends Omit<InputProps, "ref">, Pick<BaseToolbar.Input.Props, "focusableWhenDisabled"> {
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * A text field that is part of the toolbar's rotation — a filter box beside the
+ * buttons that filter with it.
+ *
+ * Renders this library's own `Input` through Base UI's `render` slot, so the
+ * adornments, sizes and focus ring are the ones every other field in the
+ * application already has. The composite's props land on the `<input>` itself
+ * rather than on `Input`'s adornment wrapper, which is what keeps DOM order —
+ * and therefore the arrow-key order — matching what the reader sees.
+ *
+ * Arrow keys still move OUT of it, which is Base UI's deliberate call and not
+ * an oversight: a toolbar field is a filter box, not a document, and a caret
+ * that traps the only navigation key in the pattern is worse than one that
+ * moves on.
+ */
+export declare function ToolbarInput({ focusableWhenDisabled, ref, ...props }: ToolbarInputProps): import("react").JSX.Element;
+export interface ToolbarGroupProps extends Omit<BaseToolbar.Group.Props, "className"> {
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * A labelled cluster of toolbar controls — "Alignment", "Text style".
+ *
+ * IT IS NOT ITSELF A STOP. The group renders `role="group"` and its CHILDREN
+ * register; a group that registered would insert a phantom position between the
+ * controls it contains. Give it an `aria-label`: a group announced as an
+ * unnamed group is noise in the rotation rather than context for it.
+ *
+ * Distinct from `ToggleGroup`, which is a set of related toggles with a shared
+ * VALUE. This one shares only a name.
+ */
+export declare function ToolbarGroup({ className, children, ref, ...props }: ToolbarGroupProps): import("react").JSX.Element;
 export {};

package/dist/types/components/chat/Attachment.d.ts

@@ -1,13 +1,31 @@
 import { type ReactNode, type Ref } from "react";
 import type { ChatFile } from "./types";
-/** Binary units, because these are file sizes and every OS reports them this way. */
-export declare function formatBytes(bytes: number): string;
 export type AttachmentLayout = "tile" | "row";
 export interface AttachmentProps {
     file: ChatFile;
     layout?: AttachmentLayout;
     /** Overrides the size line — "Sheet 2 of 4", a page count, anything truer. */
     meta?: ReactNode;
+    /**
+     * The consumer's own control, rendered first in the action cluster — "Extract
+     * this", "Attach to the demand", "Cancel the upload".
+     *
+     * A SLOT RATHER THAN ANOTHER BOOLEAN, because the library has no opinion
+     * about what the verb is and a fixed list would be wrong for the second
+     * consumer and every one after. Remove, preview and download stay separate
+     * props: they are the three actions an attachment has REGARDLESS of the
+     * application, and each carries its own rule about when it may appear.
+     *
+     * NO RULE IS IMPOSED ON THIS ONE. Download hides itself while a file is still
+     * uploading, because there is nothing complete to fetch; the consumer's action
+     * may well BE "cancel this upload", so it is rendered whatever the file's
+     * state, and the consumer decides whether their verb makes sense yet.
+     *
+     * It goes inside the cluster, above the full-card preview trigger — rendered
+     * anywhere else it would sit UNDER that trigger and never receive a click.
+     * Keep it to a control or two: this is a corner of a tile, not a menu bar.
+     */
+    action?: ReactNode;
     onRemove?: (file: ChatFile) => void;
     onPreview?: (file: ChatFile) => void;
     onDownload?: (file: ChatFile) => void;
@@ -17,7 +35,7 @@ export interface AttachmentProps {
     className?: string;
     ref?: Ref<HTMLDivElement>;
 }
-export declare function Attachment({ file, layout, meta, onRemove, onPreview, onDownload, selected, disabled, className, ref, }: AttachmentProps): import("react").JSX.Element;
+export declare function Attachment({ file, layout, meta, action, onRemove, onPreview, onDownload, selected, disabled, className, ref, }: AttachmentProps): import("react").JSX.Element;
 export interface AttachmentPreviewProps {
     file: ChatFile | null;
     onOpenChange: (open: boolean) => void;
@@ -38,6 +56,15 @@ export declare function AttachmentPreview({ file, onOpenChange, onDownload, rend
 export interface AttachmentListProps {
     files: ChatFile[];
     layout?: AttachmentLayout;
+    /**
+     * `Attachment.action`, per file — a FUNCTION rather than a node, because the
+     * control almost always has to know which file it is on.
+     *
+     * Without it the slot would exist only on a lone `Attachment`, and a consumer
+     * wanting one on a list would have to stop using the list — which is the
+     * rebuild this slot was added to prevent, one level up.
+     */
+    action?: (file: ChatFile) => ReactNode;
     onRemove?: (file: ChatFile) => void;
     onPreview?: (file: ChatFile) => void;
     onDownload?: (file: ChatFile) => void;
@@ -46,4 +73,4 @@ export interface AttachmentListProps {
     disabled?: boolean;
     className?: string;
 }
-export declare function AttachmentList({ files, layout, onRemove, onPreview, onDownload, max, disabled, className, }: AttachmentListProps): import("react").JSX.Element | null;
+export declare function AttachmentList({ files, layout, action, onRemove, onPreview, onDownload, max, disabled, className, }: AttachmentListProps): import("react").JSX.Element | null;

package/dist/types/components/chat/ContextMeter.d.ts

@@ -6,16 +6,6 @@ export interface ContextSegment {
     /** Any CSS colour. Defaults walk a fixed palette in declaration order. */
     color?: string;
 }
-/**
- * 241_600 → "241.6k".
- *
- * One decimal all the way to 1M, and exact below 1k. Unlike a file size — where
- * a tenth of a kilobyte is noise on a number nobody acts on — the tenth here is
- * the digit that moves while you work: at 1M capacity, a whole percent is
- * 10_000 tokens, so rounding to "242k" holds a figure still for several
- * exchanges and makes a live meter look frozen.
- */
-export declare function formatTokens(tokens: number): string;
 export interface UsageLimit {
     id: string;
     label: string;

package/dist/types/index.d.ts

@@ -14,7 +14,7 @@ export { registerIcon, registerIcons, getIcon, hasIcon, iconNames, type IconNode
 export { coreIcons, type CoreIconName } from "./icons/data";
 export { Button, buttonVariants, type ButtonProps } from "./components/Button";
 export { IconButton, type IconButtonProps, type IconButtonVariant, type IconButtonTone, } from "./components/IconButton";
-export { Badge, badgeVariants, type BadgeProps } from "./components/Badge";
+export { Badge, badgeVariants, type BadgeProps, type BadgeDismiss, } from "./components/Badge";
 export { Callout, calloutVariants, type CalloutProps } from "./components/Callout";
 export { Spinner, type SpinnerProps } from "./components/Spinner";
 export { Skeleton, SkeletonText, LoadingOverlay, type SkeletonProps, type SkeletonTextProps, type LoadingOverlayProps, } from "./components/Loading";
@@ -48,7 +48,7 @@ export { Accordion, AccordionItem, type AccordionProps, type AccordionItemProps,
 export { Breadcrumb, Pagination, type BreadcrumbProps, type PaginationProps, type Crumb, } from "./components/Navigation";
 export { Stepper, stepStatus, stepperProgress, advanceBlockReason, assertSteps, type StepperProps, type Step, type StepStatus, type StepperProgress, } from "./components/stepper";
 export { StatusChecklist, tallyChecklist, type StatusChecklistProps, type ChecklistItem, type ChecklistState, type ChecklistTally, } from "./components/checklist";
-export { Toggle, ToggleGroup, Toolbar, ToolbarSeparator, type ToggleProps, type ToggleGroupProps, type ToolbarProps, } from "./components/Toggle";
+export { Toggle, ToggleGroup, Toolbar, ToolbarButton, ToolbarGroup, ToolbarInput, ToolbarSeparator, type ToggleProps, type ToggleGroupProps, type ToolbarProps, type ToolbarButtonProps, type ToolbarGroupProps, type ToolbarInputProps, } from "./components/Toggle";
 export { Separator, ScrollArea, Collapsible, EmptyState, Timeline, type SeparatorProps, type ScrollAreaProps, type CollapsibleProps, type EmptyStateProps, type TimelineProps, type TimelineItem, } from "./components/Surface";
 export { PanelGroup, Panel, PanelResizer, type PanelGroupProps, type PanelProps, type PanelResizerProps, type PanelDirection, type PanelNarrowMode, } from "./components/Panel";
 export { Avatar, AvatarGroup, type AvatarProps, type AvatarGroupProps, type AvatarStatus, } from "./components/Avatar";
@@ -85,11 +85,12 @@ export { Message, MessagePartView, ToolCall, ChatMarker, type MessageProps, type
 export { MessageScroller, type MessageScrollerProps, } from "./components/chat/MessageScroller";
 export { Composer, type ComposerProps } from "./components/chat/Composer";
 export { Markdown, CodeBlock, type MarkdownProps, type CodeBlockProps } from "./components/chat/Markdown";
-export { Attachment, AttachmentList, AttachmentPreview, formatBytes, type AttachmentProps, type AttachmentListProps, type AttachmentPreviewProps, type AttachmentLayout, } from "./components/chat/Attachment";
+export { Attachment, AttachmentList, AttachmentPreview, type AttachmentProps, type AttachmentListProps, type AttachmentPreviewProps, type AttachmentLayout, } from "./components/chat/Attachment";
 export { ModelSelector, type ModelSelectorProps, type ChatModel, } from "./components/chat/ModelSelector";
 export { EffortControl, DEFAULT_EFFORT_LEVELS, type EffortControlProps, type EffortLevel, } from "./components/chat/EffortControl";
-export { ContextMeter, ChatStatus, formatTokens, type ContextMeterProps, type ContextSegment, type UsageLimit, type ChatStatusProps, } from "./components/chat/ContextMeter";
+export { ContextMeter, ChatStatus, type ContextMeterProps, type ContextSegment, type UsageLimit, type ChatStatusProps, } from "./components/chat/ContextMeter";
 export { cn } from "./lib/cn";
+export { formatBytes, formatTokens } from "./lib/format";
 export { useFillHeight } from "./lib/use-fill-height";
 export { useTheme, useUiScale, useContrast, useMotionPreference, type Theme, type UiScale, type ContrastPreference, type MotionPreference, } from "./lib/preferences";
 export { usePersistedState, readStored, writeStored, clearStored, storageKey, type PersistedStateOptions, } from "./lib/persist";
@@ -110,3 +111,6 @@ export { UseCaseCard, RoadmapItemCard, RoadmapSwimlaneBoard, UseCaseLedgerPage,
 export { ProvenanceDisclosure, ProvenanceBadge, ConfidenceMeter, provenanceStateLabel, confidenceBand, type ProvenanceRecord, type ProvenanceState, type ProvenanceSource, type ProvenanceCheck, type ProvenanceCall, type ProvenanceSignoff, type ConfidenceBand, type ProvenanceDisclosureProps, type ProvenanceTriggerBadge, type ProvenanceBadgeProps, type ProvenanceBadgeAppearance, type ConfidenceMeterProps, } from "./components/provenance";
 export { createSimStore, resetSimStores, useSimSettings, setSimSettings, getNetworkSpeed, getDataSource, simulateLatency, SimNetworkError, type SimStore, type SimStoreOptions, type SimSettings, type NetworkSpeed, type DataSource, type SimNamespace, } from "./lib/sim";
 export { NodeCanvas, LAYOUT_DEFAULTS, layoutTree, pathToNode, type NodeCanvasProps, type CanvasEdge, type CanvasLayout, type CanvasNode, type CanvasOrientation, type LayoutOptions, type NodeRenderContext, type NodeRenderer, type PlacedNode, } from "./components/node-canvas";
+export { defineRecordType, resetRecordTypes, useRecord, useRecords, useStaleness, write, writeAll, peekRecord, readState, readStaleness, subscribeToKey, subscribeToStaleness, retainKeys, sweepRecords, setRecordStoreTenant, getRecordStoreTenant, flushRecordNotifications, resetRecordStore, recordStoreStats, UNKNOWN_STATE, normalizeTypeName, normalizeTimestamp, recordKey, isRecordRef, type RecordRef, type ReadOptions, type RecordPayload, type RecordState, type RecordTypeOptions, type RecordTypeToken, type StalenessEntry, type WriteAllResult, type WriteOptions, type WriteResult, type WriteSource, type WriteVerdict, } from "./lib/records";
+export { RealtimeProvider, useRealtime, useRealtimeEpoch, useRealtimeHealth, useRealtimeRegistry, SubscriptionRegistry, normalizeScope, scopeKey, readRealtimeEpoch, subscribeToRealtimeEpoch, subscribeToRealtimeEvents, resetRealtimeSignals, type RealtimeChannel, type RealtimeConnectionState, type RealtimeDiagnostic, type RealtimeEvent, type RealtimeHealth, type RealtimeProviderProps, type RealtimeScope, type RealtimeScopeInput, type RealtimeStatus, type RealtimeTransport, type RegistryOptions, type SubscriptionHealth, type SubscriptionLease, type SubscriptionRequest, } from "./lib/realtime";
+export { useRecordRead, useRecordListRead, useRecordStoreSweep, applyMutationResult, acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type ListFetch, type ListFetchResult, type ListReadOptions, type ListReadResult, type ReadError, type RecordFetch, type RecordReadOptions, type RecordReadResult, type RunnerOptions, type SlotSnapshot, } from "./lib/reads";

package/dist/types/lib/format.d.ts

@@ -0,0 +1,12 @@
+/** Binary units, because these are file sizes and every OS reports them this way. */
+export declare function formatBytes(bytes: number): string;
+/**
+ * 241_600 → "241.6k".
+ *
+ * One decimal all the way to 1M, and exact below 1k. Unlike a file size — where
+ * a tenth of a kilobyte is noise on a number nobody acts on — the tenth here is
+ * the digit that moves while you work: at 1M capacity, a whole percent is
+ * 10_000 tokens, so rounding to "242k" holds a figure still for several
+ * exchanges and makes a live meter look frozen.
+ */
+export declare function formatTokens(tokens: number): string;

package/dist/types/lib/reads/hooks.d.ts

@@ -0,0 +1,49 @@
+import { type RecordPayload, type RecordTypeToken, type WriteResult } from "../records";
+import type { ListReadOptions, ListReadResult, RecordReadOptions, RecordReadResult } from "./types";
+/**
+ * Read one record: fetch it, write it into the store tagged with the field set
+ * it asked for, and return the store's answer.
+ *
+ * `id` may be null for a conditional read — the hook then fetches nothing and
+ * reports `unknown`, rather than forcing a caller around a rule of hooks.
+ */
+export declare function useRecordRead<T>(token: RecordTypeToken<T>, id: string | number | null | undefined, options: RecordReadOptions): RecordReadResult<T>;
+/**
+ * Read a page: fetch it, write every row into the store, and record which keys
+ * answered the query in a LIST SLOT.
+ *
+ * The slot is what makes a `created` broadcast visible and a tombstone
+ * removable without a fetch — and it is where `meta` lives, because pagination
+ * has no identity and can never be a record.
+ */
+export declare function useRecordListRead<T, TMeta = unknown>(token: RecordTypeToken<T>, options: ListReadOptions<TMeta>): ListReadResult<T, TMeta>;
+/**
+ * Write a mutation's returned item into the store.
+ *
+ * A MUTATION RESPONSE IS A FETCH, and this exists because that is a question an
+ * implementer will otherwise answer by coin flip. It is a full server answer to
+ * a request this client made: it may satisfy a field-set tag, it clears
+ * staleness on every field it carries, and it must NEVER be dropped by the
+ * self-echo filter — that filter applies to broadcasts, and dropping a
+ * mutation's own response would discard the server-computed fields the caller
+ * asked for. Structurally it cannot be dropped, because the filter lives on the
+ * broadcast path and this does not go through it.
+ */
+export declare function applyMutationResult(payload: RecordPayload, options: {
+    tag: string;
+    tenant?: string | number;
+}): WriteResult;
+/**
+ * Sweep unreachable records on a bounded schedule, for as long as this is
+ * mounted.
+ *
+ * IT IS A HOOK, NOT AN INTERVAL STARTED ON IMPORT. A design-system module that
+ * schedules work because somebody imported it is a worse defect than the leak
+ * it prevents — it runs in every consumer, including ones with no store at all.
+ * So the library exports the sweep and the CONSUMER decides when: this hook at
+ * an app root, a call at a navigation boundary, or both. A navigation boundary
+ * alone is not enough, because a broadcast can create a key no root reaches and
+ * a screen nobody navigates away from accumulates those for as long as the tab
+ * is open.
+ */
+export declare function useRecordStoreSweep(intervalMs?: number): void;

package/dist/types/lib/reads/index.d.ts

@@ -0,0 +1,4 @@
+export { useRecordRead, useRecordListRead, applyMutationResult, useRecordStoreSweep } from "./hooks";
+export { acquireSlot, appendCreatedKey, emptySlotSnapshot, readSlot, resetSlots, slotKeys, subscribeToSlot, writeSlot, type SlotSnapshot, } from "./slots";
+export { RefetchRunner, registerActiveRead, resetActiveReads, type ActiveRead, type RunnerOptions } from "./refetch";
+export type { ListFetch, ListFetchResult, ListReadOptions, ListReadResult, ReadError, RecordFetch, RecordReadOptions, RecordReadResult, } from "./types";

package/dist/types/lib/reads/refetch.d.ts

@@ -0,0 +1,52 @@
+export interface RunnerOptions {
+    readonly minIntervalMs?: number;
+    /** Test seam. Defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * One read's refetch discipline: a floor between runs, and one request in
+ * flight at a time.
+ *
+ * A SECOND SIGNAL ARRIVING MID-FLIGHT SETS A RE-RUN FLAG rather than issuing a
+ * second request. Two overlapping refetches of the same target are not twice as
+ * fresh; they are two answers racing to write, and the loser can be the newer
+ * one.
+ */
+export declare class RefetchRunner {
+    private readonly run;
+    private inFlight;
+    private rerun;
+    private lastFinishedAt;
+    private timer;
+    private disposed;
+    private readonly minIntervalMs;
+    private readonly now;
+    constructor(run: () => Promise<void>, options?: RunnerOptions);
+    /** Ask for a refetch. Respects the floor and the in-flight request. */
+    request(): void;
+    /**
+     * Run now, floor and all.
+     *
+     * For the FIRST fetch and for a key change — neither is a refetch, and making
+     * a fresh screen wait out an interval that exists to damp a broadcast stream
+     * would be the floor working against its own purpose.
+     */
+    runNow(): void;
+    private execute;
+    dispose(): void;
+}
+/** One mounted read, as the driver sees it. */
+export interface ActiveRead {
+    /** The keys this read is responsible for. Re-read per signal: a list's move. */
+    roots(): readonly string[];
+    /** Ask this read to re-issue the request it already made. */
+    request(): void;
+}
+/**
+ * Register a read so staleness and liveness recovery can reach it.
+ *
+ * @returns unregister
+ */
+export declare function registerActiveRead(read: ActiveRead): () => void;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetActiveReads(): void;

package/dist/types/lib/reads/slots.d.ts

@@ -0,0 +1,52 @@
+export interface SlotSnapshot<T = unknown, TMeta = unknown> {
+    readonly items: readonly T[];
+    readonly pending: readonly T[];
+    readonly pendingCount: number;
+    readonly meta: TMeta | undefined;
+    /** Every key the slot holds, fetched and pending. The refetch roots. */
+    readonly keys: readonly string[];
+}
+/** `getServerSnapshot`, and the answer for a slot nothing has written yet. */
+export declare function emptySlotSnapshot(): SlotSnapshot;
+/**
+ * Claim a slot for the duration of the returned release.
+ *
+ * REFCOUNTED AND IDEMPOTENT, which is what makes StrictMode's mount / unmount /
+ * mount leave the slot — and its retained keys — exactly as it found them.
+ */
+export declare function acquireSlot(id: string, options: {
+    type: string;
+    tag: string;
+    acceptsCreated: boolean;
+}): () => void;
+/**
+ * Replace a slot's membership with a fetch's answer.
+ *
+ * A key that arrived through a `created` event and is now in the fetched page
+ * stops being pending — the fetch has placed it, which is the only thing that
+ * ever could.
+ */
+export declare function writeSlot(id: string, keys: readonly string[], meta: unknown): void;
+/**
+ * Append a record that entered the set elsewhere.
+ *
+ * WITH NO POSITION. The server owns sort order and page boundary; a client that
+ * inserts at a guessed index renders a list that is subtly, confidently wrong.
+ */
+export declare function appendCreatedKey(type: string, key: string): void;
+export declare function subscribeToSlot(id: string, listener: () => void): () => void;
+/** The keys a slot holds right now — the roots a targeted refetch matches on. */
+export declare function slotKeys(id: string): readonly string[];
+/**
+ * The slot's projection, memoized to a stable reference.
+ *
+ * IT RECOMPUTES AND THEN COMPARES rather than trusting its dirty flag, because
+ * a member notification does not always change what this slot renders — a
+ * record whose field-set tag is still unsatisfied moves nothing here — and
+ * handing back a fresh array for an unchanged list re-renders every consumer
+ * for nothing. The elements themselves are the store's own reference-stable
+ * snapshots, so comparing them is one identity check each.
+ */
+export declare function readSlot(id: string): SlotSnapshot;
+/** Test seam. Nothing in the library calls this. */
+export declare function resetSlots(): void;