@spree/dashboard-core 0.1.0

package/src/lib/form-errors.ts

@@ -0,0 +1,103 @@
+import { SpreeError } from '@spree/admin-sdk'
+import type { FieldValues, Path, UseFormSetError } from 'react-hook-form'
+
+/**
+ * Map a thrown error from a Spree Admin API mutation onto a react-hook-form
+ * instance. Two things happen on every call:
+ *
+ * 1. The server's top-level `error.message` (e.g. "Code can't be blank, Name
+ *    can't be blank") is set on `formState.errors.root` so `<FormError>`
+ *    always renders the full failure summary — even when individual fields
+ *    aren't rendered (nested rules, useFieldArray rows, validations on
+ *    associations).
+ * 2. Per-key entries from `error.details` are also set as per-field errors
+ *    for any key that names a top-level flat attribute (`code`, `name`,
+ *    `expires_at`). Nested or dotted keys (`promotion_rules.base`, `rules`
+ *    on a useFieldArray, `line_items.0.quantity`) only contribute to the
+ *    root summary — we don't pretend to know which of those have rendered
+ *    inputs, and "silent" is the worst outcome.
+ *
+ * Return value:
+ *   - `true`  → the error was rendered into the form, the caller may suppress
+ *               its toast
+ *   - `false` → not a SpreeError (network / programming bug). Caller should
+ *               log + toast as usual.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const create = useCreateThing()
+ *
+ * async function onSubmit(values: FormValues) {
+ *   try {
+ *     await create.mutateAsync(values)
+ *     onSuccess()
+ *   } catch (err) {
+ *     if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ *   }
+ * }
+ * ```
+ *
+ * Server response shape (from `Spree::Api::V3::ErrorHandler#render_validation_error`):
+ *
+ * ```json
+ * { "error": {
+ *     "code": "validation_error",
+ *     "message": "Code can't be blank, Name can't be blank",
+ *     "details": { "code": ["can't be blank"], "name": ["can't be blank"] }
+ * } }
+ * ```
+ *
+ * `details` keys are AR attribute names. `<form-field>.base` is AR's
+ * record-level errors collection on a nested association — we treat both
+ * the bare `base` key and any `*.base` key as record-level and route them
+ * to root.
+ */
+export function mapSpreeErrorsToForm<TFieldValues extends FieldValues>(
+  error: unknown,
+  setError: UseFormSetError<TFieldValues>,
+): boolean {
+  if (!(error instanceof SpreeError)) return false
+
+  const { details, message } = error
+
+  // Always seed the root error with the server's top-level message. Even
+  // when details exist, the top-level message is the readable summary —
+  // and it's the only place nested/association errors will reliably show.
+  if (message) {
+    setError('root' as Path<TFieldValues>, { type: 'server', message })
+  }
+
+  if (!details) return true
+
+  // Per-field errors. Each detail value is `string[]` (one Rails error per
+  // entry). Only top-level flat keys get set as per-field errors; nested
+  // keys (`promotion_rules.base`, `rules`, `line_items.0.x`) stay on root.
+  //
+  // We're conservative on purpose: there's no way to know at this layer
+  // whether a given path has a rendered input, so anything that smells
+  // nested or associative falls back to the root summary that we already
+  // set above. Silently dropping errors onto unrendered field paths is a
+  // worse failure mode than redundant root messages.
+  for (const [field, messages] of Object.entries(details)) {
+    if (!messages?.length) continue
+    if (!isRenderableFieldKey(field)) continue
+
+    setError(field as Path<TFieldValues>, {
+      type: 'server',
+      message: messages.join(', '),
+    })
+  }
+
+  return true
+}
+
+// `base` (bare) and `*.base` are AR's record-level errors. `*.<n>.*` is an
+// association/collection index path. Anything with `.` is too risky to set
+// as a top-level RHF path — it'd either create a phantom nested error or
+// silently miss a rendered field. Stick to flat snake_case keys.
+function isRenderableFieldKey(key: string): boolean {
+  if (key === 'base') return false
+  if (key.includes('.')) return false
+  return true
+}

package/src/lib/form-fields-registry.ts

@@ -0,0 +1,102 @@
+// Extension form fields — let host-app code and plugins add fields to a
+// built-in resource form (product, category, …) that hydrate from the fetched
+// resource and persist through the form's own Save. The host form spreads its
+// values into the update payload, so a registered field's value reaches the
+// API without any save code on the extension side; the backend only needs to
+// permit the attribute.
+//
+// The registry solves the hydration half: built-in forms reset their values
+// from a mapper over the fetched resource (which knows nothing about
+// extension fields), so each form merges `extensionFormValues(formKey,
+// resource)` into every defaultValues/reset object. The rendering half is a
+// slot widget binding an input via `useHostForm()`.
+
+/** One extension field on a built-in resource form. */
+export interface FormFieldRegistration<TResource = unknown> {
+  /**
+   * The form value key — also the API attribute name submitted on save
+   * (read/write symmetry: whatever the serializer exposes is what the
+   * controller permits).
+   */
+  name: string
+  /**
+   * Seed the field's form value from the fetched resource. Receives `null`
+   * on create forms (no resource yet) — return the field's blank value.
+   */
+  from: (resource: TResource | null) => unknown
+}
+
+const registrations = new Map<string, FormFieldRegistration[]>()
+
+/**
+ * Registry of extension fields per built-in form. Form keys match the form's
+ * slot prefix — `'product'` for the product detail form. Registered names
+ * must be unique per form; duplicates throw so two plugins can't silently
+ * fight over one attribute.
+ */
+export const formFields = {
+  register<TResource = unknown>(
+    formKey: string,
+    registration: FormFieldRegistration<TResource>,
+  ): void {
+    const list = registrations.get(formKey) ?? []
+    if (list.some((r) => r.name === registration.name)) {
+      throw new Error(
+        `Form field "${registration.name}" is already registered on the "${formKey}" form.`,
+      )
+    }
+    registrations.set(formKey, [...list, registration as FormFieldRegistration])
+  },
+
+  /** Remove a registered field. No-op when absent. */
+  remove(formKey: string, name: string): void {
+    const list = registrations.get(formKey)
+    if (!list) return
+    registrations.set(
+      formKey,
+      list.filter((r) => r.name !== name),
+    )
+  },
+}
+
+/**
+ * Values for every extension field registered on `formKey`, seeded from
+ * `resource` (or blanks when `null`). Built-in forms merge this into their
+ * defaultValues and every hydration `reset(...)` so extension fields survive
+ * refetch-driven resets.
+ */
+export function extensionFormValues(
+  formKey: string,
+  resource: unknown | null,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const registration of registrations.get(formKey) ?? []) {
+    out[registration.name] = registration.from(resource)
+  }
+  return out
+}
+
+/**
+ * Current values of every extension field registered on `formKey`, read from
+ * live form state. Host forms spread this into their submit payload: the
+ * form's Zod schema only knows first-party fields (its parse strips unknown
+ * keys from the submitted values), so extension values are collected from
+ * `form.getValues(...)` instead — which also keeps them out of client-side
+ * schema validation. Their validation is the server's; a 422 maps back onto
+ * the field via `mapSpreeErrorsToForm`.
+ */
+export function extensionSubmitValues(
+  formKey: string,
+  form: { getValues: (name: string) => unknown },
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const registration of registrations.get(formKey) ?? []) {
+    out[registration.name] = form.getValues(registration.name)
+  }
+  return out
+}
+
+/** Test-only: clear the registry. Not exported from the package index. */
+export function __resetFormFieldsRegistry(): void {
+  registrations.clear()
+}

package/src/lib/form-mappers.ts

@@ -0,0 +1,30 @@
+/**
+ * Treat a blank or whitespace-only string as "not set" — common when mapping
+ * form values to API params, where a blank `<input>` should become `undefined`
+ * (omit the field) or `null` (clear the server value) rather than passing the
+ * empty string through. Returns the trimmed value when present.
+ */
+export function blankToUndefined(s: string | null | undefined): string | undefined {
+  const trimmed = s?.trim()
+  return trimmed ? trimmed : undefined
+}
+
+export function blankToNull(s: string | null | undefined): string | null {
+  const trimmed = s?.trim()
+  return trimmed ? trimmed : null
+}
+
+/**
+ * Preprocessor for Zod optional-number fields backed by `<input type="number">`.
+ * Empty inputs return `''`, which `z.coerce.number()` would coerce to `0` —
+ * tripping `.positive()` / `.min()` on otherwise-optional fields. Map empty
+ * to `undefined` so the optional branch wins.
+ *
+ * ```ts
+ * usage_limit: z.preprocess(emptyToUndefined, z.coerce.number().int().positive().optional())
+ * ```
+ */
+export function emptyToUndefined(value: unknown): unknown {
+  if (value === '' || value === null) return undefined
+  return value
+}

package/src/lib/formatters.ts

@@ -0,0 +1,19 @@
+import type { Price } from '@spree/admin-sdk'
+import { parseISO } from 'date-fns'
+import { formatInTimeZone } from 'date-fns-tz'
+
+export function formatPrice(price: Pick<Price, 'amount' | 'currency' | 'display_amount'> | null) {
+  if (!price) return '—'
+  return price.display_amount ?? `${price.currency} ${price.amount}`
+}
+
+export function formatStoreDateTime(iso: string, timezone: string) {
+  return formatInTimeZone(parseISO(iso), timezone, 'PPP p')
+}
+
+export function getInitials(fullName: string | null | undefined, fallback: string): string {
+  const parts = (fullName ?? '').trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return fallback.charAt(0)
+  if (parts.length === 1) return parts[0].charAt(0)
+  return parts[0].charAt(0) + parts[parts.length - 1].charAt(0)
+}

package/src/lib/i18n.ts

@@ -0,0 +1,210 @@
+import i18n from 'i18next'
+import { initReactI18next } from 'react-i18next'
+// Relative path, not `@/...`: dashboard-core ships source; the consuming
+// project's `@/*` alias is theirs alone (see Phase 1's rationale).
+import en from '../locales/en.json'
+
+// localStorage key for the admin's chosen UI language. Shared by the login
+// screen (pre-auth), the top-bar switcher, and the profile form so a choice
+// made anywhere is honored on the next paint.
+export const ADMIN_LOCALE_STORAGE_KEY = 'spree-admin-locale'
+
+// Marks the locale key as auto-applied from a store's `preferred_admin_locale`
+// (vs an explicit choice). Holds the storeId whose default is currently in
+// effect, so crossing into a different store can re-apply that store's default
+// while a genuine choice (switcher/profile/login) still wins everywhere. Mirrors
+// legacy Rails: the `spree_admin_locale` cookie only ever held an explicit
+// login-screen pick; the store default was re-derived per request, never stored.
+const ADMIN_LOCALE_AUTO_STORE_KEY = 'spree-admin-locale-auto-store'
+
+function readStorage(key: string): string | null {
+  try {
+    if (typeof localStorage === 'undefined') return null
+    return localStorage.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+function writeStorage(key: string, value: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') localStorage.setItem(key, value)
+  } catch {
+    // Restricted-storage contexts (Safari private mode, sandboxed iframes) throw
+    // on write; the choice still applies for this session via the booted `lng`.
+  }
+}
+
+function clearStorage(key: string): void {
+  try {
+    if (typeof localStorage !== 'undefined') localStorage.removeItem(key)
+  } catch {
+    // Ignore — see writeStorage.
+  }
+}
+
+// A full reload is deliberate for a language change: many labels (table columns,
+// nav, registry titles) are resolved with `i18n.t(...)` at module-load time and
+// don't react to a live `changeLanguage`. Reloading re-runs those at boot in the
+// new language (read from localStorage by `init`). Deferred to the next macrotask
+// so a pending React state flush (e.g. a just-saved form clearing its dirty
+// state) completes first — otherwise a still-armed `beforeunload` dirty-guard
+// would trigger the browser's "unsaved changes" prompt.
+function reloadSoon(): void {
+  if (typeof window !== 'undefined') {
+    setTimeout(() => window.location.reload(), 0)
+  }
+}
+
+// Read the stored locale, tolerating restricted-storage contexts where
+// `localStorage` access throws. Returns `null` when there is no stored choice
+// so callers can distinguish "no choice yet" from an explicit value.
+function storedLocale(): string | null {
+  return readStorage(ADMIN_LOCALE_STORAGE_KEY)
+}
+
+function readStoredLocale(): string {
+  return storedLocale() || 'en'
+}
+
+/**
+ * Reconcile the admin UI language against a store's `preferred_admin_locale`
+ * fallback (legacy `base_controller` parity), for an admin with no genuine
+ * personal choice. Encodes the precedence:
+ *   account selected_locale > genuine stored choice > store preferred_admin_locale > 'en'
+ *
+ * No-op when a higher tier owns the language (an account locale, or a genuine
+ * stored choice — locale key set without an auto-marker). Otherwise drives the
+ * stored language to this store's current default:
+ *   - a supported default → adopt it (auto-marked to this store);
+ *   - a blank/cleared/unsupported default → revert to 'en' IF the prior value was
+ *     auto-applied (a stale auto-default from this or another store is dropped);
+ *   - already matching → nothing changes.
+ * Reloads (via the boot path) only when the displayed language actually changes.
+ *
+ * @param code        the store's current `preferred_admin_locale`
+ * @param storeId     the store being entered
+ * @param accountLocale  the account's `selected_locale` (null when unset)
+ * @param supported   locale codes the dashboard ships a bundle for
+ */
+export function reconcileStoreDefaultLocale(
+  code: string | null | undefined,
+  storeId: string,
+  accountLocale: string | null,
+  supported: string[],
+): void {
+  if (accountLocale) return
+  const auto = readStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
+  const stored = storedLocale()
+  // A genuine choice (locale key set, no auto-marker) outranks any store default.
+  if (stored != null && auto == null) return
+
+  const target = code && supported.includes(code) ? code : null
+  const current = i18n.resolvedLanguage ?? i18n.language
+
+  if (target) {
+    writeStorage(ADMIN_LOCALE_STORAGE_KEY, target)
+    writeStorage(ADMIN_LOCALE_AUTO_STORE_KEY, storeId)
+    if (target !== current) reloadSoon()
+  } else if (auto != null) {
+    // Store has no usable default and the current language was auto-applied —
+    // drop it so the UI reverts to the app default ('en').
+    clearStorage(ADMIN_LOCALE_STORAGE_KEY)
+    clearStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
+    if (current !== 'en') reloadSoon()
+  }
+}
+
+// All non-English core bundles, imported EAGERLY so the active language has its
+// resources synchronously available (registered just after init() below) —
+// no flash, no async race with module-load `i18n.t(...)` calls.
+const coreLocales = import.meta.glob<{ default: Record<string, unknown> }>(
+  ['../locales/*.json', '!../locales/en.json'],
+  { eager: true },
+)
+
+/** Admin-UI locale codes the framework ships a bundle for (including `en`). */
+export function coreLocaleCodes(): string[] {
+  return [
+    'en',
+    ...Object.keys(coreLocales).map((p) => p.replace('../locales/', '').replace('.json', '')),
+  ]
+}
+
+/**
+ * Record an explicit, genuine UI-language choice (top-bar switcher, profile,
+ * login, settings-save) WITHOUT reloading. Persists the locale and clears any
+ * store-default marker, so the choice now outranks every store default and
+ * won't be superseded on store switches. Use this when the UI already displays
+ * `code` (no reload needed) but the choice must still be marked as genuine.
+ */
+export function markGenuineLocaleChoice(code: string): void {
+  writeStorage(ADMIN_LOCALE_STORAGE_KEY, code)
+  clearStorage(ADMIN_LOCALE_AUTO_STORE_KEY)
+}
+
+// Switch the admin UI language from an explicit, genuine choice. Marks it as
+// genuine (see `markGenuineLocaleChoice`) and reloads (see `reloadSoon`) so
+// every module-load label re-resolves in the new language.
+export function switchLocale(code: string): void {
+  markGenuineLocaleChoice(code)
+  reloadSoon()
+}
+
+// Bootstrap i18next with the framework's base translation namespace. Side-effect
+// import — `import '@spree/dashboard-core/lib/i18n'` from the consuming app's
+// entry point runs this once before any component calls `useTranslation()`.
+//
+// The app (and any plugin) extends the base by calling
+// `i18n.addResourceBundle('en', 'translation', extraKeys, true, true)`
+// after this side-effect import has settled. The `deep` + `overwrite` flags
+// merge the extension into the base namespace without dropping framework keys.
+//
+// English ships eagerly; `lng` is read from localStorage so a previously
+// chosen language is the initial language on first paint (no flash).
+i18n.use(initReactI18next).init({
+  resources: { en: { translation: en } },
+  lng: readStoredLocale(),
+  fallbackLng: 'en',
+  interpolation: { escapeValue: false },
+  // Surface missing keys in dev so we notice gaps as we build pages; ship
+  // silently humanizing the attribute in prod (a missing key shouldn't blow
+  // up the UI).
+  saveMissing: import.meta.env.DEV,
+  missingKeyHandler: import.meta.env.DEV
+    ? (_lngs, _ns, key) => console.warn(`[i18n] Missing key: ${key}`)
+    : undefined,
+})
+
+// Register the eager non-English core bundles now that i18next is initialized.
+for (const [path, mod] of Object.entries(coreLocales)) {
+  const code = path.replace('../locales/', '').replace('.json', '')
+  i18n.addResourceBundle(code, 'translation', mod.default, true, true)
+}
+
+// Reflect the active language on the root <html> element so the document
+// advertises the right `lang` (a11y, spellcheck, font selection) and `dir`
+// (RTL for Arabic/Hebrew/etc.). `i18n.dir()` consults i18next's built-in RTL
+// language list. Runs at boot; `switchLocale` reloads the page, so the next
+// boot re-applies it for the chosen language — no live listener needed.
+function applyDocumentLanguage(code: string): void {
+  if (typeof document === 'undefined') return
+  const html = document.documentElement
+  html.setAttribute('lang', code)
+  html.setAttribute('dir', i18n.dir(code))
+}
+
+applyDocumentLanguage(i18n.language || readStoredLocale())
+
+/** Document text direction for a locale (`ltr` or `rtl`). */
+export function uiDirection(locale?: string): 'ltr' | 'rtl' {
+  return i18n.dir(locale ?? i18n.language) === 'rtl' ? 'rtl' : 'ltr'
+}
+
+/** Which edge the primary sidebar docks to for a locale. */
+export function primarySidebarSide(locale?: string): 'left' | 'right' {
+  return uiDirection(locale) === 'rtl' ? 'right' : 'left'
+}
+
+export { default as i18n } from 'i18next'
+export { Trans, useTranslation } from 'react-i18next'

package/src/lib/nav-registry.ts

@@ -0,0 +1,224 @@
+import type { LucideIcon } from 'lucide-react'
+import { type ComponentType, useSyncExternalStore } from 'react'
+import type { SubjectName } from './permissions'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type NavSection = 'main' | 'bottom'
+
+/** Ambient context passed to `NavEntry.if` — mirrors `SlotAmbientContext`. */
+export interface NavVisibilityContext {
+  permissions?: unknown
+  store?: unknown
+  user?: unknown
+}
+
+export interface NavEntry {
+  /** Stable identifier — used for register/remove/update and as the React key. */
+  key: string
+  /** Visible label. */
+  label: string
+  /**
+   * Path template, prefixed with `/$storeId` at render time. Pass paths like
+   * `'/orders'`, NOT `/store_abc/orders`. The leading slash is required.
+   */
+  path: string
+  /** Sidebar icon (top-level entries only — subitems don't render icons). */
+  icon?: LucideIcon
+  /** Section. Defaults to `'main'`. `'bottom'` pins to the sidebar footer. */
+  section?: NavSection
+  /** Lower numbers render first. Built-ins use 100/200/300… so plugins can slot in between. */
+  position?: number
+  /** CanCanCan subject required to see this item. Omit for always-visible. */
+  subject?: SubjectName
+  /**
+   * State-based visibility gate evaluated at render (top-level entries only),
+   * e.g. hide Getting Started once the store's setup tasks are all done.
+   * Combines with `subject` — both must pass.
+   */
+  if?: (ctx: NavVisibilityContext) => boolean
+  /**
+   * Rendered after the label (e.g. a count). A component — not an element —
+   * so it can call hooks like useStore and return null to hide itself.
+   */
+  badge?: ComponentType
+  /** Nested children. Children inherit nothing — they declare their own subject + position. */
+  children?: NavEntry[]
+}
+
+interface NavMutator {
+  add(entry: NavEntry): void
+  remove(key: string): void
+  update(key: string, patch: Partial<Omit<NavEntry, 'key'>>): void
+  /** Insert a new entry immediately before `targetKey`. Throws if the target is missing. */
+  insertBefore(targetKey: string, entry: NavEntry): void
+  /** Insert a new entry immediately after `targetKey`. Throws if the target is missing. */
+  insertAfter(targetKey: string, entry: NavEntry): void
+  /**
+   * Append a child under an existing top-level entry (e.g. nest a plugin page
+   * under the built-in `products` menu). Preserves the parent's existing
+   * children — unlike `update(parent, { children })`, which replaces them.
+   * Throws if the parent is missing or the child key already exists there.
+   */
+  addChild(parentKey: string, child: NavEntry): void
+  /** Remove a child by key from a parent. No-op when either is absent. */
+  removeChild(parentKey: string, childKey: string): void
+  /** Patch a child of `parentKey`. Throws if the parent or child is missing. */
+  updateChild(parentKey: string, childKey: string, patch: Partial<Omit<NavEntry, 'key'>>): void
+}
+
+// ============================================================================
+// Registry — module-singleton
+// ============================================================================
+
+const entries: NavEntry[] = []
+const listeners = new Set<() => void>()
+let snapshotCache: { main: NavEntry[]; bottom: NavEntry[] } | null = null
+
+function notify() {
+  snapshotCache = null
+  for (const l of listeners) l()
+}
+
+function findIndex(key: string): number {
+  return entries.findIndex((e) => e.key === key)
+}
+
+function ensureUniqueKey(key: string) {
+  if (entries.some((e) => e.key === key)) {
+    throw new Error(`Nav entry "${key}" already registered. Use nav.update() instead.`)
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+export const nav: NavMutator = {
+  add(entry) {
+    ensureUniqueKey(entry.key)
+    entries.push(entry)
+    notify()
+  },
+  remove(key) {
+    const i = findIndex(key)
+    if (i === -1) return
+    entries.splice(i, 1)
+    notify()
+  },
+  update(key, patch) {
+    const e = entries.find((x) => x.key === key)
+    if (!e) throw new Error(`Nav entry "${key}" not found.`)
+    Object.assign(e, patch)
+    notify()
+  },
+  insertBefore(targetKey, entry) {
+    const i = findIndex(targetKey)
+    if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
+    ensureUniqueKey(entry.key)
+    // Inherit target's position so the relative order survives `getNavEntries`'s sort.
+    const target = entries[i]
+    const adjusted: NavEntry = {
+      ...entry,
+      position: entry.position ?? (target.position ?? 100) - 1,
+    }
+    entries.splice(i, 0, adjusted)
+    notify()
+  },
+  insertAfter(targetKey, entry) {
+    const i = findIndex(targetKey)
+    if (i === -1) throw new Error(`Nav entry "${targetKey}" not found.`)
+    ensureUniqueKey(entry.key)
+    const target = entries[i]
+    const adjusted: NavEntry = {
+      ...entry,
+      position: entry.position ?? (target.position ?? 100) + 1,
+    }
+    entries.splice(i + 1, 0, adjusted)
+    notify()
+  },
+  addChild(parentKey, child) {
+    const parent = requireEntry(parentKey)
+    if (parent.children?.some((c) => c.key === child.key)) {
+      throw new Error(
+        `Nav child "${child.key}" already exists under "${parentKey}". Use nav.updateChild().`,
+      )
+    }
+    parent.children = [...(parent.children ?? []), child]
+    notify()
+  },
+  removeChild(parentKey, childKey) {
+    const parent = entries.find((e) => e.key === parentKey)
+    if (!parent?.children) return
+    const next = parent.children.filter((c) => c.key !== childKey)
+    if (next.length === parent.children.length) return
+    parent.children = next
+    notify()
+  },
+  updateChild(parentKey, childKey, patch) {
+    const parent = requireEntry(parentKey)
+    const idx = parent.children?.findIndex((c) => c.key === childKey) ?? -1
+    if (idx === -1 || !parent.children) {
+      throw new Error(`Nav child "${childKey}" not found under "${parentKey}".`)
+    }
+    // Replace both the child and the array so the patched entry gets a fresh
+    // reference in the next snapshot — in-place mutation would defeat any
+    // reference-equality memoization on the item component.
+    const next = [...parent.children]
+    next[idx] = { ...next[idx], ...patch }
+    parent.children = next
+    notify()
+  },
+}
+
+function requireEntry(key: string): NavEntry {
+  const entry = entries.find((e) => e.key === key)
+  if (!entry) throw new Error(`Nav entry "${key}" not found.`)
+  return entry
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+
+function buildSnapshot(): { main: NavEntry[]; bottom: NavEntry[] } {
+  const sortRecursively = (list: NavEntry[]): NavEntry[] =>
+    [...list]
+      .sort((a, b) => (a.position ?? 100) - (b.position ?? 100))
+      .map((e) => (e.children ? { ...e, children: sortRecursively(e.children) } : e))
+
+  return {
+    main: sortRecursively(entries.filter((e) => (e.section ?? 'main') === 'main')),
+    bottom: sortRecursively(entries.filter((e) => e.section === 'bottom')),
+  }
+}
+
+function getSnapshot() {
+  if (!snapshotCache) snapshotCache = buildSnapshot()
+  return snapshotCache
+}
+
+/**
+ * Subscribe to nav-registry updates and read the sorted entries. Mirrors
+ * `useSlotEntries` from slot-registry.ts. Re-renders only when the registry
+ * is mutated; navigations don't trigger updates.
+ */
+export function useNavEntries() {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+/** Test-only: clear the registry. Not exported from the package index. */
+export function __resetNavRegistry(): void {
+  entries.length = 0
+  notify()
+}
+
+/** Test-only: raw entries in registration order (unsorted, unsectioned). */
+export function __getNavEntries(): readonly NavEntry[] {
+  return entries
+}