@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/hooks/.use-humanity-signals.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 13917fe1e6b23215d3b8f20208831188 -->
+Client-side React hook that manages invisible bot-protection signals — a honeypot field reference and a mount timestamp — for attachment to public form submissions.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `useHumanitySignals` | Hook | Returns honeypot input props, a signal getter, and a reset function |
+| `honeypotInputProps` | `{ ref, name }` | Spread onto a hidden `<input>` to capture bot-filled values |
+| `getSignals` | `() => HumanitySignals` | Produces the wire object (`HONEYPOT_FIELD` + `ELAPSED_MS_FIELD`) to merge into a POST body |
+| `resetSignals` | `() => void` | Clears the honeypot value and resets the mount timestamp after a successful submit |
+
+**Signal strategy:**
+- `HONEYPOT_FIELD` — a hidden input that legitimate users never fill; non-empty value indicates a bot.
+- `ELAPSED_MS_FIELD` — milliseconds since mount using `performance.now()` (monotonic, immune to wall-clock skew); suspiciously low values indicate automated submissions.
+
+Both signals travel in the request body, so they remain functional behind reverse proxies or prefixed URLs.
+
+## Usage Example
+
+```typescript
+import { useHumanitySignals } from '@/hooks/use-humanity-signals'
+import { HoneypotField } from '@/components/honeypot-field'
+
+function ContactForm() {
+  const { honeypotInputProps, getSignals, resetSignals } = useHumanitySignals()
+
+  async function handleSubmit(formData: Record<string, string>) {
+    await fetch('/api/contact', {
+      method: 'POST',
+      body: JSON.stringify({ ...formData, ...getSignals() }),
+    })
+    resetSignals()
+  }
+
+  return (
+    <form onSubmit={...}>
+      <HoneypotField {...honeypotInputProps} />
+      {/* ...other fields */}
+    </form>
+  )
+}
+```
+
+> This hook is SSR-safe: both `performance.now()` calls are guarded against server-side execution even though the hook is marked `'use client'`.
+
+**Source:** [`use-humanity-signals.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-humanity-signals.ts)

package/src/hooks/.use-near-viewport.md

@@ -1,44 +1,44 @@
-<!-- source-hash: 22dd3f53bc1b8db26b9d173ca6be7427 -->
-A React hook that detects when an element is approaching the viewport using a shared, module-level `IntersectionObserver` pool — one observer instance per unique `rootMargin` value, shared across all components using the hook.
+<!-- source-hash: c797174c623bbd0d74779f436ba36a2f -->
+Provides a shared, module-level `IntersectionObserver` hook that efficiently detects when an element approaches the viewport, firing once and unobserving on first intersection.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `useNearViewport` | Hook | Main hook; returns `ref` and `isNear` state |
-| `UseNearViewportResult` | Interface | Return type generic over element type `T` |
-| `getObserverFor` | Internal | Lazily creates/retrieves a shared `IntersectionObserver` per `rootMargin` |
-| `observers` | `Map<string, IntersectionObserver>` | Module-level singleton pool keyed by `rootMargin` |
-| `subscribers` | `WeakMap<Element, () => void>` | Tracks per-element callbacks; auto-GC'd when elements are removed |
+### Constants & Module-Level Singletons
+
+- **`NEAR_VIEWPORT_ROOT_MARGIN`** — Default lookahead distance (`'500px'`); exported as SSOT for viewport-proximity logic across the codebase.
+- **`observers`** — `Map<string, IntersectionObserver>` keyed by `rootMargin|threshold`; one IO per unique config, shared across all subscribers.
+- **`subscribers`** — `WeakMap<Element, () => void>` mapping observed elements to their callbacks; avoids memory leaks on unmount.
+- **`THRESHOLD_EPSILON`** — Float rounding slack (`0.01`) for sub-pixel `intersectionRatio` comparisons.
+
+### Functions
+
+- **`observerKey(rootMargin, threshold)`** — Generates a stable string key for the observer map.
+- **`getObserverFor(rootMargin, threshold)`** — Returns an existing IO or creates and caches a new one for the given config.
+
+### Hook
+
+- **`useNearViewport<T>(rootMargin?, threshold?)`** — Returns `{ ref, isNear }`. Subscribes the attached element to the shared IO; flips `isNear` to `true` once the element meets the threshold, then unobserves. Safe under React StrictMode's double-mount via callback identity checks.
+
+### Interface
+
+- **`UseNearViewportResult<T>`** — `{ ref: (node: T | null) => void, isNear: boolean }`
 
 ## Usage Example
 
 ```typescript
 import { useNearViewport } from './use-near-viewport';
 
-// Basic lazy-render pattern
-function MediaCard() {
-  const { ref, isNear } = useNearViewport('500px');
-  return (
-    <div ref={ref}>
-      {isNear ? <HeavyMediaComponent /> : <Placeholder />}
-    </div>
-  );
+function LazyCard() {
+  // Start loading 500px before scroll-in (default margin)
+  const { ref, isNear } = useNearViewport();
+  return <div ref={ref}>{isNear ? <HeavyChild /> : <Placeholder />}</div>;
 }
 
-// Strict on-screen detection
-function AnalyticsTracker() {
-  const { ref, isNear } = useNearViewport('0px');
-  useEffect(() => {
-    if (isNear) trackImpression();
-  }, [isNear]);
-  return <div ref={ref} />;
+function HalfVisibleCard() {
+  // Fire only when at least 50% of the element is on-screen
+  const { ref, isNear } = useNearViewport('0px', 0.5);
+  return <div ref={ref}>{isNear ? <Chart /> : null}</div>;
 }
 ```
 
-## Behavior Notes
-
-- **Fires once**: `isNear` flips to `true` on first intersection and never resets; the element is unobserved immediately after
-- **Shared observers**: All components using the same `rootMargin` share a single `IntersectionObserver` — efficient for grid/list pages with many cards
-- **StrictMode safe**: Cleanup uses callback identity checks to survive React's dev-mode double-mount cycle without dropping subscriptions
-- **Race safe**: IO callback re-reads `subscribers` at fire time so late-firing callbacks after unmount cannot invoke stale state setters
+> **Note:** `isNear` is fire-once and never resets. For two-way mount/unmount behavior, use a raw `IntersectionObserver` instead and share `NEAR_VIEWPORT_ROOT_MARGIN` for distance consistency.

package/src/hooks/.use-og-placeholder-url.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 6a8b6b64036a92c403c29835e73faf22 -->
+React hook that resolves a branded OG placeholder image URL by reading runtime endpoints from `ChatRuntime` context and delegating to `buildOgPlaceholderUrl`.
+
+## Key Components
+
+### `UseOgPlaceholderUrlArgs`
+Configuration interface for the hook:
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string \| undefined \| null` | — | Text displayed on the placeholder image |
+| `siteName` | `string` | `''` | Site name shown below the title |
+| `aspect` | `'wide' \| 'square'` | `'wide'` | `'wide'` = 1200×630 social card; `'square'` = 1024×1024 for compact chat-inline slots |
+| `enabled` | `boolean` | `true` | When `false`, returns `null` instead of a URL |
+
+### `useOgPlaceholderUrl`
+The single canonical hook for OG placeholder resolution. Reads `endpoints` from `ChatRuntime` context and passes them to `buildOgPlaceholderUrl`, which resolves the route base via:
+
+1. Explicit `ogPlaceholderUrl` endpoint
+2. Derived from `imageProxyUrlPrefix`
+3. Same-origin fallback `/api/og-placeholder`
+
+Returns a memoized `string | null`. Per-platform brand colors are resolved server-side by the route handler — nothing is baked into the URL.
+
+## Usage Example
+
+```typescript
+import { useOgPlaceholderUrl } from './use-og-placeholder-url'
+
+function LinkCard({ title, siteName }: { title: string; siteName: string }) {
+  // Wide social-card placeholder (default)
+  const placeholderUrl = useOgPlaceholderUrl({ title, siteName })
+
+  // Square variant for compact chat-inline slots
+  const squarePlaceholderUrl = useOgPlaceholderUrl({
+    title,
+    siteName,
+    aspect: 'square',
+  })
+
+  // Conditionally disabled — returns null when no title is available
+  const conditionalUrl = useOgPlaceholderUrl({
+    title,
+    enabled: Boolean(title),
+  })
+
+  return <img src={placeholderUrl ?? '/fallback.png'} alt={title} />
+}
+```
+
+## Notes
+
+- Replaces the older builder-injection pattern `useOgPlaceholder(buildUrl, …)` — callers no longer supply a URL builder.
+- `useEntityCardPlaceholder` delegates here, ensuring all surfaces share one memo and one code path.
+- Safe to call with a nullish `title`; returns `null` without throwing.
+
+**Source:** [`use-og-placeholder-url.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-og-placeholder-url.ts)

package/src/hooks/.use-scroll-to-hash.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 41cddbc1609de359a4385ad11867ade8 -->
+Scrolls the page to `window.location.hash` after a dependency resolves, using a `requestAnimationFrame` polling loop to handle lazy-mounted elements like Radix accordion panels or SWR-fetched rows.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `useScrollToHash` | Hook | Main hook that drives hash-based scroll behavior |
+| `UseScrollToHashOptions` | Interface | Configuration options for the hook |
+| `MAX_POLL_FRAMES` | Constant | rAF poll budget (~1s at 60fps) before giving up |
+
+### `UseScrollToHashOptions`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `headerOffset` | `number` | `0` | Pixels to subtract for sticky headers/chrome |
+
+## Usage Example
+
+```typescript
+// Basic — runs on mount for SSR-rendered anchors
+useScrollToHash()
+
+// Wait for async data before attempting scroll
+const { data } = useSWR('/api/items')
+useScrollToHash(data)
+
+// With sticky header compensation
+useScrollToHash(data, { headerOffset: 64 })
+
+// Delay until accordion/drawer is fully open
+const [isOpen, setIsOpen] = useState(false)
+useScrollToHash(isOpen)
+```
+
+## Behavior Notes
+
+- **Polling:** Calls `requestAnimationFrame` up to `MAX_POLL_FRAMES` (60) times, giving lazy-mounted DOM nodes ~1 second to appear before aborting.
+- **Skipped when** `readyDep` is `null` or `false` — safe to pass unresolved async state directly.
+- **Re-runs on:** `hashchange` events (browser back/forward navigation) and the synthetic `navigateSamePageHash` event, in addition to `readyDep` reference changes.
+- **Concurrent safety:** Cancels any in-flight rAF poll before starting a new one to prevent double-scroll races.
+- **SSR safe:** Guards against `window` being undefined.
+
+## Source
+
+[`use-scroll-to-hash.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-scroll-to-hash.ts)

package/src/hooks/.use-self-fetch.md

@@ -0,0 +1,52 @@
+<!-- source-hash: 884662ede8163c89d9ac2a0519142f27 -->
+A lightweight React hook that fetches JSON data into component state using plain `fetch` + `useEffect`, intentionally avoiding any external data-fetching library (no react-query, no QueryClient required).
+
+## Key Components
+
+### `UseSelfFetchResult<T>`
+Return type interface exposing:
+- `data` — fetched payload or `null`
+- `setData` — imperative state setter for optimistic updates
+- `isLoading` — boolean loading indicator
+- `error` — boolean error flag
+- `reload()` — forces a re-fetch (error-retry affordance)
+
+### `useSelfFetch<T>(url, options?)`
+Core hook with two optional config values:
+- `options.initialData` — seeds state from SSR-rendered data, skipping the initial fetch
+- `options.revalidateOnVisibleAfterMs` — opt-in tab-visibility revalidation; re-fetches when the held data is older than the given threshold (replaces `setInterval` polling)
+
+## Usage Example
+
+```typescript
+// Basic self-fetch
+const { data, isLoading, error, reload } = useSelfFetch<Product[]>(
+  '/api/products?page=1'
+)
+
+// SSR-hydrated: skips first fetch, re-fetches on url change
+const { data, setData } = useSelfFetch<RoadmapItem[]>(
+  `/api/roadmap?section=${section}`,
+  { initialData: serverData }
+)
+
+// With tab-visibility revalidation (5 minutes)
+const { data } = useSelfFetch<Release[]>(
+  '/api/releases',
+  { revalidateOnVisibleAfterMs: 5 * 60 * 1000 }
+)
+
+// Optimistic update (e.g. upvote)
+setData((prev) => prev ? { ...prev, votes: prev.votes + 1 } : prev)
+```
+
+## Behavior Notes
+
+- **`url = null`** disables fetching entirely (controlled/SSR mode)
+- **Stale-request guard** — an `AbortController` + `cancelled` flag prevents race conditions when `url` changes rapidly (e.g. pagination)
+- **SSR hydration skip** — `dataUrlRef` tracks the URL whose data is currently held; the fetch effect is skipped when it matches, surviving React 18 StrictMode's double-mount in dev
+- **`reload()`** nulls `dataUrlRef` so the same URL can be re-fetched after an error
+
+## Source
+
+[`use-self-fetch.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-self-fetch.ts)

package/src/hooks/state/.flatten-schema.md

@@ -1,43 +1,51 @@
-<!-- source-hash: 35adb97eaacf2c17d09efbd85a569c46 -->
-Provides utilities to flatten nested GraphQL input types into URL parameter mappings for cleaner URL state management. Converts complex nested objects like `{ filter: { severity: [...] } }` into simple URL parameters like `?severity=...`.
+<!-- source-hash: f6f23c54f1dcd6f13c1c04a935fe719d -->
+Utilities for flattening nested GraphQL input type schemas into flat URL parameter mappings, enabling clean URL state management for GraphQL-powered views.
 
 ## Key Components
 
-**Main Functions:**
-- `flattenQueryVariables()` - Core function that flattens GraphQL variables using schema introspection
-- `mergeDefaults()` - Merges default values into the flattened schema
-- `validateSchema()` - Ensures no URL parameter name conflicts exist
-- `getArrayParams()` - Identifies which parameters should use repeated URL values
-- `getRequiredParams()` - Lists required parameters from the schema
-- `shouldIncludeInUrl()` - Determines if a parameter value should be included in the URL
+### Interfaces
 
-**Types:**
-- `FlattenedParam` - Configuration mapping URL parameter names to GraphQL paths with type information
+- **`FlattenedParam`** — Describes a single URL parameter, including its `urlParamName`, `graphqlPath` (e.g., `filter.severity`), `type`, `defaultValue`, `required`, and `isArray` flags.
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `flattenQueryVariables` | Async. Converts nested GraphQL query variables into a flat `Record<string, FlattenedParam>`. Uses introspection to expand input object fields. |
+| `mergeDefaults` | Merges a defaults map into an existing flattened schema, overriding or populating `defaultValue` per param. |
+| `validateSchema` | Throws if any two params resolve to the same `urlParamName` (conflict detection). |
+| `getArrayParams` | Returns keys of all array-typed params; useful for repeated URL value handling (e.g., `?severity=error&severity=warning`). |
+| `getRequiredParams` | Returns keys of all required params. |
+| `shouldIncludeInUrl` | Returns `false` for `null`/`undefined`, empty arrays, empty strings, or values matching `defaultValue`; keeps URLs clean. |
 
 ## Usage Example
 
 ```typescript
-import { flattenQueryVariables, validateSchema } from './flatten-schema'
+import { flattenQueryVariables, mergeDefaults, validateSchema, shouldIncludeInUrl } from './flatten-schema'
 import { GraphQLIntrospector } from './introspection'
 
-// GraphQL query variables
-const queryVars = {
-  search: { type: 'string', required: false },
-  filter: { type: 'object', graphqlTypeName: 'LogFilterInput' },
-  cursor: { type: 'string', required: false }
+const introspector = new GraphQLIntrospector(/* ... */)
+await introspector.load()
+
+const queryVariables = {
+  search: { type: 'string', required: false, isArray: false },
+  filter: { type: 'object', graphqlTypeName: 'LogFilterInput', required: false, isArray: false },
 }
 
-// Flatten to URL parameter schema
-const introspector = new GraphQLIntrospector(schema)
-const flatSchema = await flattenQueryVariables(queryVars, introspector)
+// Flatten: { filter: { severity } } → ?severity=...
+let schema = await flattenQueryVariables(queryVariables, introspector)
+
+// Apply defaults
+schema = mergeDefaults(schema, { severity: ['info'] })
+
+// Validate no URL param name conflicts
+validateSchema(schema)
+
+// Check if a value should be written to the URL
+const include = shouldIncludeInUrl(['critical'], schema.severity) // true
+const skip = shouldIncludeInUrl([], schema.severity)             // false
+```
 
-// Result maps nested filter fields to top-level URL params
-// flatSchema = {
-//   search: { urlParamName: 'search', graphqlPath: 'search', type: 'string' },
-//   severity: { urlParamName: 'severity', graphqlPath: 'filter.severity', type: 'array' },
-//   toolType: { urlParamName: 'toolType', graphqlPath: 'filter.toolType', type: 'array' }
-// }
+## Source
 
-validateSchema(flatSchema) // Ensure no conflicts
-const arrayParams = getArrayParams(flatSchema) // ['severity', 'toolType']
-```
+[`flatten-schema.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/flatten-schema.ts)

package/src/hooks/ui/.index.md

@@ -1,41 +1,53 @@
-<!-- source-hash: fc4a9d5f3d9a97f43016324c6310b828 -->
-Barrel export file that re-exports all UI hooks from the hooks package, providing a single entry point for consuming hook utilities across the application.
+<!-- source-hash: f2ee6838846ee9d01b393ef923facc58 -->
+Barrel export file for the UI hooks library, re-exporting all custom React hooks and the `usePreventScroll` utility from `@react-aria/overlays` under a single import path.
 
 ## Key Components
 
-| Hook | Description |
-|------|-------------|
-| `use-debounce` | Delays value updates until after a specified wait period |
-| `use-local-storage` | Persists and retrieves state from browser local storage |
-| `use-media-query` | Evaluates CSS media queries reactively |
-| `use-memoized-callback` | Memoizes callback functions to prevent unnecessary re-renders |
-| `use-onboarding-state` | Manages onboarding flow state and progress |
-| `use-table-pagination` | Handles pagination logic for data tables |
-| `use-throttle` | Limits function call frequency to a specified interval |
-| `use-window-size` | Tracks browser window dimensions reactively |
-| `use-horizontal-scrollbar` | Detects and manages horizontal scrollbar visibility |
-| `use-image-edge-color` | Extracts dominant edge color from an image |
-| `use-search` | Manages search input state and filtering logic |
-| `use-auto-limit-tags` | Automatically limits visible tags based on available space |
+| Export | Description |
+|---|---|
+| `useAutoLimitTags` | Limits visible tags based on container width |
+| `useDebounce` | Delays value updates by a specified duration |
+| `useDeferredError` | Defers error state for async workflows |
+| `useFocusTrap` | Traps keyboard focus within a DOM subtree |
+| `useHeaderHeight` | Tracks the application header's pixel height |
+| `useHorizontalScrollbar` | Detects and manages horizontal scrollbar presence |
+| `useImageEdgeColor` | Samples the edge color of an image element |
+| `useLocalStorage` | Synced, typed `localStorage` state |
+| `useMarqueeEngine` | Drives text marquee/ticker animations |
+| `useMediaQuery` | Reactive CSS media query matching |
+| `useMemoizedCallback` | Stable callback reference with deep-equality memoization |
+| `useNotificationPermission` | Reads and requests browser notification permission |
+| `useOnboardingState` | Manages multi-step onboarding flow state |
+| `useResetOnPageHidden` | Resets state when the page visibility changes to hidden |
+| `useSearch` | Controlled search input with filtering logic |
+| `useSuppressCloneFocus` | Prevents focus events on cloned DOM nodes |
+| `useTablePagination` | Pagination state and helpers for data tables |
+| `useThrottle` | Throttles rapidly firing values or callbacks |
+| `useWindowSize` | Reactive viewport width and height |
+| `usePreventScroll` | Ref-counted, iOS-aware body scroll lock (`@react-aria/overlays`) |
 
 ## Usage Example
 
 ```typescript
+// Single import path for all hooks
 import {
   useDebounce,
   useLocalStorage,
   useWindowSize,
-  useSearch,
-  useTablePagination,
-} from '@your-package/hooks'
+  usePreventScroll,
+} from '@openframe-oss-lib/hooks'
 
-const MyComponent = () => {
-  const { width, height } = useWindowSize()
+function SearchPanel() {
   const [query, setQuery] = useLocalStorage('search-query', '')
   const debouncedQuery = useDebounce(query, 300)
-  const { results } = useSearch(debouncedQuery, items)
-  const { page, pageSize, onPageChange } = useTablePagination()
+  const { width } = useWindowSize()
 
-  return <Table data={results} page={page} pageSize={pageSize} />
+  usePreventScroll({ isDisabled: width > 768 })
+
+  return <input value={query} onChange={e => setQuery(e.target.value)} />
 }
-```
+```
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/hooks/ui/.use-auto-limit-tags.md

@@ -1,54 +1,71 @@
-<!-- source-hash: 4ddac380d848a0dcab830bec82a667f6 -->
-Calculates how many tags fit within a single-line container using real DOM measurements, supporting both a fixed numeric limit and an automatic layout-aware mode.
+<!-- source-hash: 3512572c1b5ae0dfa77abc80ec31167a -->
+Calculates how many tag chips fit in a single-line container using real DOM measurements, supporting both fixed and automatic (`"auto"`) limits with `ResizeObserver`-driven updates.
 
 ## Key Components
 
 ### `useAutoLimitTags(options)`
-Main hook that returns layout refs and the computed `visibleCount`.
+Main hook that returns refs and a `visibleCount` to drive tag overflow rendering.
+
+**Options (`UseAutoLimitTagsOptions`):**
 
-**Options**
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `count` | `number` | — | Total number of tags |
-| `limitTags` | `number \| "auto"` | `"auto"` | Fixed cap or DOM-measured auto mode |
-| `placeholder` | `string` | `""` | Input placeholder used to reserve width |
+| `limitTags` | `number \| "auto"` | `"auto"` | Fixed limit or DOM-based measurement |
+| `placeholder` | `string` | `""` | Input placeholder used to reserve input width |
+| `reserveInputWidth` | `boolean` | `true` | Reserve trailing space for a combobox input |
+
+**Returns (`UseAutoLimitTagsReturn`):**
 
-**Returns (`UseAutoLimitTagsReturn`)**
-| Ref | Element | Purpose |
+| Ref / Value | Attach to | Purpose |
 |---|---|---|
-| `middleRef` | `HTMLDivElement` | Container with tags + input (reads padding/gap from here) |
-| `measureRef` | `HTMLDivElement` | Off-screen container holding copies of all tags |
-| `textMeasureRef` | `HTMLSpanElement` | Hidden span measuring placeholder text width |
-| `badgeRef` | `HTMLButtonElement` | The `+N` overflow badge (measures its width) |
-| `inputRef` | `HTMLInputElement` | The text input (reads its `min-width`) |
-| `visibleCount` | `number` | How many tags to render visibly |
+| `visibleCount` | — | Number of tags to render visibly |
+| `middleRef` | `<div>` (tag + input zone) | Source of CSS metrics (padding, gap, width) |
+| `measureRef` | `<div>` (off-screen) | Holds hidden copies of all tags for width measurement |
+| `textMeasureRef` | `<span>` (off-screen) | Measures placeholder text width |
+| `badgeRef` | `<button>` (+N badge) | Measures overflow badge width |
+| `inputRef` | `<input>` | Reads `min-width` for input reservation |
 
 ## Usage Example
 
 ```typescript
-const { visibleCount, middleRef, measureRef, textMeasureRef, badgeRef, inputRef } =
-  useAutoLimitTags({ count: tags.length, placeholder: "Search..." })
-
-return (
-  <>
-    {/* Off-screen measurement container */}
-    <div ref={measureRef} style={{ position: "absolute", visibility: "hidden" }}>
-      {tags.map((tag) => <TagChip key={tag.id} tag={tag} />)}
-    </div>
-    <span ref={textMeasureRef} style={{ visibility: "hidden", position: "absolute" }}>
-      Search...
-    </span>
-
-    {/* Visible tag zone */}
-    <div ref={middleRef} className="flex overflow-hidden gap-1 px-2">
-      {tags.slice(0, visibleCount).map((tag) => <TagChip key={tag.id} tag={tag} />)}
-      {visibleCount < tags.length && (
-        <button ref={badgeRef}>+{tags.length - visibleCount}</button>
-      )}
-      <input ref={inputRef} placeholder="Search..." />
-    </div>
-  </>
-)
+import { useAutoLimitTags } from "./use-auto-limit-tags"
+
+function TagRow({ tags }: { tags: string[] }) {
+  const {
+    visibleCount,
+    middleRef,
+    measureRef,
+    textMeasureRef,
+    badgeRef,
+    inputRef,
+  } = useAutoLimitTags({ count: tags.length, placeholder: "Search..." })
+
+  const overflowCount = tags.length - visibleCount
+
+  return (
+    <>
+      {/* Visible tag zone */}
+      <div ref={middleRef} style={{ overflow: "hidden", display: "flex", gap: 8 }}>
+        {tags.slice(0, visibleCount).map((tag) => (
+          <span key={tag}>{tag}</span>
+        ))}
+        {overflowCount > 0 && (
+          <button ref={badgeRef}>+{overflowCount}</button>
+        )}
+        <input ref={inputRef} placeholder="Search..." />
+      </div>
+
+      {/* Off-screen measurement elements */}
+      <div ref={measureRef} style={{ visibility: "hidden", position: "absolute" }}>
+        {tags.map((tag) => <span key={tag}>{tag}</span>)}
+      </div>
+      <span ref={textMeasureRef} style={{ visibility: "hidden", position: "absolute" }}>
+        Search...
+      </span>
+    </>
+  )
+}
 ```
 
-> **Note:** `middleRef` must have `overflow-hidden`, explicit `gap`, and `padding` set via CSS — the hook reads these values directly with `getComputedStyle` and uses a `ResizeObserver` to recalculate on container width changes.
+> **Note:** The `measureRef` container must render a hidden copy of **all** tags off-screen so the hook can measure each chip's true rendered width regardless of which tags are currently visible.

package/src/hooks/ui/.use-deferred-error.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 470d7db06c3aaa133ca4e063375a0c98 -->
+Manages the timing of when field-level validation error messages are displayed, deferring visibility until the user has stopped typing or left the field.
+
+## Key Components
+
+### `UseDeferredErrorResult`
+Interface describing the hook's return value:
+- `error` — The validation message to render, or `undefined` when suppressed (user is still typing) or the field is valid
+- `onBlur` — Callback to attach to the field's `onBlur` event; immediately reveals the error and keeps validation live going forward
+
+### `useDeferredError(error, value, delay?)`
+Hook that controls error reveal timing with two trigger paths:
+- **Blur/touch** — Revealing immediately when the field loses focus (`onBlur`), and remaining live thereafter
+- **Idle timer** — Revealing after `delay` ms (default `1500`) of no value changes; every keystroke resets the countdown
+
+Once a field is touched, the error stays reactive. If the error clears (field becomes valid), it disappears immediately regardless of touch/pause state.
+
+## Usage Example
+
+```typescript
+import { useDeferredError } from './use-deferred-error'
+
+function EmailField({ value, onChange, validationError }) {
+  const { error, onBlur } = useDeferredError(validationError, value)
+
+  return (
+    <div>
+      <input
+        type="email"
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+      />
+      {error && <span className="error">{error}</span>}
+    </div>
+  )
+}
+```
+
+To use a custom delay (e.g. 800 ms for faster feedback):
+
+```typescript
+const { error, onBlur } = useDeferredError(validationError, value, 800)
+```