kaafil-react-uikit 0.1.0-beta.1

package/dist/core/index.d.ts

@@ -0,0 +1,1267 @@
+import { D as DomainHookResult, g as CapabilityTriple, h as ErrorClassification } from '../useVendors-DXOuZWhZ.js';
+export { i as CapabilityRow, a as ChecklistsReady, j as DarkReason, k as ERROR_HANDLING_PATH, l as ErrorHandlingPath, m as ExpensesReady, n as FilesContext, o as FilesReady, p as FloatReady, q as FormsReady, r as ItineraryReady, s as RoomingReady, t as RoomingUnassignedPool, V as VendorsReady, u as classifyError, v as useChecklists, w as useExpenses, x as useFiles, y as useFloat, z as useForms, A as useItinerary, B as useRooming, G as useVendors } from '../useVendors-DXOuZWhZ.js';
+import { ManagerAgencyProfileResponse, BookingListRow, AgencyAdminMeResponse, OfflineEngine, OutboxOp, KaafilClient, FeedbackNpsResource, DispatchFormOptions, JourneyResource, BoundJourneyResource, TripManagersResource, OfflineEventName, OfflineEventMap, ShareTokensResource, FormsResource, TravellersResource, TreksResource, CreateTrekWalkInOptions, PostponeTrekOptions, Environment, KaafilStorageAdapter, BlobUploader, BlobSource, ConflictResolver, EntityReader } from 'kaafil-js/client';
+export { AgencyTripFilters, AgencyTripSegmentCounts, ManagerAgencyProfileResponse, TripManifestFacets, TripManifestFilters, UnsatisfiableSchemeError } from 'kaafil-js/client';
+export { i as AgencyChecklistTemplatesReady, j as AgencyFormsReady, k as AgencyJourneyTriggersReady, g as AgencySettingsDocument, l as AgencySettingsReady, m as AgencyTripManifestResult, f as AgencyTripRead, n as AgencyTripResult, A as AgencyTripRow, o as AgencyTripsResult, B as BindingRow, a as ChecklistTemplateItemRow, C as ChecklistTemplateRow, p as CloneFormInput, q as CollectionsReady, r as CreateFormFieldInput, s as CreateFormInput, t as CreateFormSectionInput, D as DeleteFormFieldInput, u as DeleteFormInput, v as DeleteFormSectionInput, w as DirectoriesReady, F as FormDetailRow, b as FormFieldRow, c as FormRow, h as FormSectionRow, x as FormSummaryRow, J as JourneyTriggerRow, P as PaginatedListFetch, y as PaginatedListFetchResult, z as PaginatedListOptions, E as PaginatedListResult, G as PatchAgencySettingsInput, H as PatchFormFieldInput, I as PatchFormInput, K as PatchFormSectionInput, L as PatchJourneyTriggerInput, R as ReorderFormInput, d as TripManifestRow, N as useAgencyChecklistTemplates, O as useAgencyForms, Q as useAgencyJourneyTriggers, S as useAgencySettings, U as useAgencyTrip, V as useAgencyTripManifest, W as useAgencyTrips, X as useCollections, Y as useDirectories, Z as useKaafilClient, _ as usePaginatedList } from '../useAgencyTrip-BzyJB1D9.js';
+import { C as ConflictRecord, S as StalenessState } from '../useNotifications-D262i5BQ.js';
+export { a as CloseoutReady, M as ManagerMeReady, b as ManagerMeResult, c as ManagerNotification, d as ManagerTodayReady, e as ManagerTodayResult, N as NotificationsReady, f as NotificationsResult, O as OutboxState, P as PartiesReady, g as PickupsReady, h as SeatingReady, i as SyncEventKind, u as useCloseout, j as useManagerMe, k as useManagerToday, l as useNotifications, m as useParties, n as usePickups, o as useSeating } from '../useNotifications-D262i5BQ.js';
+import { ReactNode, Component } from 'react';
+import { K as KaafilTokenOverrides } from '../tokenStyle-CToG5oOS.js';
+
+type ManagerAgencyProfileRead = ManagerAgencyProfileResponse;
+interface AgencyManagerProfileResult {
+    readonly read: ManagerAgencyProfileRead | undefined;
+    readonly readFailed: boolean;
+    readonly refresh: () => Promise<void>;
+}
+declare function useAgencyManagerProfile(managerRef: string): AgencyManagerProfileResult;
+
+/**
+ * The FULL replacement set for one booking's vouchers.
+ *
+ * `voucherFileKeys` REPLACES the stored array wholesale (`bookings FRD` R6) —
+ * there is no add-one call. A caller that sends only its new key detaches
+ * every voucher the CRM already attached, so a UI must read the booking's
+ * current list and send it back plus the addition. Named `…FileKeys` rather
+ * than `…FileIds` because that is the wire field; the values are file ids.
+ */
+interface ReplaceBookingVouchersInput {
+    readonly bookingRef: string;
+    readonly voucherFileKeys: readonly string[];
+}
+interface BookingsReady {
+    readonly bookings: readonly BookingListRow[];
+    readonly syncedAt: string | undefined;
+    /** Re-read the live list — used after a voucher write so the booking's own
+     * `voucherFileKeys` stops being stale. */
+    readonly refreshLive: () => Promise<void>;
+    /**
+     * `PATCH /trips/{ref}/bookings/{bookingRef}/vouchers`. The ONE write this
+     * hook has, and the only booking field a browser may change.
+     *
+     * `ReplaceBookingVouchersOptions` declares NO `idempotencyKey`, so nothing
+     * here mints or accepts one (hard rule #4) and the desk lane is legal.
+     */
+    readonly replaceVouchers: (input: ReplaceBookingVouchersInput) => Promise<void>;
+}
+declare function useBookings(tripRef: string): DomainHookResult<BookingsReady>;
+
+/**
+ * Thrown by a §3 domain hook that has no implementation yet in this build.
+ *
+ * Deliberately NOT the same class as `kaafil-js`'s own `KaafilNotImplementedError`
+ * (re-exported by `./classify.ts`'s callers via `kaafil-js/client` where
+ * needed) — that one models the wire's `501 NOT_IMPLEMENTED` catalog code (a
+ * reserved server route, `architecture/10-conventions.md §7`), a fact about
+ * the API. This one is a fact about THIS PACKAGE's own build: the hook
+ * exists, type-checks, and is importable, but its body has not been
+ * authored yet. Naming it differently keeps a composite's `catch` block from
+ * ever conflating "the server hasn't shipped this route" with "the UIKit
+ * hasn't shipped this hook" — the two need different user-facing copy and
+ * the two need different fixes.
+ */
+declare class NotImplementedError extends Error {
+    readonly hookName: string;
+    readonly specSection: string;
+    constructor(hookName: string, specSection: string);
+}
+
+interface AgencyAdminMeLoading {
+    readonly status: 'loading';
+}
+interface AgencyAdminMeError {
+    readonly status: 'error';
+}
+interface AgencyAdminMeReady {
+    readonly status: 'ready';
+    readonly agencyAdmin: AgencyAdminMeResponse['agencyAdmin'];
+}
+type AgencyAdminMeResult = AgencyAdminMeLoading | AgencyAdminMeError | AgencyAdminMeReady;
+/**
+ * `client.agencyAdminMe.read()` behind a plain fetch-on-mount effect — this
+ * read takes no parameter (it resolves entirely off the authenticated
+ * principal, `agency-admin-me.routes.ts`'s own header, cited), so it never
+ * re-fetches on a prop change. A caller wanting "refresh now" re-mounts this
+ * hook's owning component.
+ */
+declare function useAgencyAdminMe(): AgencyAdminMeResult;
+
+interface BlobStatusResult {
+    readonly status: 'pending' | 'uploading' | 'ready' | 'orphaned' | 'purged';
+    readonly progress: number | undefined;
+}
+declare function useBlobStatus(blobId: string): BlobStatusResult;
+
+/** `08-core-hooks.md §1.4`. Persona restriction: unavailable to `share`. */
+declare function useCapability(key: string): CapabilityTriple;
+/** `08-core-hooks.md §1.4`. Omitting `keys` returns every key the last read
+ * carried. Persona restriction: unavailable to `share`. */
+declare function useCapabilities(keys?: readonly string[]): ReadonlyMap<string, CapabilityTriple>;
+
+interface CapabilityStatusesResult {
+    /** Capability key → the derived status, for every key the last read
+     * carried. A key that is ABSENT from this map is absent from the read —
+     * callers apply their own open-set fallback (`06 §6` point 5), which this
+     * hook deliberately does not choose for them. */
+    readonly statuses: ReadonlyMap<string, CapabilityTriple['status']>;
+    /** `false` until the first `journey.capabilities()` response for this trip
+     * has landed. A `share` session is immediately `true` with an empty map
+     * (`06 §9` — no `share.*` operation exposes this read). */
+    readonly loaded: boolean;
+}
+declare function useCapabilityStatuses(tripRef: string): CapabilityStatusesResult;
+
+interface ConflictsResult {
+    readonly conflicts: readonly ConflictRecord[];
+    readonly resolve: (opId: string, choice: 'keep-queued' | 'keep-current') => Promise<void>;
+}
+declare function useConflicts(tripRef: string): ConflictsResult;
+
+type OfflineMutationStatus = 'idle' | 'queued' | 'syncing' | 'synced' | 'conflicted' | 'parked';
+interface OfflineMutationConfig<TOptions> {
+    readonly tripRef: string;
+    readonly enqueue: (engine: OfflineEngine, options: TOptions) => Promise<OutboxOp>;
+    /**
+     * The same write, awaited straight against the SDK, for a surface with no
+     * `OfflineShell` — see this file's header. Omit it and `mutate` keeps its
+     * original throw on such a surface, which is right for a domain that only
+     * a field persona ever writes.
+     *
+     * Its resolved value is deliberately unused: the caller re-reads after the
+     * write (every domain hook here already does), so a returned row would be a
+     * second, staler copy of what the refresh is about to fetch.
+     */
+    readonly direct?: (client: KaafilClient, options: TOptions) => Promise<unknown>;
+}
+/** A config that HAS a direct lane — the overload below keys on this. */
+interface OfflineMutationConfigWithDirect<TOptions> extends OfflineMutationConfig<TOptions> {
+    readonly direct: (client: KaafilClient, options: TOptions) => Promise<unknown>;
+}
+/**
+ * `TQueued` is `OutboxOp` for a config with no direct lane and
+ * `OutboxOp | null` for one that has it. Parameterised rather than widened
+ * unconditionally: a hook that supplies no `direct` can never take the direct
+ * branch, so telling its callers the result might be `null` would be a lie
+ * that every one of the fourteen existing domain hooks would have to absorb
+ * into its own published `Ready` interface.
+ */
+interface OfflineMutationResult<TOptions, TQueued = OutboxOp> {
+    /** `null` on the direct lane — committed, with no outbox row to track. */
+    readonly mutate: (options: TOptions) => Promise<TQueued>;
+    readonly status: OfflineMutationStatus;
+    readonly op: OutboxOp | undefined;
+}
+declare function useOfflineMutation<TOptions>(config: OfflineMutationConfigWithDirect<TOptions>): OfflineMutationResult<TOptions, OutboxOp | null>;
+declare function useOfflineMutation<TOptions>(config: OfflineMutationConfig<TOptions>): OfflineMutationResult<TOptions, OutboxOp>;
+
+type FeedbackNpsScope = {
+    readonly kind: 'trip';
+    readonly tripRef: string;
+} | {
+    readonly kind: 'agency';
+    readonly agencyRef: string;
+};
+type TripFeedbackSummaryData = Awaited<ReturnType<FeedbackNpsResource['trip']>>['data'];
+type AgencyFeedbackSummaryData = Awaited<ReturnType<FeedbackNpsResource['agency']>>['data'];
+/** One row of the `agency` read's `definitions[]` — the agency-wide rollup
+ * `manager/06-feedback-nps.md` explicitly leaves to the admin family; kept
+ * here only so this one shared hook serves both scopes uniformly. */
+type FeedbackNpsAgencyDefinitionRow = AgencyFeedbackSummaryData['definitions'][number];
+type DispatchFeedbackChaseInput = Omit<DispatchFormOptions, 'tripRef' | 'formId' | 'idempotencyKey' | 'signal'>;
+interface FeedbackNpsReady {
+    readonly kind: FeedbackNpsScope['kind'];
+    /** `trip` scope only — the discriminated union verbatim off the wire.
+     * `undefined` on `agency` scope, or before the first `trip` fetch has
+     * settled (`loaded` distinguishes the two). */
+    readonly summary: TripFeedbackSummaryData | undefined;
+    /** `agency` scope only — always `[]` on `trip` scope. */
+    readonly definitions: readonly FeedbackNpsAgencyDefinitionRow[];
+    /** `true` once the first read has settled (success or failure) —
+     * distinguishes "never fetched yet" from "fetched, and this trip
+     * genuinely has no feedback form configured" (`CloseoutReady.loaded`'s
+     * own contract, reused). */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw. `loaded`/`summary`/
+     * `definitions` stay whatever they already were. */
+    readonly lastFetchFailed: boolean;
+    readonly syncedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+    /** `trip` scope only. Throws if called before a `configured: true`
+     * summary has resolved a `formId` to target — a caller gates the
+     * dispatch control on `summary?.configured === true` first exactly as
+     * `manager/06-feedback-nps.md`'s own `FeedbackDispatchControls` does. */
+    readonly dispatch: (input?: DispatchFeedbackChaseInput) => Promise<OutboxOp>;
+    /** The dispatch op's OWN outbox lifecycle (`useOfflineMutation`'s own
+     * `status`) — `'parked'`/`'conflicted'` is how a `423`
+     * ("this trip has been closed out") or a `402` plan-lock surfaces, via
+     * `dispatchOp?.parkReason?.userMessage` (`06-feedback-nps.md`'s own
+     * `locked (423)`/`parked (402)` States rows). */
+    readonly dispatchStatus: OfflineMutationStatus;
+    readonly dispatchOp: OutboxOp | undefined;
+}
+/**
+ * Two scope members, different credential sets, one shared read/refresh
+ * shape — see this file's header for why there is no `createDomainHook()`
+ * gate. `manager`'s own `FeedbackNpsFlow` only ever calls this with
+ * `{ kind: 'trip', tripRef }`; the `agency` branch exists for the admin
+ * family's own agency-wide rollup, reusing this same hook rather than a
+ * second `useAgencyFeedbackNps()` (hard rule #2).
+ */
+declare function useFeedbackNps(scope: FeedbackNpsScope): FeedbackNpsReady;
+
+type JourneyReadResponse = Awaited<ReturnType<JourneyResource['get']>>;
+interface JourneyResult {
+    readonly read: JourneyReadResponse | undefined;
+    readonly capabilities: ReadonlyMap<string, CapabilityTriple>;
+    readonly refreshCapabilities: () => Promise<void>;
+    readonly triggers: {
+        list: BoundJourneyResource['triggers']['list'];
+        patch: BoundJourneyResource['triggers']['patch'];
+    };
+}
+declare function useJourney(tripRef: string): JourneyResult;
+
+/** One row of `trips.managers.list`'s result — derived structurally off the
+ * resource's own return type (`useJourney.ts`'s identical precedent for
+ * `JourneyReadResponse`), so this can never drift from what the SDK
+ * actually returns. */
+type TripManagerRow = Awaited<ReturnType<TripManagersResource['list']>>[number];
+type ManagersResult = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'ready';
+    readonly managers: readonly TripManagerRow[];
+} | {
+    readonly status: 'error';
+    readonly error: ErrorClassification;
+};
+/**
+ * A trip's manager roster — every live manager assigned to the trip,
+ * lead first (`trips.managers.list`'s own doc comment). `manager`/
+ * `agencyAdmin` only, matching `useJourney()`'s identical persona
+ * restriction and identical dev-only throw on misuse.
+ */
+declare function useManagers(tripRef: string): ManagersResult;
+
+/** Returns the engine instance `OfflineShell` opened via
+ * `client.openOffline(options)`. Throws outside the provider tree. */
+declare function useOfflineEngine(): OfflineEngine;
+
+/**
+ * Subscribes `handler` to `name` for as long as the calling component is
+ * mounted. `session.expired`/`share.expired`/`share.revoked` firing for the
+ * "wrong" persona's session is inert, not an error (`08-core-hooks.md
+ * §2.6`'s persona-restriction note) — this hook does not filter by persona
+ * itself, since the engine only ever emits the events its own persona can
+ * produce.
+ */
+declare function useOfflineEvent<TName extends OfflineEventName>(name: TName, handler: (event: OfflineEventMap[TName]) => void): void;
+
+interface OutboxStatusOptions {
+    readonly tripRef?: string;
+}
+interface OutboxStatusResult {
+    readonly pending: number;
+    readonly parked: number;
+    readonly lanes: readonly string[];
+    readonly isOnline: boolean;
+}
+/**
+ * `isOnline` reads `navigator.onLine` where available (every browser target
+ * this package ships to) and defaults to `true` on a runtime without a
+ * `navigator` (SSR) — the honest default for a signal that only degrades
+ * gracefully, never one this hook can source from the SDK itself: `06
+ * -offline-first.md` and `08-core-hooks.md §2.9`'s own "Wraps" line name
+ * "the transport's own online/offline signal" but `kaafil-js`'s
+ * `OfflineEngine` does not expose a queryable connectivity flag of its own
+ * (verified — `Outbox`/`Drainer` react to `online`/`offline` DOM events
+ * internally via `bindOpportunisticTriggers()`, but neither surfaces the
+ * CURRENT state as a readable property). This hook therefore reads the
+ * browser signal directly and refreshes it on the same events the engine
+ * itself listens for, rather than duplicating a connectivity tracker inside
+ * the SDK it is meant to be a thin subscription over.
+ */
+declare function useOutboxStatus(options?: OutboxStatusOptions): OutboxStatusResult;
+
+/**
+ * The three credential kinds a `KaafilClient` can be opened with, collapsed
+ * to the label every component downstream of the session adapter is allowed
+ * to see (`06-capability-and-personas.md §7`). Never a JWT, never which of
+ * `session.open`/`admin.open`/`share.open` produced it beyond this label.
+ */
+type Persona = 'manager' | 'agencyAdmin' | 'share';
+/**
+ * `useSession()`'s return shape (`08-core-hooks.md §1.2`). `agencyRef` is
+ * `undefined` only for a `share` session — a share token carries no agency
+ * scope of its own (`client-entry.ts`'s share-session header, verified).
+ */
+interface SessionState {
+    readonly status: 'authenticated' | 'expired' | 'opening';
+    readonly persona: Persona;
+    readonly agencyRef: string | undefined;
+    readonly environment: 'live' | 'test';
+}
+
+declare function usePersona(): Persona;
+
+/**
+ * Returns the resolved value of `key` (`module.group.key`), or `undefined`
+ * when no rung supplied one and there is no frozen default to fall back to.
+ * There is no default parameter and none may ever be added (hard rule #5) —
+ * a component that needs to render something while this is `undefined`
+ * renders a loading/unknown state, never a guessed value.
+ */
+declare function useResolvedSetting<T>(key: `${string}.${string}.${string}`): T | undefined;
+
+interface ServerTimeApi {
+    now: () => string;
+    sinceLastSync: string | undefined;
+}
+declare function useServerTime(): ServerTimeApi;
+
+/**
+ * Returns the open session's derived state. Reads the base value
+ * `SessionShell` provides, then layers the `session.expired` offline event
+ * (`08-core-hooks.md §1.2`'s "Wraps" paragraph) on top locally, so a
+ * `manager`/`agencyAdmin` session that expires mid-mount transitions to
+ * `status: 'expired'` without waiting on `SessionShell` to re-render this
+ * subtree itself. `OfflineShell` may not have mounted yet (or ever, for a
+ * consumer that only needs `useKaafilClient()`) — the listener attaches
+ * only when an `OfflineEngine` is actually in context, and is a no-op
+ * otherwise; this hook still throws if `SessionShell` itself is absent,
+ * since a session-derived read with no session is meaningless.
+ */
+declare function useSession(): SessionState;
+
+/** One row of `GET /api/v1/share/{token}/forms` — `ShareFormsListResponse`
+ * (verified, `kaafil-js/openapi/openapi.json`). Metadata only: no prefill,
+ * no field list, no answers (`FRD:traveller-share §4.8`) — that detail
+ * arrives only from `renderForm()` below. */
+interface ShareFormListItem {
+    readonly formId: string;
+    readonly key: string;
+    readonly title: string;
+    readonly phase: string;
+    readonly required: boolean;
+    readonly fillState: string;
+    readonly opensAt: string | null;
+    readonly closesAt: string | null;
+    readonly responseStatus: string | null;
+    readonly submittedAt: string | null;
+}
+/** One answer in a `save`/`submit` body — `ShareSaveFormRequest.answers[]`
+ * / `ShareSubmitFormRequest.answers[]` (verified). */
+interface ShareFormAnswer {
+    readonly fieldKey: string;
+    readonly value: unknown;
+}
+interface ShareFormWriteInput {
+    readonly formId: string;
+    readonly answers: readonly ShareFormAnswer[];
+    /** This route's own de-dupe key — REQUIRED by the wire schema. See this
+     * file's header ("`clientToken` IS NOT A HOOK-MINTED IDEMPOTENCY KEY") —
+     * the caller mints this once per form-fill session and reuses it across
+     * every save/submit/retry of that session; this hook never generates it. */
+    readonly clientToken: string;
+    /** Group fill within the same `TripTraveller.partyId` — omit when the
+     * token itself already scopes to a single traveller. */
+    readonly travellerRef?: string;
+    readonly startNew?: boolean;
+    readonly isAnonymous?: boolean;
+}
+type ShareFormsListStatus = 'loading' | 'list-empty' | 'list-populated' | 'not-found';
+/**
+ * The write-side status a `save()`/`submit()` call's tracked `OutboxOp`
+ * resolves to. Deliberately excludes `'filling'` (`02-forms.md`'s own
+ * `States` list also names it): `'filling'` is "the traveller is editing
+ * fields, no request in flight yet" — a pure local UI mode with no
+ * server/outbox signal behind it, so it belongs to the composite that owns
+ * the form's field state, never to this hook, which only ever reflects
+ * something async.
+ */
+type ShareFormsWriteStatus = 'idle' | 'saving' | 'submitting' | 'submitted' | 'conflicted' | 'subject-required' | 'queued-offline' | 'dropped-on-revoke';
+interface ShareFormsResult {
+    readonly status: ShareFormsListStatus;
+    /** `[]` in both the `'loading'` and the `'list-empty'` states — a
+     * consumer distinguishes them via `status`, never via array emptiness
+     * alone (`02-forms.md`'s `Gating`: an empty list is a NORMAL steady
+     * state, never an error, never a placeholder). */
+    readonly forms: readonly ShareFormListItem[];
+    readonly serverTime: string | undefined;
+    /** Re-runs `share.forms.list()`. A composite calls this after a
+     * `submit()` lands, since submitting can change another form's
+     * `fillState` (e.g. an any-phase trigger opening a follow-up form). */
+    readonly refresh: () => Promise<void>;
+    /** `GET /api/v1/share/{token}/forms/{formId}` — the fully-resolved,
+     * ready-to-paint form (definition merged with any in-progress answers).
+     * An open shape (`ShareRenderResponse` has no closed schema yet,
+     * verified) — a live call, not cached, matching `save`/`submit`'s own
+     * un-cached write path. */
+    readonly renderForm: (formId: string, options?: {
+        readonly travellerRef?: string;
+    }) => Promise<Record<string, unknown>>;
+    /** An in-progress save — no required-field validation server-side. */
+    readonly save: (input: ShareFormWriteInput) => Promise<OutboxOp>;
+    /** Finalizes the response — full validation, one transaction. */
+    readonly submit: (input: ShareFormWriteInput) => Promise<OutboxOp>;
+    /** The combined save/submit write status — see `ShareFormsWriteStatus`. */
+    readonly writeStatus: ShareFormsWriteStatus;
+    /** The most recently tracked save/submit `OutboxOp`, or `undefined`
+     * before either has ever been called. */
+    readonly writeOp: OutboxOp | undefined;
+}
+declare function useShareForms(token: string): ShareFormsResult;
+
+/** Metadata for one link. Never carries a plaintext token. */
+type ShareLinkRow = Awaited<ReturnType<ShareTokensResource['list']>>[number];
+/** A freshly minted link — the ONE shape that carries `token`. */
+type MintedShareLink = Awaited<ReturnType<ShareTokensResource['create']>>;
+/**
+ * The 14 sections a link can expose, in the order the engine's own
+ * `SHARE_SECTION_KEYS` declares them.
+ *
+ * Derived from the SDK's own request type rather than hand-listed, so a
+ * section added engine-side becomes a compile error here instead of a
+ * silently-missing checkbox.
+ */
+type ShareSectionKey = keyof NonNullable<NonNullable<Parameters<ShareTokensResource['create']>[0]['config']>['sections']>;
+type ShareSections = Readonly<Record<ShareSectionKey, boolean>>;
+interface MintShareLinkInput {
+    /** Omit for the whole-trip FAMILY link. */
+    readonly travellerRef?: string;
+    /**
+     * Omit entirely for the agency's own mode-based default. Supplying it turns
+     * every UNSET key OFF — a partial config does NOT inherit the defaults, so
+     * a caller that supplies this must name every section it wants visible.
+     * That is the wire's rule, not this hook's.
+     */
+    readonly sections?: ShareSections;
+    readonly ttlDays?: number;
+    readonly expiresAt?: string;
+}
+interface PatchShareLinkInput {
+    readonly id: string;
+    /** The token row's own version. A stale one answers `409 CONFLICT_VERSION`. */
+    readonly version: number;
+    readonly sections?: ShareSections;
+    readonly expiresAt?: string;
+}
+interface ShareLinksResult {
+    /** Live links on this trip — `undefined` until the first read lands. */
+    readonly links: readonly ShareLinkRow[] | undefined;
+    readonly readFailed: boolean;
+    readonly refresh: () => Promise<void>;
+    readonly mint: (input: MintShareLinkInput) => Promise<MintedShareLink>;
+    readonly revoke: (id: string) => Promise<void>;
+    readonly patch: (input: PatchShareLinkInput) => Promise<void>;
+    readonly regenerate: (id: string) => Promise<MintedShareLink>;
+}
+/**
+ * `travellerRef` narrows the LIST to one subject; pass `null` for every link
+ * on the trip, family link included. Minting takes its own `travellerRef`
+ * independently, so one hook instance can list a traveller's links and mint
+ * a family link.
+ */
+declare function useShareLinks(tripRef: string, travellerRef: string | null): ShareLinksResult;
+
+interface ShareSnapshotOptions {
+    readonly travellerRef?: string;
+}
+type ShareSnapshotResponse = Awaited<ReturnType<KaafilClient['share']['snapshot']>>;
+/** The trip echo every snapshot response carries — `name`/`startDate`/
+ * `endDate` plus the two fields this hook used to throw away:
+ * `timezone` (the IANA zone every traveller-facing render must anchor to)
+ * and `phase` (server-computed `PRE_DEPARTURE`/`ON_TRIP`/`POST_TRIP`). */
+type ShareSnapshotTrip = ShareSnapshotResponse['trip'];
+interface ShareSnapshotResult {
+    readonly status: 'loading' | 'ready' | 'expired' | 'revoked' | 'not-found';
+    readonly sections: ReadonlyMap<string, unknown>;
+    /** The snapshot's `trip` echo, or `undefined` before any response has
+     * landed (mirrors `sections`' own "empty until ready" behaviour). NEVER a
+     * section key — see this file's header. */
+    readonly trip: ShareSnapshotTrip | undefined;
+    /** `meta.serverTime` off the most recently landed snapshot response — the
+     * only trusted clock a share composite may read (hard rule #6). Kept
+     * separate from `useServerTime()`'s own stream (which advances off
+     * `OfflineEngine`'s `snapshot.updated` event, not this hook's own fetch)
+     * so a composite that only ever calls `useShareSnapshot()` still has a
+     * real server stamp to compare against without also wiring the offline
+     * engine's event stream. `undefined` before any response has landed. */
+    readonly serverTime: string | undefined;
+}
+declare function useShareSnapshot(token: string, options?: ShareSnapshotOptions): ShareSnapshotResult;
+
+interface SnapshotEntityResult<TRow> {
+    readonly row: TRow | undefined;
+    readonly syncedAt: string | undefined;
+}
+/**
+ * `row` is `undefined` both when the id genuinely doesn't exist and when
+ * the list hasn't synced yet — a caller distinguishes those with
+ * `syncedAt`: absent entirely means "never pulled"; present with `row:
+ * undefined` means "pulled, and this id isn't in it" (`08-core-hooks.md
+ * §2.3`).
+ */
+declare function useSnapshotEntity<TRow extends Record<string, unknown>>(tripRef: string, listName: string, id: string): SnapshotEntityResult<TRow>;
+
+interface SnapshotListOptions<TRow> {
+    /**
+     * The same list, read live, for a surface with no `OfflineShell`. Resolve
+     * the rows AND the server's own time — `syncedAt` means the same thing on
+     * both lanes ("what this reading is as of"), and deriving it from a device
+     * clock would make the two disagree.
+     */
+    readonly live?: (client: KaafilClient, tripRef: string) => Promise<{
+        readonly rows: readonly TRow[];
+        readonly syncedAt: string | undefined;
+    }>;
+}
+interface SnapshotListResult<TRow> {
+    readonly rows: readonly TRow[];
+    readonly syncedAt: string | undefined;
+    /**
+     * Re-reads the live lane. A NO-OP on the snapshot lane, where the store's
+     * own `snapshot.updated` event already drives re-render and a manual
+     * refetch would be a second sync path.
+     */
+    readonly refreshLive: () => Promise<void>;
+}
+/**
+ * At-least-once delivery is the CALLER's problem to absorb structurally
+ * (`07-offline-and-sync.md §4`) — this hook returns exactly what
+ * `SnapshotStore.list()` holds and does not de-duplicate beyond what the
+ * store itself already guarantees.
+ */
+declare function useSnapshotList<TRow extends Record<string, unknown>>(tripRef: string, listName: string, options?: SnapshotListOptions<TRow>): SnapshotListResult<TRow>;
+
+/**
+ * DECISION: the catalog names "a threshold `ConfigShell` supplies" without
+ * naming the resolved-setting key. `stale.thresholdSeconds` is this hook's
+ * own choice of key, under the `stale` module namespace — the closest fit to
+ * `useResolvedSetting`'s `module.group.key` shape (`08-core-hooks.md §1.5`)
+ * for a value that isn't owned by any one of the eighteen domain modules.
+ * `isStale` is conservatively `false` (never a guessed threshold) when
+ * nothing resolved one — the honest reading of "no threshold configured"
+ * given `useResolvedSetting()` may never supply its own default (hard rule
+ * #5).
+ */
+declare function useStaleness(tripRef: string, listName: string): StalenessState;
+
+type TravellerFormResponseRow = Awaited<ReturnType<FormsResource['trip']['travellerResponses']['list']>>['items'][number];
+interface TravellerFormResponsesResult {
+    readonly responses: readonly TravellerFormResponseRow[] | undefined;
+    readonly readFailed: boolean;
+    readonly refresh: () => Promise<void>;
+}
+/**
+ * `travellerRef` is nullable so a caller can mount this unconditionally while
+ * its own panel is closed — Rules of Hooks forbid calling it conditionally,
+ * and `null` reads as "nothing open yet" rather than firing a request for a
+ * traveller nobody asked for.
+ */
+declare function useTravellerFormResponses(tripRef: string, travellerRef: string | null): TravellerFormResponsesResult;
+
+type TravellerProfileRead = Awaited<ReturnType<TravellersResource['getDetail']>>;
+interface AddTravellerNoteInput {
+    readonly body: string;
+}
+interface TravellerProfileResult {
+    readonly read: TravellerProfileRead | undefined;
+    readonly readFailed: boolean;
+    readonly refresh: () => Promise<void>;
+    readonly addNote: (input: AddTravellerNoteInput) => Promise<OutboxOp>;
+}
+declare function useTravellerProfile(tripRef: string, travellerRef: string): TravellerProfileResult;
+
+/** `TrekBoardResponse` — verified against `kaafil-js/src/generated/
+ * schema.d.ts`. `TreksResource['board']` resolves to `KaafilResponse<
+ * TrekBoardResponse>` = `TrekBoardResponse & { meta }` (`kaafil-js/src/
+ * types/meta.ts`'s own intersection, not a nested `data` field — unlike
+ * `FloatSummaryResponse`/`FloatLedgerResponse`, `TrekBoardResponse` carries
+ * `phase`/`stops`/`runningHeadCount`/`emptyState` at its own top level).
+ * `phase`/`externalTripId` are `null` only when `emptyState` is set; every
+ * other field still comes back with its empty/zero identity rather than
+ * being omitted (the schema's own doc comment). */
+type TrekBoardData = Awaited<ReturnType<TreksResource['board']>>;
+/** One row of `treks.walkIns.listPage()`'s page — `KaafilPagedResponse<
+ * readonly WalkInListItemResponse[]>` = the array itself, `meta` attached
+ * (`kaafil-js/src/types/meta.ts`), never a nested `.data`. */
+type TrekWalkInRow = Awaited<ReturnType<TreksResource['walkIns']['listPage']>>[number];
+/** `WalkInMetaResponse` — the pickup options + field-requirement hints a
+ * walk-in intake form reads, verified against the generated schema; same
+ * flat (non-`data`-nested) shape as `TrekBoardData`. */
+type TrekWalkInMetaData = Awaited<ReturnType<TreksResource['walkIns']['meta']>>;
+type CreateTrekWalkInInput = Omit<CreateTrekWalkInOptions, 'trekRef' | 'idempotencyKey' | 'signal'>;
+type PostponeTrekInput = Omit<PostponeTrekOptions, 'trekRef' | 'idempotencyKey' | 'signal'>;
+/** `ReconcileTrekWalkInOptions` — verified real (`treks.ts`'s own
+ * `walkIns.reconcile`) but NOT re-exported from `kaafil-js/client`'s public
+ * surface (verified: `client-entry.ts`'s `export type { ... } from
+ * './resources/treks'` list omits it, unlike its five siblings). Derived
+ * structurally off `TreksResource['walkIns']['reconcile']`'s own parameter
+ * rather than importing a name that does not exist on the package's public
+ * barrel — see this worker's final report for the exact export gap. */
+type ReconcileTrekWalkInInput = Omit<Parameters<TreksResource['walkIns']['reconcile']>[0], 'trekRef' | 'walkInId' | 'idempotencyKey' | 'signal'>;
+/**
+ * The phase-aware boarding board — a live-fetched, explicitly-refreshed
+ * state, never a snapshot subscription. See this file's header for why.
+ */
+interface TrekBoardState {
+    readonly data: TrekBoardData | undefined;
+    /** `true` once at least one `client.treks.board()` call has settled
+     * (success or failure) — same `loaded` contract `RoomingUnassignedPool`/
+     * `useFloat().summary` document. */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw — a genuine transport/server
+     * failure, distinct from the honest `emptyState` "no trek assigned"
+     * `200`. */
+    readonly lastFetchFailed: boolean;
+    readonly fetchedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+}
+/** The walk-in roster — live-fetched via `listPage`, one page at a time
+ * (`08-treks.md §TrekWalkInRoster`'s own prop table cites `.list`/
+ * `.listPage`, never a delta feed). `loadMore` advances the cursor; calling
+ * `refresh` resets back to the first page. */
+interface TrekWalkInsState {
+    readonly rows: readonly TrekWalkInRow[];
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly fetchedAt: string | undefined;
+    readonly hasMore: boolean;
+    readonly refresh: () => Promise<void>;
+    readonly loadMore: () => Promise<void>;
+}
+interface TrekWalkInMetaState {
+    readonly data: TrekWalkInMetaData | undefined;
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly refresh: () => Promise<void>;
+}
+interface TreksReady {
+    readonly board: TrekBoardState;
+    readonly walkIns: TrekWalkInsState;
+    readonly walkInMeta: TrekWalkInMetaState;
+    /** `POST .../walk-ins` — lands `BOARDED` directly for a manager submitter
+     * (`D-211`). */
+    readonly createWalkIn: (input: CreateTrekWalkInInput) => Promise<OutboxOp>;
+    /** `POST .../postpone` — shifts itinerary/stay-window dates server-side;
+     * never shifts pickup `scheduledTime`s (`08-treks.md`'s own "Does NOT"). */
+    readonly postpone: (input: PostponeTrekInput) => Promise<OutboxOp>;
+    /** `POST .../walk-ins/{walkInId}/reconcile` — the human fallback for a
+     * name-only walk-in the automatic CRM-phone match can't clear on its
+     * own. See this file's header for why this is exposed beyond
+     * `08-treks.md`'s own prop tables. */
+    readonly reconcileWalkIn: (walkInId: string, input: ReconcileTrekWalkInInput) => Promise<OutboxOp>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'treks'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useTreks(tripRef: string): DomainHookResult<TreksReady>;
+
+interface KaafilBrandAssets {
+    readonly appName?: string;
+    readonly logo?: string | ReactNode;
+    readonly logoMark?: string | ReactNode;
+    readonly favicon?: string;
+}
+interface BrandShellProps extends KaafilBrandAssets {
+    readonly headStrategy?: 'none' | 'own-page';
+    readonly children?: ReactNode;
+}
+/** Reads the brand assets `BrandShell` forwarded, or `{}` when mounted
+ * without one (never throws — brand is presentational, not load-bearing the
+ * way a session read is). */
+declare function useKaafilBrand(): KaafilBrandAssets;
+interface ShareMeta {
+    readonly title: string | undefined;
+    readonly favicon: string | undefined;
+    readonly ogTitle: string | undefined;
+    readonly ogDescription: string | undefined;
+    readonly ogImage: string | undefined;
+    readonly robots: 'noindex' | 'index';
+}
+/**
+ * Forwards brand assets unconditionally; enforces `headStrategy` before
+ * ever mounting `<KaafilDocumentHead>`. `'none'` is a HARD no-op — no
+ * branch below it ever touches `document.head`, even when `favicon`/
+ * `appName` are supplied. `'own-page'` is runtime-rejected under
+ * `agencyAdmin`/`manager` (dev throw, prod warning + silent `'none'`
+ * fallback — the same shape `useCapability()` uses for a wrong-persona call,
+ * `08-core-hooks.md §1.4`).
+ */
+declare function BrandShell({ appName, logo, logoMark, favicon, headStrategy, children, }: BrandShellProps): ReactNode;
+/**
+ * Shell-owned read-only alternative to `<KaafilDocumentHead>` — for a host
+ * (e.g. Next.js App Router) that already owns `<head>` via its own
+ * `metadata`/`generateMetadata` export and must keep `headStrategy="none"`
+ * here. Never writes the head itself; exactly one of the two paths is
+ * active per mount (`shells/06-brand-shell.md`).
+ */
+declare function useKaafilShareMeta(assets: KaafilBrandAssets): ShareMeta;
+
+/** A `module.group.key`-keyed document — the shape `seedConfig.tenant`/
+ * `seedConfig.agency` each carry (`shells/04-config-shell.md`'s `seedConfig`
+ * prop). Not exported from `../types` — this is `ConfigShell`'s own prop
+ * shape, not a `08-core-hooks.md`-catalogued type. */
+type ConfigDocument = Readonly<Record<string, unknown>>;
+interface ConfigShellProps {
+    readonly seedConfig?: {
+        readonly tenant?: ConfigDocument;
+        readonly agency?: ConfigDocument;
+    };
+    /** Accepted, not yet load-bearing — see this file's header DISCOVERY note. */
+    readonly refreshOn?: ReadonlyArray<'trip-load' | 'refocus' | 'snapshot-update'>;
+    readonly children?: ReactNode;
+}
+/**
+ * Builds `resolveSetting` over the two rungs of the precedence ladder this
+ * package can actually reach today (`shells/04-config-shell.md §"Agency
+ * settings are unreachable"`) — Agency narrows Tenant, Tenant is the seed's
+ * outer rung; neither Kaafil-default nor Partner has a browser-reachable
+ * read at all (`⛔ GAP-002`), so this shell does not fabricate either.
+ */
+declare function ConfigShell({ seedConfig, children }: ConfigShellProps): ReactNode;
+
+/** Discriminated per `00-decisions.md` U-014/U-003 — passing a `shareToken`
+ * alongside `agencyRef` is a compile error, never a shape this shell has to
+ * defensively validate at runtime. */
+type SessionShellCredential = {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly agencyRef: string;
+    readonly shareToken?: undefined;
+    readonly credentialResolver?: undefined;
+} | {
+    readonly shareToken: string;
+    readonly accessToken?: undefined;
+    readonly refreshToken?: undefined;
+    readonly agencyRef?: undefined;
+    readonly credentialResolver?: undefined;
+} | {
+    readonly credentialResolver: () => Promise<{
+        accessToken: string;
+        refreshToken: string;
+        agencyRef: string;
+    } | {
+        shareToken: string;
+    }>;
+    readonly accessToken?: undefined;
+    readonly refreshToken?: undefined;
+    readonly agencyRef?: undefined;
+    readonly shareToken?: undefined;
+};
+type SessionShellProps = SessionShellCredential & {
+    readonly environment?: Environment;
+    /** Forwarded into `session.open`'s/`admin.open`'s own `onRefresh` field —
+     * no-ops silently for a `share` credential, which has no refresh shape
+     * (`shells/02-session-shell.md`). */
+    readonly onRefresh?: (result: unknown) => void | Promise<void>;
+    readonly onSessionExpired?: (credentialKind: Persona) => void;
+    readonly children?: ReactNode;
+};
+/**
+ * Opens the credential the resolved value props imply, exposes
+ * `KaafilClientContext`/`SessionContext`, and latches `onSessionExpired` to
+ * fire exactly once per terminal expiry — see this file's header for why the
+ * actual event subscription happens one shell further in
+ * (`./internal/sessionExpiryBridge.ts`). `client.close()` runs on unmount and
+ * before any re-open — `KaafilClient` throws `KaafilClientAlreadyOpenError`
+ * on a second `open()` without an intervening `close()` (verified,
+ * `client-entry.ts`).
+ */
+declare function SessionShell(props: SessionShellProps): ReactNode;
+
+/**
+ * The discriminated union `09-telemetry-shell.md §"Event taxonomy"` owns —
+ * every field is an opaque id, an enum, or a count, never PII, never a money
+ * amount. This is the type's one home; a new event type is added to this
+ * union and to the table in that doc, nowhere else.
+ */
+type TelemetryEvent = {
+    readonly type: 'session.opened';
+    readonly timestamp: string;
+    readonly persona: string;
+} | {
+    readonly type: 'session.expired';
+    readonly timestamp: string;
+    readonly persona: string;
+} | {
+    readonly type: 'capability.darkened';
+    readonly timestamp: string;
+    readonly capability: string;
+    readonly reason: 'mode' | 'data' | 'flag';
+} | {
+    readonly type: 'sync.drained';
+    readonly timestamp: string;
+    readonly tripRef: string;
+    readonly pending: number;
+} | {
+    readonly type: 'sync.error';
+    readonly timestamp: string;
+    readonly tripRef: string;
+    readonly pending: number;
+} | {
+    readonly type: 'outbox.parked';
+    readonly timestamp: string;
+    readonly opId: string;
+    readonly code: string;
+} | {
+    readonly type: 'conflict.surfaced';
+    readonly timestamp: string;
+    readonly opId: string;
+} | {
+    readonly type: 'conflict.resolved';
+    readonly timestamp: string;
+    readonly opId: string;
+    readonly choice?: 'keep-queued' | 'keep-current';
+} | {
+    readonly type: 'error.caught';
+    readonly timestamp: string;
+    readonly classification: 'retryable' | 'parked' | 'isolation';
+    readonly code: string | undefined;
+} | {
+    readonly type: 'brand.headStrategyRejected';
+    readonly timestamp: string;
+    readonly persona: string;
+} | {
+    readonly type: 'frame.resolved';
+    readonly timestamp: string;
+    readonly frame: string;
+    readonly overridden: boolean;
+};
+interface TelemetryShellProps {
+    readonly onEvent?: (event: TelemetryEvent) => void;
+    readonly children?: ReactNode;
+}
+/**
+ * Wires the taxonomy's `session.opened`/`session.expired` rows off
+ * `useSession()`'s own status transitions — `useSession()` (hooks phase)
+ * already folds the underlying `session.expired`/`share.expired`/
+ * `share.revoked` offline events into its returned `status`
+ * (`../hooks/useSession.ts`), so watching `status` here is the one signal
+ * this shell needs, without a second, competing subscription to the same
+ * underlying event. The remaining taxonomy rows
+ * (`capability.darkened`/`sync.*`/`outbox.parked`/`conflict.*`/
+ * `error.caught`/`brand.headStrategyRejected`/`frame.resolved`) are defined
+ * in the `TelemetryEvent` union above (their one home) for the
+ * component-authoring phase's composites to emit into this same sink —
+ * this shell does not synthesize them itself before the events they
+ * describe exist to observe.
+ */
+declare function TelemetryShell({ onEvent, children }: TelemetryShellProps): ReactNode;
+
+type KaafilUIKitProviderCredential = SessionShellCredential;
+/** `defaultCapabilityViews` (`shells/00-kaafil-uikit-provider.md`'s props
+ * table) — a tree-wide DEFAULT for the three capability-dark view overrides
+ * `04-customization-ladder.md §5.1` defines. No composite exists yet to
+ * consume this (component authoring is out of scope for this phase), so
+ * this context is the provider's own seam for one to read later; it never
+ * changes which of the three treatments applies, only what a composite
+ * falls back to rendering when it hasn't set its own same-named prop. */
+interface DefaultCapabilityViews {
+    readonly modeDarkView?: ReactNode | ((ctx: unknown) => ReactNode);
+    readonly dataDarkView?: ReactNode | ((ctx: unknown) => ReactNode);
+    readonly flagDarkView?: ReactNode | ((ctx: unknown) => ReactNode);
+}
+/** Reads the tree-wide default set by `<KaafilUIKitProvider
+ * defaultCapabilityViews>` — `{}` when the provider didn't set one, never a
+ * required context (a missing default simply means every composite falls
+ * back to its own built-in dark treatment). */
+declare function useDefaultCapabilityViews(): DefaultCapabilityViews;
+interface KaafilUIKitProviderProps {
+    readonly environment?: Environment;
+    readonly onSessionExpired?: (credentialKind: Persona) => void;
+    readonly density?: 'compact' | 'default' | 'comfortable';
+    readonly theme?: 'light' | 'dark' | 'system';
+    readonly brand?: KaafilBrandAssets & {
+        readonly headStrategy?: 'none' | 'own-page';
+    };
+    readonly locale?: string;
+    readonly isolation?: 'scoped' | 'shadow';
+    readonly onEvent?: (event: TelemetryEvent) => void;
+    readonly storage?: KaafilStorageAdapter;
+    readonly blob?: {
+        readonly uploader: BlobUploader;
+        readonly source: BlobSource;
+    };
+    readonly conflictResolver?: ConflictResolver;
+    readonly readEntity?: EntityReader;
+    readonly offlineScope?: string;
+    readonly seedConfig?: {
+        readonly tenant?: ConfigDocument;
+        readonly agency?: ConfigDocument;
+    };
+    readonly defaultCapabilityViews?: DefaultCapabilityViews;
+    readonly children?: ReactNode;
+}
+type KaafilUIKitProviderCredentialProps = KaafilUIKitProviderCredential & KaafilUIKitProviderProps;
+/**
+ * Composes `ErrorShell → ThemeShell → I18nShell → AppShell → SessionShell →
+ * OfflineShell → ConfigShell → BrandShell → TelemetryShell → {children}`,
+ * the locked order (`shells/README.md §2`). No `persona` prop, no `mode`
+ * prop, no `sessionEndpoint` — the credential union above is the only way
+ * in, as VALUES (`00-decisions.md` U-003, U-014).
+ */
+declare function KaafilUIKitProvider(props: KaafilUIKitProviderCredentialProps): ReactNode;
+
+/**
+ * A type-keyed registry: `register`/`resolve`, resolved by lookup, never a
+ * `switch`/`if-else` chain (`09-registries.md §1` rule 1). `resolve` is
+ * documented as "internal; called by the composite that owns the registry
+ * per row/item/kind it renders" (§1's registration-signature note) — this
+ * factory does not itself enforce that a consumer never calls `resolve`
+ * from outside a composite, because there is no way to do so at the type
+ * level without either a second module boundary per registry or a runtime
+ * check with no way to tell "composite" from "integrator code" apart; the
+ * convention is enforced by which files ever call it, not by this factory.
+ */
+interface Registry<TKey extends string, THandler> {
+    /**
+     * Registers `handler` under `key`. Rule 2 (`09-registries.md §1`): the
+     * LAST registration for a given key wins — a custom registration
+     * overwrites a built-in one, and a re-registration of an already-custom
+     * key overwrites that too. There is no "first registration wins" mode and
+     * no error on re-registering an existing key, because tier-4/5
+     * customization (`04-customization-ladder.md`) depends on exactly this
+     * being silent and total.
+     */
+    register(key: TKey, handler: THandler): void;
+    /**
+     * Resolves `key` to its registered handler, or the `default` fallback
+     * (rule 3) when `key` has no registration — because the engine shipped a
+     * new kind this build predates, or an integrator's custom kind rode an
+     * key nothing here anticipated. Never throws and never returns
+     * `undefined` — the fallback registration (seeded at `createRegistry()`
+     * time) guarantees a resolve is always total.
+     */
+    resolve(key: TKey): THandler;
+    /**
+     * Every key currently registered, fallback excluded — for a composite
+     * that needs to enumerate what's registered (a settings UI listing
+     * overridable kinds), never for resolving one row's dispatch (that is
+     * always `resolve`, so a row from an unregistered kind still renders).
+     */
+    registeredKeys(): readonly TKey[];
+}
+interface CreateRegistryOptions<THandler> {
+    /**
+     * The `default` registration (`09-registries.md §1` rule 3: "the fallback
+     * is itself a registration under a reserved `default` key, so it inherits
+     * the same override mechanism as every other entry rather than being
+     * special-cased in the resolver"). A consumer MAY later call
+     * `register('default' as TKey, …)` to replace it wholesale, the same way
+     * any other key can be overridden — this factory does not special-case
+     * that call either.
+     */
+    readonly fallback: THandler;
+}
+/**
+ * Builds one registry instance. `TKey` is left to the caller as a string
+ * literal union (`FormFieldKind`, `BlockerKey`, …) or a plain `string` for a
+ * genuinely open set — this factory does not require the union to be
+ * closed, which is exactly what lets a consumer "register a new key without
+ * a PR" against this package.
+ */
+declare function createRegistry<TKey extends string, THandler>(options: CreateRegistryOptions<THandler>): Registry<TKey, THandler>;
+
+/** A desk/field screen scoped to one trip. `tripRef` is the host's own
+ * external id OR a Kaafil id — every `:ref` route accepts either, and the
+ * UIKit never asks a host to resolve one into the other first. */
+interface TripScopedParams {
+    readonly tripRef: string;
+    /** One of the trip workspace's own tab keys. Optional: absent means the
+     * surface picks its own landing tab. */
+    readonly initialTab?: KaafilTripTabKey;
+}
+/** An agency-wide desk screen. There is deliberately no `agencyRef`: scope
+ * comes from the open credential, never a route param (`00-decisions.md`
+ * U-003). */
+interface AgencyScopedParams {
+    readonly initialPane?: string;
+}
+/** The public share surface. `token` is the opaque value from the share
+ * link's own URL — never a traveller id, never a trip ref. */
+interface ShareParams {
+    readonly token: string;
+}
+/** The two props introduced by the deep-link table itself. Both are bare
+ * props on the receiving screen — they carry scope and behaviour, not
+ * presentation, so neither is a `components`/`*Slot` key. */
+interface DeepLinkParams {
+    /** The row the destination must scroll to and focus on arrival. */
+    readonly highlightId?: string;
+    /** A named filter preset the destination flow already exposes. The screen
+     * passes it straight through; the UIKit has no filter language of its
+     * own. */
+    readonly presetFilter?: string;
+}
+type KaafilTripTabKey = 'itinerary' | 'pickups' | 'rooming' | 'vehicles' | 'vendors' | 'payments' | 'expenses' | 'float' | 'checklist' | 'forms';
+/**
+ * The engine's own route hints (`closing-day.constants.ts#
+ * CLOSEOUT_BLOCKER_ACTION_KEYS`), and the value a caller routes on.
+ *
+ * ROUTE ON `actionKey`, NEVER ON `key` OR THE COPY. The engine says so
+ * outright — "the route hint the FE navigates on, so it never parses copy"
+ * — and the titles are explicitly free to be reworded.
+ */
+type CloseoutActionKey = 'open_checklist' | 'open_collections' | 'open_expenses' | 'open_float' | 'open_forms' | 'open_itinerary' | 'open_mandatory_checklist' | 'open_past_itinerary' | 'open_pickups' | 'open_rooming' | 'open_seating' | 'open_vendors';
+/** The blocker keys the engine can emit (`CloseoutBlockerKey`). Accepted as
+ * an optional refinement below — see `resolveBlockerDeepLink`. */
+type CloseoutBlockerKey = 'balance_due' | 'missing_receipt' | 'float_not_returned' | 'open_mandatory_checklist' | 'required_form_gap' | 'unassigned_rooming' | 'unseated_travellers' | 'pickup_no_show' | 'reimbursements_pending' | 'unrated_vendors' | 'open_past_itinerary';
+/**
+ * `actionKey` → the tab that clears the row.
+ *
+ * A type-keyed record (hard rule #8), total over the union so a new engine
+ * action key is a compile error here rather than a row whose jump silently
+ * does nothing.
+ */
+declare const CLOSEOUT_ACTION_TAB: Readonly<Record<CloseoutActionKey, KaafilTripTabKey>>;
+/** What a caller should do with a blocker row's action. */
+interface BlockerDeepLink extends DeepLinkParams {
+    readonly tab: KaafilTripTabKey;
+}
+interface ResolveBlockerInput {
+    /** The engine's route hint. The one required field. */
+    readonly actionKey: string;
+    /** The blocker's own key, when the caller has the whole row. Refines the
+     * filter only; it never changes the tab. */
+    readonly key?: string;
+    /** Passed through untouched when the caller knows which row to focus —
+     * typically only when the blocker's `count` is 1. */
+    readonly highlightId?: string;
+}
+/**
+ * Resolve one blocker row into a destination, or `null` for a row that has
+ * nowhere to send anyone.
+ *
+ * `null` IS A REAL ANSWER AND MUST BE HANDLED — render the row's own
+ * statement with no jump, never a control that goes nowhere. It happens for
+ * an `actionKey` this build has no tab for (a later engine adding one), and
+ * for a tab this trip does not have.
+ *
+ * ── TWO ROWS THE SPEC AND THE ENGINE DISAGREE ABOUT ──────────────────────
+ *
+ * `shared/00-routing-and-deeplinks.md §3` says `reimbursements_pending`
+ * "never navigates" (resolved by CRM back-office, out of band) and that
+ * `unrated_vendors` is unbuildable (`GAP-005`). The ENGINE assigns both an
+ * `actionKey` anyway — `open_expenses` and `open_vendors` — on its own
+ * stated principle that "a row pointing at NO screen is a row a manager
+ * cannot act on".
+ *
+ * This follows the engine, because the engine is what actually ships the
+ * row, and both destinations are defensible: the expenses tab shows claim
+ * status read-only, which IS where you look to see where a reimbursement
+ * got to, and the vendors tab is where a rating would live. In practice
+ * neither costs anything — `unrated_vendors` is never emitted at all (the
+ * engine has no vendor-rating source to probe), and `reimbursements_pending`
+ * lands unfiltered by the note in `BLOCKER_PRESET_FILTER`.
+ */
+declare function resolveBlockerDeepLink(input: ResolveBlockerInput): BlockerDeepLink | null;
+/**
+ * A deep link → query params, for a host that wants to put one in a URL.
+ *
+ * Returns a FRESH `URLSearchParams` carrying only this link's own keys — it
+ * never mutates an input, so a caller merges it into their own query string
+ * on their own terms rather than having this decide what else survives.
+ */
+declare function toSearchParams(link: Partial<BlockerDeepLink>): URLSearchParams;
+/**
+ * Query params → the props a surface takes, or `null` when the query carries
+ * no Kaafil deep link at all.
+ *
+ * `null` rather than an empty object, so `if (link)` is enough to tell "this
+ * URL addresses a Kaafil surface" from "it does not" — a host's own router
+ * will hand this every query string it sees, most of which are none of our
+ * business.
+ *
+ * AN UNKNOWN TAB IS DROPPED, not passed through. The value came from a URL,
+ * which is user-editable; handing an arbitrary string to a surface as a tab
+ * key would put unvalidated input into a registry lookup. `highlightId` and
+ * `presetFilter` ARE passed through as-is — they are opaque by contract, and
+ * the destination flow is what decides whether either matches anything.
+ */
+declare function fromSearchParams(params: URLSearchParams): (DeepLinkParams & {
+    readonly initialTab?: KaafilTripTabKey;
+}) | null;
+/** Narrows a string off a URL to the shared tab vocabulary. Exported because
+ * a host validating its own route params wants the same check. */
+declare function isTripTabKey(value: string | null | undefined): value is KaafilTripTabKey;
+
+type AppShellFamily = 'admin' | 'manager' | 'traveller';
+type AppShellFrame = 'desk' | 'field' | 'document';
+interface AppShellProps {
+    readonly frame?: AppShellFrame;
+    readonly family?: AppShellFamily;
+    readonly isolation?: 'scoped' | 'shadow';
+    readonly navSlot?: ReactNode;
+    readonly actionBarSlot?: ReactNode;
+    readonly connectivitySlot?: ReactNode;
+    readonly children?: ReactNode;
+    /**
+     * Per-instance `--kf-*` token overrides (`00-decisions.md` U-019). Layer-3
+     * tokens are per component TYPE; this is how one INSTANCE differs from
+     * another without restyling every sibling. On a shell this is also the
+     * per-SUBTREE scope: custom properties inherit, so tokens set here reach
+     * every descendant — including across the shadow-DOM boundary in
+     * `isolation="shadow"` mode, since custom-property inheritance follows
+     * the flat tree from a shadow host into its shadow root (unlike ordinary
+     * selector-based CSS, which does not cross that boundary). `.kf-root`
+     * here is either the shadow host itself, or a light-DOM ancestor of it —
+     * both cases inherit normally, so `style` lands once, on this outermost
+     * node, never needing to be re-applied inside `ShadowIsolationBoundary`.
+     */
+    readonly style?: KaafilTokenOverrides;
+}
+/**
+ * Establishes `.kf-root`, the resolved `frame` shape, the CSS-isolation
+ * rung, and the container-query root. Renders unconditionally — never
+ * withholds `{children}` behind a loading gate (`shells/README.md §1`).
+ */
+declare function AppShell({ frame, family, isolation, navSlot, actionBarSlot, connectivitySlot, children, style, }: AppShellProps): ReactNode;
+
+type ErrorShellClassification = 'retryable' | 'parked' | 'isolation';
+interface ErrorShellFallbackContext {
+    readonly classification: ErrorShellClassification;
+    readonly code: string | undefined;
+}
+interface ErrorShellProps {
+    readonly fallbackSlot?: (ctx: ErrorShellFallbackContext) => ReactNode;
+    readonly children?: ReactNode;
+}
+interface ErrorShellState {
+    readonly caught: {
+        readonly error: unknown;
+    } | null;
+    readonly retryKey: number;
+}
+/**
+ * Catches a thrown render error from anything beneath it. Never consumes
+ * `ThemeShell`/`I18nShell` context in its own fallback, never retries a
+ * `parked`/`isolation` classification, and never offers an admin override
+ * for a classified `423`/`402`/`422`.
+ */
+declare class ErrorShell extends Component<ErrorShellProps, ErrorShellState> {
+    state: ErrorShellState;
+    static getDerivedStateFromError(error: unknown): Partial<ErrorShellState>;
+    private handleRetry;
+    render(): ReactNode;
+}
+
+type HostCssHazard = 'global-box-sizing-reset' | 'global-button-input-unset' | 'tailwind-preflight-after-ours' | 'global-margin-padding-reset' | 'conflicting-layer-order' | 'global-img-max-width' | 'host-css-reset-library' | 'global-focus-outline-removed';
+interface HostCssCompatibilityProbeProps {
+    /**
+     * Per-instance `--kf-*` token overrides (`00-decisions.md` U-019). Layer-3
+     * tokens are per component TYPE; this is how one INSTANCE differs from
+     * another without restyling every sibling.
+     */
+    readonly style?: KaafilTokenOverrides;
+}
+/** Dev-only per `05-theming-and-branding.md §7` — a no-op in production,
+ * with a dev-only warning at the ONE other place `isDevelopment()` reads
+ * false-negatively (a production build accidentally shipping this probe). */
+declare function HostCssCompatibilityProbe({ style, }?: HostCssCompatibilityProbeProps): ReactNode;
+
+type ChromeLocale = 'en' | 'hi';
+
+interface I18nContextValue {
+    readonly locale: ChromeLocale;
+    /** The host's own, possibly-unrecognised BCP-47 tag — kept alongside the
+     * resolved `ChromeLocale` so a consumer can tell "we're rendering en
+     * because the host asked for en" apart from "we're rendering en because
+     * the host's tag has no shipped sibling catalog" without this context
+     * lying about which locale is actually active. */
+    readonly requestedLocale: string;
+    readonly t: (key: string) => string;
+}
+
+interface I18nShellProps {
+    /** BCP-47 tag. No `Accept-Language` sniff, no `Traveller.locale` read —
+     * the host is the one party that already knows which locale its user or
+     * traveller wants (`13-i18n-and-formatting.md §3.3`). */
+    readonly locale?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * Resolves the active locale's chrome catalog synchronously — the catalog
+ * ships inside the package bundle (`shells/07-i18n-shell.md`'s own "Offline"
+ * field), so there is no loading state for a descendant to observe.
+ */
+declare function I18nShell({ locale, children }: I18nShellProps): ReactNode;
+/**
+ * `I18nShell`'s own reader — shell-owned, not a `08-core-hooks.md` catalog
+ * entry (no chrome-translation hook is named there; component authoring,
+ * this hook's eventual consumer, is out of scope for this phase). Mirrors
+ * `BrandShell`'s `useKaafilShareMeta()` in kind: a read-only hook a shell
+ * exposes alongside itself. Throws outside the provider tree, the same
+ * "no provider, no default" contract every `/core` context follows.
+ */
+declare function useKaafilChrome(): I18nContextValue;
+
+interface KaafilSessionProbeProps {
+    /** The host's own intended environment — cross-checked against the
+     * opened credential's actual `environment` to catch "wrong environment"/
+     * "test key on live" (`shells/00-kaafil-uikit-provider.md`). */
+    readonly expectedEnvironment?: 'live' | 'test';
+    /**
+     * Per-instance `--kf-*` token overrides (`00-decisions.md` U-019). Layer-3
+     * tokens are per component TYPE; this is how one INSTANCE differs from
+     * another without restyling every sibling.
+     */
+    readonly style?: KaafilTokenOverrides;
+}
+/**
+ * When green: a card naming credential kind, environment, and status. When
+ * red: names exactly ONE of the five documented failure modes this probe
+ * exists to distinguish — this build can only detect the two that are
+ * directly readable off `useSession()`'s derived shape (an expired/rejected
+ * credential, and an environment mismatch); "clock skew" and "CORS" need a
+ * live network probe this component does not attempt on its own, so they
+ * are named here as documented, undetected-by-this-build failure modes
+ * rather than silently omitted from the contract.
+ */
+declare function KaafilSessionProbe({ expectedEnvironment, style, }: KaafilSessionProbeProps): ReactNode;
+
+interface OfflineShellProps {
+    readonly storage: KaafilStorageAdapter;
+    readonly blob?: {
+        readonly uploader: BlobUploader;
+        readonly source: BlobSource;
+    };
+    readonly conflictResolver?: ConflictResolver;
+    readonly readEntity?: EntityReader;
+    /** Escalation-tier override — see `shells/03-offline-shell.md`'s own
+     * warning about two concurrently-open credentials sharing one browser's
+     * storage. Defaults to a scope derived from persona + agencyRef, never
+     * the credential secret itself. */
+    readonly scope?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * Opens the one `OfflineEngine` for the open session's credential, once
+ * `SessionShell`'s credential exists — `OpenOfflineOptions` cannot be shaped
+ * before that (`shells/README.md §2` row 6's rationale). Closes the previous
+ * engine and opens a fresh one on a genuine credential change (a different
+ * agency, a re-minted share token); an ordinary silent token rotation never
+ * reaches this effect at all (`shells/03-offline-shell.md`'s "Credential
+ * binding and credential change" section).
+ */
+declare function OfflineShell({ storage, blob, conflictResolver, readEntity, scope, children, }: OfflineShellProps): ReactNode;
+
+interface ThemeShellProps {
+    readonly theme?: 'light' | 'dark' | 'system';
+    readonly density?: 'compact' | 'default' | 'comfortable';
+    readonly children?: ReactNode;
+}
+/**
+ * Resolves theme/density synchronously, during render — not behind a
+ * `useEffect`, so there is no theme-loading flash for a descendant to
+ * observe (`05-theme-shell.md`'s "no theme-loading state" contract). Only
+ * `theme="system"` needs a live subscription, to follow the OS preference
+ * across a change while mounted; an explicit `"light"`/`"dark"` is used
+ * immediately and never touches `matchMedia` at all.
+ */
+declare function ThemeShell({ theme, density, children }: ThemeShellProps): ReactNode;
+
+export { type AddTravellerNoteInput, type AgencyAdminMeReady, type AgencyAdminMeResult, type AgencyManagerProfileResult, type AgencyScopedParams, AppShell, type AppShellFamily, type AppShellFrame, type AppShellProps, type BlobStatusResult, type BlockerDeepLink, type BookingsReady, BrandShell, type BrandShellProps, CLOSEOUT_ACTION_TAB, type CapabilityStatusesResult, CapabilityTriple, type CloseoutActionKey, type CloseoutBlockerKey, type ConfigDocument, ConfigShell, type ConfigShellProps, ConflictRecord, type ConflictsResult, type CreateRegistryOptions, type DeepLinkParams, type DefaultCapabilityViews, DomainHookResult, ErrorClassification, ErrorShell, type ErrorShellClassification, type ErrorShellFallbackContext, type ErrorShellProps, type FeedbackNpsReady, type FeedbackNpsScope, HostCssCompatibilityProbe, type HostCssHazard, I18nShell, type I18nShellProps, type JourneyResult, type KaafilBrandAssets, KaafilSessionProbe, type KaafilSessionProbeProps, type KaafilTripTabKey, KaafilUIKitProvider, type KaafilUIKitProviderCredential, type KaafilUIKitProviderCredentialProps, type KaafilUIKitProviderProps, type ManagerAgencyProfileRead, type ManagersResult, NotImplementedError, type OfflineMutationConfig, type OfflineMutationResult, type OfflineMutationStatus, OfflineShell, type OfflineShellProps, type OutboxStatusOptions, type OutboxStatusResult, type Persona, type Registry, type ResolveBlockerInput, type ServerTimeApi, SessionShell, type SessionShellCredential, type SessionShellProps, type SessionState, type ShareFormAnswer, type ShareFormListItem, type ShareFormWriteInput, type ShareFormsListStatus, type ShareFormsResult, type ShareFormsWriteStatus, type ShareLinkRow, type ShareLinksResult, type ShareMeta, type ShareParams, type ShareSectionKey, type ShareSections, type ShareSnapshotOptions, type ShareSnapshotResult, type ShareSnapshotTrip, type SnapshotEntityResult, type SnapshotListResult, StalenessState, type TelemetryEvent, TelemetryShell, type TelemetryShellProps, ThemeShell, type ThemeShellProps, type TravellerFormResponseRow, type TravellerProfileRead, type TravellerProfileResult, type TreksReady, type TripManagerRow, type TripScopedParams, createRegistry, fromSearchParams, isTripTabKey, resolveBlockerDeepLink, toSearchParams, useAgencyAdminMe, useAgencyManagerProfile, useBlobStatus, useBookings, useCapabilities, useCapability, useCapabilityStatuses, useConflicts, useDefaultCapabilityViews, useFeedbackNps, useJourney, useKaafilBrand, useKaafilChrome, useKaafilShareMeta, useManagers, useOfflineEngine, useOfflineEvent, useOfflineMutation, useOutboxStatus, usePersona, useResolvedSetting, useServerTime, useSession, useShareForms, useShareLinks, useShareSnapshot, useSnapshotEntity, useSnapshotList, useStaleness, useTravellerFormResponses, useTravellerProfile, useTreks };