hazo_ui 6.0.0 → 6.3.0

package/CHANGE_LOG.md

@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v6.3.0 (2026-07-21)
+
+### New
+- feat: add `useLongPress()` (touch-only long-press hook) — ported as-is
+  from Kinstripe's `src/lib/hooks/useLongPress.ts` (already fully generic;
+  no app coupling to remove). Every returned handler
+  (`onPointerDown`/`onPointerMove`/`onPointerUp`/`onPointerCancel`/`onClick`)
+  is a no-op on fine-pointer (mouse) devices — desktop should keep using
+  `onContextMenu` for right-click. Cancels on movement past
+  `moveThresholdPx`, early `pointerup`, a second `pointerdown`
+  (multi-touch), or `pointercancel`.
+- feat: add `announce()` + `<LiveRegion>` — a screen-reader announcement
+  bus (a `window` CustomEvent dispatched by `announce()`, consumed by a
+  mounted `<LiveRegion>`), generalised from Kinstripe's `announce.ts` +
+  `KsLiveRegion`. Both the hardcoded event name (`"kinstripe:announce"`)
+  and the sr-only class name (`"kn-sr-only"`) are now configurable:
+  `announce(message, priority, { eventName })` and
+  `<LiveRegion eventName className clearAfterMs />`, defaulting to
+  `DEFAULT_ANNOUNCE_EVENT` and Tailwind's built-in `"sr-only"` utility so
+  it works out of the box. Keeps the two-region (polite/assertive) design,
+  the default 6s self-clear, and the duplicate-text re-announce trick.
+  `announce()` is also exported from the server-safe `hazo_ui/utils`
+  subpath (same dual-export pattern as `cn`).
+- feat: add `useScrollRestore()` — localStorage-backed scroll-position
+  save/load, generalised from Kinstripe's `useScrollRestore`. Keeps the
+  same `(treeId, viewName)` positional signature; the previously-hardcoded
+  `"kinstripe.scrollPos"` key prefix is now an optional third argument
+  (`{ prefix }`, default `DEFAULT_SCROLL_RESTORE_PREFIX`). The underlying
+  pure helpers (`buildScrollRestoreKey`, `saveScrollPos`, `loadScrollPos`)
+  are split into `lib/scroll_restore.ts` (same hook/lib split as
+  `useRememberedState`/`remembered_state.ts`) and also exported from
+  `hazo_ui/utils`.
+- Demo pages added under `test-app/app/{long-press,live-region,scroll-restore}/`,
+  new "Ported utilities (v6.3)" sidebar section, and five new
+  `hazo_ui/test-harness` scenarios (`use_long_press`, `announce_dispatch`,
+  `live_region_round_trip`, `scroll_restore_helpers`,
+  `use_scroll_restore_hook`) registered in
+  `test-app/app/harness-self-test/hazo_ui_utility_ports_scenarios.ts` — the
+  pointer/DOM-driven ones mount a real React tree via `react-dom/client`
+  against the test-app's live browser DOM rather than settling for an
+  export-shape check.
+
+## v6.2.0 (2026-07-21)
+
+### New
+- feat: add `useRememberedState<T>()` hook (FR-020) — a generic
+  localStorage-backed "remember last-used state across visits" hook:
+  restore-once-on-mount (ref-guarded, immune to `restore` identity churn),
+  a debounced write (`debounceMs`, default `600`), and an optional
+  `skipWhenUrlParam` escape hatch so an explicit shared-link/saved-record
+  query param always wins over remembered state. Generalised from
+  stocktools's app-local `useToolMemory` — the caller now supplies the full
+  storage `key` and generic `snapshot`/`restore` callbacks instead of a
+  hardcoded key prefix and `Seed`-typed shape.
+- feat: add pure helpers `readRememberedState`, `writeRememberedState`,
+  `hasUrlParam` backing the hook — SSR-safe, JSON-parse/stringify with
+  corrupt-data tolerance, framework-free. Exported from **both** the main
+  `hazo_ui` barrel and the server-safe `hazo_ui/utils` subpath (same
+  dual-export pattern as `cn`), so Server Components can read/write
+  remembered state without pulling in the `"use client"` bundle.
+- Demo page added to `test-app/app/remembered-state/` under the new
+  "Remembered state (v6.2)" sidebar section.
+
+## v6.1.0 (2026-07-17)
+
+### New
+- feat: add `permissionToast` helper (FR-017) — an opinionated wrapper around
+  `errorToast` that standardizes permission-failure toasts (fixed "Permission
+  required" title, composed missing-permission description, optional action
+  button). Exported alongside `PermissionToastOptions` from `hazo_ui`.
+
 ## v6.0.0 (2026-07-11)
 
 Major — the P1 hazo_theme rehome. hazo_ui stops owning theme tokens, preset, and provider;

package/README.md

@@ -226,7 +226,7 @@ Lightweight, opinionated components for the four ubiquitous async states: **load
 - **[ErrorPage](#errorpage)** - Full-page error fallback with title, description, error code tag, correlation id, and CTAs.
 - **[LoadingTimeout](#loadingtimeout)** - Wraps a loading region and escalates messaging at 5s / 15s / 30s thresholds before showing a retry banner.
 - **[ProgressiveImage](#progressiveimage)** - Three-stage image render: grey placeholder → blurred LQIP → sharp final image.
-- **[HazoUiToaster + toast helpers](#toasts-hazouitoaster--successtoast--errortoast)** - `sonner`-backed toaster with `successToast()` and `errorToast()` imperative helpers.
+- **[HazoUiToaster + toast helpers](#toasts-hazouitoaster--successtoast--errortoast)** - `sonner`-backed toaster with `successToast()`, `errorToast()`, and `permissionToast()` imperative helpers.
 - **[useLoadingState](#useloadingstate)** hook - `{ isLoading, setLoading, withLoading }` with an async wrapper.
 - **[useErrorDisplay](#useerrordisplay)** hook - Passive `{ error, setError, clearError }` that coerces `Error` instances to strings.
 
@@ -3443,6 +3443,29 @@ try { await sync(); } catch (e) {
 | `duration` | `number` (ms) | `3000` success / `5000` error |
 | `action` | `{ label: string; onClick: () => void }` | — |
 
+**`permissionToast(opts: PermissionToastOptions)`** — an opinionated wrapper around
+`errorToast` for permission-failure UX. Always titles the toast `"Permission required"`
+and composes a description from the missing permission key(s) (and optional human
+descriptions), so every "you can't do that" moment in the app reads consistently:
+
+```tsx
+import { permissionToast } from "hazo_ui";
+
+permissionToast({
+  missingPermissions: ["env.migrate"],
+  descriptions: { "env.migrate": "Migrate environments" },
+  action: { label: "Request access", onClick: () => requestAccess() },
+});
+// → "Permission required" / "Missing: `env.migrate` — Migrate environments"
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `missingPermissions` | `string[]` | **required** |
+| `descriptions` | `Record<string, string>` | — |
+| `action` | `{ label: string; onClick: () => void }` | — |
+| `duration` | `number` (ms) | `5000` |
+
 Also exports `rawToast` (re-export of sonner's `toast`) for advanced use cases.
 
 ### useWakeLock / use_wake_lock

package/dist/announce-DAnQDTld.d.cts

@@ -0,0 +1,92 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merges class names using clsx and tailwind-merge
+ * @param inputs - Class values to merge
+ * @returns Merged class string
+ */
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent
+ * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an
+ * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but
+ * not protocol-relative `//…`). Returns `undefined` for anything else, so the
+ * anchor renders with no href rather than an active malicious one.
+ * @param url - Candidate href (may be undefined)
+ * @returns The original url if allowed, otherwise undefined
+ */
+declare function safeHref(url?: string): string | undefined;
+
+/**
+ * Reads and JSON-parses the remembered value stored under `key`. SSR-safe —
+ * returns `null` on the server, when nothing is stored, or when the stored
+ * value is corrupt/unparsable.
+ *
+ * @param key - localStorage key to read.
+ *
+ * @example
+ *   const seed = readRememberedState<MySeed>("myapp:tool:cgt");
+ */
+declare function readRememberedState<T>(key: string): T | null;
+/**
+ * JSON-stringifies and writes `snapshot` under `key`. SSR-safe — no-ops on
+ * the server. Quota / private-mode errors are swallowed; losing a memory
+ * write is non-fatal.
+ *
+ * @param key      - localStorage key to write.
+ * @param snapshot - Serialisable value to remember.
+ *
+ * @example
+ *   writeRememberedState("myapp:tool:cgt", { proceeds: 1000 });
+ */
+declare function writeRememberedState<T>(key: string, snapshot: T): void;
+/**
+ * True when `paramName` is present in the given search string (e.g.
+ * `window.location.search`). Generic form of the "an explicit shared-link /
+ * saved-record query param always wins over remembered state" precedence
+ * check — callers supply the param name (e.g. `"restore"`); this module
+ * never hardcodes one.
+ *
+ * @param search    - A URL search string, e.g. `window.location.search`.
+ * @param paramName - The query param to look for.
+ *
+ * @example
+ *   hasUrlParam("?restore=abc123", "restore"); // true
+ */
+declare function hasUrlParam(search: string, paramName: string): boolean;
+
+type AnnouncePriority = "polite" | "assertive";
+interface LiveAnnouncement {
+    message: string;
+    priority: AnnouncePriority;
+}
+interface AnnounceOptions {
+    /** Custom-event name the paired `LiveRegion` listens on. Must match the `eventName` it was mounted with. Default `DEFAULT_ANNOUNCE_EVENT`. */
+    eventName?: string;
+}
+/** Default `window` CustomEvent name used when `announce()` / `LiveRegion` are not given an explicit `eventName`. */
+declare const DEFAULT_ANNOUNCE_EVENT = "hazo_ui:announce";
+/**
+ * Dispatch a screen-reader announcement via a `window` CustomEvent. Safe to
+ * call from anywhere in the client tree — no-ops during SSR or before a
+ * `LiveRegion` has mounted (fire-and-forget; there's no queue/replay).
+ *
+ * Use `"polite"` (default) for ambient updates ("Sarah joined the canvas",
+ * "2 new notifications"). Use `"assertive"` only for things the user must
+ * hear immediately (errors that interrupt a task).
+ *
+ * @param message  - Text to announce. Empty / whitespace-only messages are dropped (no dispatch).
+ * @param priority - `"polite"` (default) or `"assertive"`.
+ * @param options.eventName - Custom-event name to dispatch on. Default `DEFAULT_ANNOUNCE_EVENT`.
+ *
+ * @example
+ *   announce("2 new notifications");
+ *   announce("Save failed — check your connection", "assertive");
+ *
+ * @example
+ *   // namespaced channel — must match the eventName the LiveRegion was mounted with
+ *   announce("Saved", "polite", { eventName: "myapp:announce" });
+ */
+declare function announce(message: string, priority?: AnnouncePriority, options?: AnnounceOptions): void;
+
+export { type AnnounceOptions as A, DEFAULT_ANNOUNCE_EVENT as D, type LiveAnnouncement as L, type AnnouncePriority as a, announce as b, cn as c, hasUrlParam as h, readRememberedState as r, safeHref as s, writeRememberedState as w };

package/dist/announce-DAnQDTld.d.ts

@@ -0,0 +1,92 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Merges class names using clsx and tailwind-merge
+ * @param inputs - Class values to merge
+ * @returns Merged class string
+ */
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Sanitizes a user/admin-supplied href against a scheme allowlist to prevent
+ * `javascript:`/`data:`/`vbscript:` URI XSS when the value is rendered into an
+ * `<a href>`. Allows http(s), mailto, and same-origin absolute paths (`/…` but
+ * not protocol-relative `//…`). Returns `undefined` for anything else, so the
+ * anchor renders with no href rather than an active malicious one.
+ * @param url - Candidate href (may be undefined)
+ * @returns The original url if allowed, otherwise undefined
+ */
+declare function safeHref(url?: string): string | undefined;
+
+/**
+ * Reads and JSON-parses the remembered value stored under `key`. SSR-safe —
+ * returns `null` on the server, when nothing is stored, or when the stored
+ * value is corrupt/unparsable.
+ *
+ * @param key - localStorage key to read.
+ *
+ * @example
+ *   const seed = readRememberedState<MySeed>("myapp:tool:cgt");
+ */
+declare function readRememberedState<T>(key: string): T | null;
+/**
+ * JSON-stringifies and writes `snapshot` under `key`. SSR-safe — no-ops on
+ * the server. Quota / private-mode errors are swallowed; losing a memory
+ * write is non-fatal.
+ *
+ * @param key      - localStorage key to write.
+ * @param snapshot - Serialisable value to remember.
+ *
+ * @example
+ *   writeRememberedState("myapp:tool:cgt", { proceeds: 1000 });
+ */
+declare function writeRememberedState<T>(key: string, snapshot: T): void;
+/**
+ * True when `paramName` is present in the given search string (e.g.
+ * `window.location.search`). Generic form of the "an explicit shared-link /
+ * saved-record query param always wins over remembered state" precedence
+ * check — callers supply the param name (e.g. `"restore"`); this module
+ * never hardcodes one.
+ *
+ * @param search    - A URL search string, e.g. `window.location.search`.
+ * @param paramName - The query param to look for.
+ *
+ * @example
+ *   hasUrlParam("?restore=abc123", "restore"); // true
+ */
+declare function hasUrlParam(search: string, paramName: string): boolean;
+
+type AnnouncePriority = "polite" | "assertive";
+interface LiveAnnouncement {
+    message: string;
+    priority: AnnouncePriority;
+}
+interface AnnounceOptions {
+    /** Custom-event name the paired `LiveRegion` listens on. Must match the `eventName` it was mounted with. Default `DEFAULT_ANNOUNCE_EVENT`. */
+    eventName?: string;
+}
+/** Default `window` CustomEvent name used when `announce()` / `LiveRegion` are not given an explicit `eventName`. */
+declare const DEFAULT_ANNOUNCE_EVENT = "hazo_ui:announce";
+/**
+ * Dispatch a screen-reader announcement via a `window` CustomEvent. Safe to
+ * call from anywhere in the client tree — no-ops during SSR or before a
+ * `LiveRegion` has mounted (fire-and-forget; there's no queue/replay).
+ *
+ * Use `"polite"` (default) for ambient updates ("Sarah joined the canvas",
+ * "2 new notifications"). Use `"assertive"` only for things the user must
+ * hear immediately (errors that interrupt a task).
+ *
+ * @param message  - Text to announce. Empty / whitespace-only messages are dropped (no dispatch).
+ * @param priority - `"polite"` (default) or `"assertive"`.
+ * @param options.eventName - Custom-event name to dispatch on. Default `DEFAULT_ANNOUNCE_EVENT`.
+ *
+ * @example
+ *   announce("2 new notifications");
+ *   announce("Save failed — check your connection", "assertive");
+ *
+ * @example
+ *   // namespaced channel — must match the eventName the LiveRegion was mounted with
+ *   announce("Saved", "polite", { eventName: "myapp:announce" });
+ */
+declare function announce(message: string, priority?: AnnouncePriority, options?: AnnounceOptions): void;
+
+export { type AnnounceOptions as A, DEFAULT_ANNOUNCE_EVENT as D, type LiveAnnouncement as L, type AnnouncePriority as a, announce as b, cn as c, hasUrlParam as h, readRememberedState as r, safeHref as s, writeRememberedState as w };

package/dist/index.cjs

@@ -8819,6 +8819,23 @@ function errorToast({ title, description, duration = 5e3, action }) {
     action: action ? { label: action.label, onClick: action.onClick } : void 0
   });
 }
+function permissionToast({
+  missingPermissions,
+  descriptions,
+  action,
+  duration = 5e3
+}) {
+  const description = missingPermissions.length === 0 ? "You do not have permission to perform this action." : `Missing: ${missingPermissions.map((key) => {
+    const label = descriptions?.[key];
+    return label ? `\`${key}\` \u2014 ${label}` : `\`${key}\``;
+  }).join("; ")}`;
+  return errorToast({
+    title: "Permission required",
+    description,
+    action,
+    duration
+  });
+}
 function useLoadingState(initial = false) {
   const [isLoading, setLoading] = React27.useState(initial);
   const withLoading = React27.useCallback(async (fn) => {
@@ -11927,6 +11944,253 @@ function AppFooter({ variant, footer, identity, className }) {
   );
 }
 
+// src/lib/remembered_state.ts
+function readRememberedState(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function writeRememberedState(key, snapshot) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, JSON.stringify(snapshot));
+  } catch {
+  }
+}
+function hasUrlParam(search, paramName) {
+  try {
+    return new URLSearchParams(search).has(paramName);
+  } catch {
+    return false;
+  }
+}
+
+// src/hooks/use_remembered_state.ts
+function useRememberedState({
+  key,
+  snapshot,
+  restore,
+  enabled = true,
+  debounceMs = 600,
+  skipWhenUrlParam
+}) {
+  const restoreRef = React27.useRef(restore);
+  React27.useEffect(() => {
+    restoreRef.current = restore;
+  });
+  const didRestore = React27.useRef(false);
+  React27.useEffect(() => {
+    if (didRestore.current) return;
+    didRestore.current = true;
+    if (!enabled) return;
+    if (typeof window === "undefined") return;
+    if (skipWhenUrlParam && hasUrlParam(window.location.search, skipWhenUrlParam)) return;
+    const remembered = readRememberedState(key);
+    if (remembered === null) return;
+    try {
+      restoreRef.current(remembered);
+    } catch {
+    }
+  }, [key, enabled, skipWhenUrlParam]);
+  const snapshotJson = JSON.stringify(snapshot);
+  const writeTimer = React27.useRef(null);
+  React27.useEffect(() => {
+    if (!enabled) return;
+    if (writeTimer.current) clearTimeout(writeTimer.current);
+    writeTimer.current = setTimeout(() => {
+      writeRememberedState(key, snapshot);
+    }, debounceMs);
+    return () => {
+      if (writeTimer.current) clearTimeout(writeTimer.current);
+    };
+  }, [key, snapshotJson, enabled, debounceMs]);
+}
+var COARSE_QUERY = "(pointer: coarse)";
+function subscribe_coarse(notify) {
+  if (typeof window === "undefined") return () => {
+  };
+  const mql = window.matchMedia(COARSE_QUERY);
+  mql.addEventListener("change", notify);
+  return () => mql.removeEventListener("change", notify);
+}
+function get_coarse_snapshot() {
+  return window.matchMedia(COARSE_QUERY).matches;
+}
+function get_coarse_server_snapshot() {
+  return false;
+}
+function useLongPress({
+  onLongPress,
+  delayMs = 500,
+  moveThresholdPx = 8,
+  hapticMs = 10
+}) {
+  const isCoarse = React27.useSyncExternalStore(
+    subscribe_coarse,
+    get_coarse_snapshot,
+    get_coarse_server_snapshot
+  );
+  const timerRef = React27.useRef(null);
+  const originRef = React27.useRef(null);
+  const firedRef = React27.useRef(false);
+  const eventRef = React27.useRef(null);
+  const cancel = React27.useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    originRef.current = null;
+    eventRef.current = null;
+  }, []);
+  React27.useEffect(() => () => cancel(), [cancel]);
+  const noop = React27.useCallback(() => {
+  }, []);
+  const handlePointerDown = React27.useCallback(
+    (e) => {
+      if (originRef.current && originRef.current.pointerId !== e.pointerId) {
+        cancel();
+        return;
+      }
+      firedRef.current = false;
+      originRef.current = { x: e.clientX, y: e.clientY, pointerId: e.pointerId };
+      eventRef.current = e;
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        firedRef.current = true;
+        if (hapticMs > 0 && typeof navigator !== "undefined" && "vibrate" in navigator) {
+          try {
+            navigator.vibrate?.(hapticMs);
+          } catch {
+          }
+        }
+        const evt = eventRef.current;
+        if (evt) onLongPress(evt);
+      }, delayMs);
+    },
+    [delayMs, hapticMs, cancel, onLongPress]
+  );
+  const handlePointerMove = React27.useCallback(
+    (e) => {
+      if (!originRef.current) return;
+      const dx = e.clientX - originRef.current.x;
+      const dy = e.clientY - originRef.current.y;
+      if (Math.hypot(dx, dy) > moveThresholdPx) cancel();
+    },
+    [moveThresholdPx, cancel]
+  );
+  const handlePointerUpOrCancel = React27.useCallback(() => {
+    cancel();
+  }, [cancel]);
+  const handleClick = React27.useCallback((e) => {
+    if (firedRef.current) {
+      e.preventDefault();
+      e.stopPropagation();
+      firedRef.current = false;
+    }
+  }, []);
+  if (!isCoarse) {
+    return {
+      onPointerDown: noop,
+      onPointerMove: noop,
+      onPointerUp: noop,
+      onPointerCancel: noop,
+      onClick: noop
+    };
+  }
+  return {
+    onPointerDown: handlePointerDown,
+    onPointerMove: handlePointerMove,
+    onPointerUp: handlePointerUpOrCancel,
+    onPointerCancel: handlePointerUpOrCancel,
+    onClick: handleClick
+  };
+}
+
+// src/lib/announce.ts
+var DEFAULT_ANNOUNCE_EVENT = "hazo_ui:announce";
+function announce(message, priority = "polite", options) {
+  if (typeof window === "undefined") return;
+  const trimmed = message.trim();
+  if (!trimmed) return;
+  const eventName = options?.eventName ?? DEFAULT_ANNOUNCE_EVENT;
+  window.dispatchEvent(
+    new CustomEvent(eventName, {
+      detail: { message: trimmed, priority }
+    })
+  );
+}
+function LiveRegion({
+  eventName = DEFAULT_ANNOUNCE_EVENT,
+  className = "sr-only",
+  clearAfterMs = 6e3
+}) {
+  const [polite, set_polite] = React27.useState("");
+  const [assertive, set_assertive] = React27.useState("");
+  const polite_timer = React27.useRef(null);
+  const assertive_timer = React27.useRef(null);
+  React27.useEffect(() => {
+    const handler = (e) => {
+      const detail = e.detail;
+      if (!detail?.message) return;
+      if (detail.priority === "assertive") {
+        if (assertive_timer.current) clearTimeout(assertive_timer.current);
+        set_assertive((prev) => prev === detail.message ? `${detail.message} ` : detail.message);
+        assertive_timer.current = setTimeout(() => set_assertive(""), clearAfterMs);
+      } else {
+        if (polite_timer.current) clearTimeout(polite_timer.current);
+        set_polite((prev) => prev === detail.message ? `${detail.message} ` : detail.message);
+        polite_timer.current = setTimeout(() => set_polite(""), clearAfterMs);
+      }
+    };
+    window.addEventListener(eventName, handler);
+    return () => {
+      window.removeEventListener(eventName, handler);
+      if (polite_timer.current) clearTimeout(polite_timer.current);
+      if (assertive_timer.current) clearTimeout(assertive_timer.current);
+    };
+  }, [eventName, clearAfterMs]);
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className, children: polite }),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { role: "alert", "aria-live": "assertive", "aria-atomic": "true", className, children: assertive })
+  ] });
+}
+
+// src/lib/scroll_restore.ts
+var DEFAULT_SCROLL_RESTORE_PREFIX = "hazo_ui:scrollPos";
+function buildScrollRestoreKey(prefix, treeId, viewName) {
+  return `${prefix}.${treeId}.${viewName}`;
+}
+function saveScrollPos(key, scrollY) {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(key, String(Math.round(scrollY)));
+  } catch {
+  }
+}
+function loadScrollPos(key) {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(key);
+    if (!raw) return null;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/hooks/use_scroll_restore.ts
+function useScrollRestore(treeId, viewName, options) {
+  const key = buildScrollRestoreKey(options?.prefix ?? DEFAULT_SCROLL_RESTORE_PREFIX, treeId, viewName);
+  const save = React27.useCallback((scrollY) => saveScrollPos(key, scrollY), [key]);
+  const load = React27.useCallback(() => loadScrollPos(key), [key]);
+  return { save, load };
+}
+
 Object.defineProperty(exports, "rawToast", {
   enumerable: true,
   get: function () { return sonner.toast; }
@@ -11990,6 +12254,7 @@ exports.CollapsibleTrigger = CollapsibleTrigger2;
 exports.CommandNodeExtension = CommandNodeExtension;
 exports.CommandPill = CommandPill;
 exports.CommandPopover = CommandPopover;
+exports.DEFAULT_ANNOUNCE_EVENT = DEFAULT_ANNOUNCE_EVENT;
 exports.DateRangeSelector = DateRangeSelector;
 exports.Drawer = Drawer;
 exports.DrawerClose = DrawerClose;
@@ -12059,6 +12324,7 @@ exports.Input = Input;
 exports.InputAffix = InputAffix;
 exports.InverseSparkline = InverseSparkline;
 exports.Label = Label3;
+exports.LiveRegion = LiveRegion;
 exports.LoadingTimeout = LoadingTimeout;
 exports.Logo = Logo;
 exports.MarkdownEditor = MarkdownEditor;
@@ -12120,6 +12386,7 @@ exports.Tooltip = Tooltip;
 exports.TooltipContent = TooltipContent;
 exports.TooltipProvider = TooltipProvider;
 exports.TooltipTrigger = TooltipTrigger;
+exports.announce = announce;
 exports.applyKanbanFilter = applyKanbanFilter;
 exports.buttonGroupVariants = buttonGroupVariants;
 exports.celebrate = celebrate;
@@ -12132,10 +12399,13 @@ exports.format_num = format_num;
 exports.generateUUID = generateUUID;
 exports.get_hazo_ui_config = get_hazo_ui_config;
 exports.get_logger = get_logger;
+exports.hasUrlParam = hasUrlParam;
 exports.isLucideValue = isLucideValue;
 exports.median = median;
 exports.parse_commands_from_text = parse_commands_from_text;
+exports.permissionToast = permissionToast;
 exports.pick_x_label_indices = pick_x_label_indices;
+exports.readRememberedState = readRememberedState;
 exports.reset_hazo_ui_config = reset_hazo_ui_config;
 exports.resolve_animation_classes = resolve_animation_classes;
 exports.safeHref = safeHref;
@@ -12154,11 +12424,15 @@ exports.useFullscreen = useFullscreen;
 exports.useIsMobile = useIsMobile;
 exports.useLoadingState = useLoadingState;
 exports.useLocalStorage = useLocalStorage;
+exports.useLongPress = useLongPress;
 exports.useMediaQuery = useMediaQuery;
+exports.useRememberedState = useRememberedState;
+exports.useScrollRestore = useScrollRestore;
 exports.useSessionStorage = useSessionStorage;
 exports.useViewport = useViewport;
 exports.useWakeLock = useWakeLock;
 exports.use_fullscreen = use_fullscreen;
 exports.use_wake_lock = use_wake_lock;
+exports.writeRememberedState = writeRememberedState;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map