kaafil-react-uikit 0.1.0-beta.1

package/dist/core/index.js

@@ -0,0 +1,995 @@
+export { useConflicts, useManagerMe, useNotifications } from '../chunk-YDGR7JSY.js';
+export { CLOSEOUT_ACTION_TAB, fromSearchParams, isTripTabKey, resolveBlockerDeepLink, toSearchParams, useAgencyAdminMe, useAgencyChecklistTemplates, useAgencyForms, useAgencyJourneyTriggers, useAgencyManagerProfile, useAgencySettings, useAgencyTrip, useAgencyTripManifest, useAgencyTrips, useBookings, useCapabilityStatuses, useDirectories, usePaginatedList, useShareLinks, useTravellerFormResponses } from '../chunk-UUGMNP27.js';
+import { createDomainHook, useSnapshotList, classifyError } from '../chunk-UYJ6LIWP.js';
+export { ERROR_HANDLING_PATH, classifyError, useChecklists, useCloseout, useCollections, useExpenses, useFiles, useFloat, useForms, useItinerary, useManagerToday, useManagers, useParties, usePickups, useRooming, useSeating, useSnapshotList, useTravellerProfile, useVendors } from '../chunk-UYJ6LIWP.js';
+import { BrandShell } from '../chunk-WUAFL77X.js';
+export { BrandShell, useKaafilBrand, useKaafilShareMeta, useShareForms, useShareSnapshot } from '../chunk-WUAFL77X.js';
+export { useOfflineEngine } from '../chunk-PZKXLQSU.js';
+import { useServerTime } from '../chunk-XI7MK4Y7.js';
+export { useServerTime } from '../chunk-XI7MK4Y7.js';
+import { useKaafilClient, useOfflineMutation, OfflineEngineContext, useOfflineEvent, usePersona, useCapabilityRows, isDevelopment, deriveCapabilityTriple, useRequiredContext, ConfigContext, tokenStyle, KaafilClientContext, useSession, SessionContext, I18nShell, useKaafilChrome } from '../chunk-6FPAGGFL.js';
+export { I18nShell, createRegistry, useCapabilities, useCapability, useKaafilChrome, useKaafilClient, useOfflineEvent, useOfflineMutation, useOutboxStatus, usePersona, useSession } from '../chunk-6FPAGGFL.js';
+import { SyncOpMethod, KaafilClient } from 'kaafil-js/client';
+export { UnsatisfiableSchemeError } from 'kaafil-js/client';
+import { useState, useCallback, useEffect, createContext, useContext, useRef, useMemo, Component, Fragment } from 'react';
+import { createPortal } from 'react-dom';
+import { jsx, Fragment as Fragment$1, jsxs } from 'react/jsx-runtime';
+
+var NotImplementedError = class _NotImplementedError extends Error {
+  hookName;
+  specSection;
+  constructor(hookName, specSection) {
+    super(
+      `${hookName}() has no implementation in this build yet \u2014 see 08-core-hooks.md ${specSection} for its full signature and SDK binding.`
+    );
+    this.name = "NotImplementedError";
+    Object.setPrototypeOf(this, _NotImplementedError.prototype);
+    this.hookName = hookName;
+    this.specSection = specSection;
+  }
+};
+function useBlobStatus(blobId) {
+  const engine = useContext(OfflineEngineContext);
+  const [, forceRefresh] = useState(0);
+  useOfflineEvent("sync.drained", () => forceRefresh((tick) => tick + 1));
+  useOfflineEvent("sync.error", () => forceRefresh((tick) => tick + 1));
+  const record = engine?.blobs?.all().find((candidate) => candidate.id === blobId);
+  if (record === void 0) {
+    return { status: "pending", progress: void 0 };
+  }
+  const status = record.status === "confirmed" ? "ready" : record.status === "parked" ? "orphaned" : record.attemptCount > 0 ? "uploading" : "pending";
+  return { status, progress: void 0 };
+}
+function useFeedbackNps(scope) {
+  const client = useKaafilClient();
+  const [summary, setSummary] = useState(void 0);
+  const [definitions, setDefinitions] = useState([]);
+  const [loaded, setLoaded] = useState(false);
+  const [lastFetchFailed, setLastFetchFailed] = useState(false);
+  const [syncedAt, setSyncedAt] = useState(void 0);
+  const formIdRef = useRef(void 0);
+  const refresh = useCallback(async () => {
+    try {
+      if (scope.kind === "trip") {
+        const response = await client.feedbackNps.trip({ tripRef: scope.tripRef });
+        setSummary(response.data);
+        formIdRef.current = response.data.configured ? response.data.formId : void 0;
+        setLoaded(true);
+        setLastFetchFailed(false);
+        setSyncedAt(response.meta.serverTime);
+      } else {
+        const response = await client.feedbackNps.agency({});
+        setDefinitions(response.data.definitions);
+        setLoaded(true);
+        setLastFetchFailed(false);
+        setSyncedAt(response.meta.serverTime);
+      }
+    } catch {
+      setLastFetchFailed(true);
+    }
+  }, [client, scope.kind, scope.kind === "trip" ? scope.tripRef : scope.agencyRef]);
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+  const dispatchMutation = useOfflineMutation({
+    tripRef: scope.kind === "trip" ? scope.tripRef : "",
+    enqueue: (engine, input) => {
+      const formId = formIdRef.current;
+      if (formId === void 0 || scope.kind !== "trip") {
+        throw new Error("useFeedbackNps: cannot dispatch before a feedback form is resolved");
+      }
+      return engine.enqueue({
+        tripRef: scope.tripRef,
+        method: SyncOpMethod.Post,
+        path: `/api/v1/trips/${scope.tripRef}/forms/${formId}/dispatch`,
+        // Hardcoded literal, not imported: `OperationId` is not exported
+        // from `kaafil-js/client`'s public surface — same convention as
+        // `useRooming.ts`'s own `'assignRoomingBed' as never`. Verified
+        // against `kaafil-js/src/generated/security.ts`
+        // (`OPERATION_SECURITY.dispatchForm`) this session.
+        operationId: "dispatchForm",
+        body: input ?? {}
+      });
+    }
+  });
+  const dispatchMutate = dispatchMutation.mutate;
+  const dispatch = useCallback(
+    async (input) => {
+      const op = await dispatchMutate(input ?? {});
+      void refresh();
+      return op;
+    },
+    [dispatchMutate, refresh]
+  );
+  return {
+    kind: scope.kind,
+    summary,
+    definitions,
+    loaded,
+    lastFetchFailed,
+    syncedAt,
+    refresh,
+    dispatch,
+    dispatchStatus: dispatchMutation.status,
+    dispatchOp: dispatchMutation.op
+  };
+}
+function useJourney(tripRef) {
+  const client = useKaafilClient();
+  const persona = usePersona();
+  const { rows } = useCapabilityRows(tripRef);
+  const [read, setRead] = useState(void 0);
+  const [liveRows, setLiveRows] = useState(void 0);
+  useEffect(() => {
+    if (persona === "share") {
+      if (isDevelopment()) {
+        throw new Error(
+          "useJourney() was called from a share session \u2014 it is manager/agencyAdmin only (08-core-hooks.md \xA73.2)."
+        );
+      }
+      return;
+    }
+    let cancelled = false;
+    void client.journey.get({ tripRef }).then((response) => {
+      if (!cancelled) {
+        setRead(response);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, persona, tripRef]);
+  const refreshCapabilities = useCallback(async () => {
+    const response = await client.journey.capabilities({ tripRef, live: true });
+    setLiveRows(response);
+  }, [client, tripRef]);
+  const effectiveRows = liveRows ?? rows;
+  const capabilities = /* @__PURE__ */ new Map();
+  for (const row of effectiveRows) {
+    capabilities.set(row.capability, deriveCapabilityTriple(row));
+  }
+  return {
+    read,
+    capabilities,
+    refreshCapabilities,
+    triggers: {
+      list: (options) => client.journey.triggers.list(options),
+      patch: (options) => client.journey.triggers.patch(options)
+    }
+  };
+}
+
+// src/core/hooks/useResolvedSetting.ts
+function useResolvedSetting(key) {
+  const config = useRequiredContext(ConfigContext, "useResolvedSetting", "ConfigShell");
+  return config.resolveSetting(key);
+}
+function useSnapshotEntity(tripRef, listName, id) {
+  const engine = useContext(OfflineEngineContext);
+  const { rows } = useSnapshotList(tripRef, listName);
+  const row = rows.find((candidate) => candidate.id === id);
+  const syncedAt = engine === null ? void 0 : engine.snapshot.syncedAt(tripRef, listName, id);
+  return { row, syncedAt };
+}
+
+// src/core/hooks/useStaleness.ts
+function useStaleness(tripRef, listName) {
+  const { syncedAt } = useSnapshotList(tripRef, listName);
+  const { now } = useServerTime();
+  const thresholdSeconds = useResolvedSetting("stale.thresholdSeconds.default");
+  if (syncedAt === void 0) {
+    return { syncedAt: void 0, ageSeconds: void 0, isStale: false };
+  }
+  let ageSeconds;
+  try {
+    ageSeconds = (Date.parse(now()) - Date.parse(syncedAt)) / 1e3;
+  } catch {
+    ageSeconds = void 0;
+  }
+  const isStale = ageSeconds !== void 0 && thresholdSeconds !== void 0 && ageSeconds > thresholdSeconds;
+  return { syncedAt, ageSeconds, isStale };
+}
+var WALK_INS_PAGE_SIZE = 25;
+var useTreksInternal = createDomainHook("treks", (tripRef) => {
+  const client = useKaafilClient();
+  const [boardData, setBoardData] = useState(void 0);
+  const [boardLoaded, setBoardLoaded] = useState(false);
+  const [boardFetchFailed, setBoardFetchFailed] = useState(false);
+  const [boardFetchedAt, setBoardFetchedAt] = useState(void 0);
+  const refreshBoard = useCallback(async () => {
+    try {
+      const response = await client.treks.board({ trekRef: tripRef });
+      setBoardData(response);
+      setBoardLoaded(true);
+      setBoardFetchFailed(false);
+      setBoardFetchedAt(response.meta.serverTime);
+    } catch {
+      setBoardFetchFailed(true);
+    }
+  }, [client, tripRef]);
+  useEffect(() => {
+    void refreshBoard();
+  }, [refreshBoard]);
+  const [walkInRows, setWalkInRows] = useState([]);
+  const [walkInsLoaded, setWalkInsLoaded] = useState(false);
+  const [walkInsFetchFailed, setWalkInsFetchFailed] = useState(false);
+  const [walkInsFetchedAt, setWalkInsFetchedAt] = useState(void 0);
+  const [walkInsCursor, setWalkInsCursor] = useState(void 0);
+  const [walkInsHasNext, setWalkInsHasNext] = useState(false);
+  const refreshWalkIns = useCallback(async () => {
+    try {
+      const page = await client.treks.walkIns.listPage({
+        trekRef: tripRef,
+        limit: WALK_INS_PAGE_SIZE
+      });
+      setWalkInRows(page);
+      setWalkInsLoaded(true);
+      setWalkInsFetchFailed(false);
+      setWalkInsFetchedAt(page.meta.serverTime);
+      setWalkInsCursor(page.meta.page.cursor ?? void 0);
+      setWalkInsHasNext(page.meta.page.hasNext);
+    } catch {
+      setWalkInsFetchFailed(true);
+    }
+  }, [client, tripRef]);
+  const loadMoreWalkIns = useCallback(async () => {
+    if (walkInsCursor === void 0 || !walkInsHasNext) {
+      return;
+    }
+    try {
+      const page = await client.treks.walkIns.listPage({
+        trekRef: tripRef,
+        cursor: walkInsCursor,
+        limit: WALK_INS_PAGE_SIZE
+      });
+      setWalkInRows((existing) => [...existing, ...page]);
+      setWalkInsFetchedAt(page.meta.serverTime);
+      setWalkInsCursor(page.meta.page.cursor ?? void 0);
+      setWalkInsHasNext(page.meta.page.hasNext);
+    } catch {
+      setWalkInsFetchFailed(true);
+    }
+  }, [client, tripRef, walkInsCursor, walkInsHasNext]);
+  useEffect(() => {
+    void refreshWalkIns();
+  }, [refreshWalkIns]);
+  const [metaData, setMetaData] = useState(void 0);
+  const [metaLoaded, setMetaLoaded] = useState(false);
+  const [metaFetchFailed, setMetaFetchFailed] = useState(false);
+  const refreshMeta = useCallback(async () => {
+    try {
+      const response = await client.treks.walkIns.meta({ trekRef: tripRef });
+      setMetaData(response);
+      setMetaLoaded(true);
+      setMetaFetchFailed(false);
+    } catch {
+      setMetaFetchFailed(true);
+    }
+  }, [client, tripRef]);
+  useEffect(() => {
+    void refreshMeta();
+  }, [refreshMeta]);
+  const createWalkInMutation = useOfflineMutation({
+    tripRef,
+    enqueue: (engine, input) => engine.enqueue({
+      tripRef,
+      method: SyncOpMethod.Post,
+      path: `/api/v1/treks/${tripRef}/walk-ins`,
+      // `OperationId` is not exported from `kaafil-js/client`'s public
+      // surface — same documented gap `useFloat.ts`/`useRooming.ts` cast
+      // around for their own literal `operationId`s.
+      operationId: "createTrekWalkIn",
+      body: input
+    })
+  });
+  const postponeMutation = useOfflineMutation({
+    tripRef,
+    enqueue: (engine, input) => engine.enqueue({
+      tripRef,
+      method: SyncOpMethod.Post,
+      path: `/api/v1/treks/${tripRef}/postpone`,
+      operationId: "postponeTrek",
+      body: input
+    })
+  });
+  const reconcileMutation = useOfflineMutation({
+    tripRef,
+    enqueue: (engine, { walkInId, input }) => engine.enqueue({
+      tripRef,
+      method: SyncOpMethod.Post,
+      path: `/api/v1/treks/${tripRef}/walk-ins/${walkInId}/reconcile`,
+      operationId: "reconcileTrekWalkIn",
+      body: input
+    })
+  });
+  const createWalkInMutate = createWalkInMutation.mutate;
+  const createWalkIn = useCallback(
+    async (input) => {
+      const op = await createWalkInMutate(input);
+      void refreshBoard();
+      void refreshWalkIns();
+      return op;
+    },
+    [createWalkInMutate, refreshBoard, refreshWalkIns]
+  );
+  const postponeMutate = postponeMutation.mutate;
+  const postpone = useCallback(
+    async (input) => {
+      const op = await postponeMutate(input);
+      void refreshBoard();
+      return op;
+    },
+    [postponeMutate, refreshBoard]
+  );
+  const reconcileMutate = reconcileMutation.mutate;
+  const reconcileWalkIn = useCallback(
+    async (walkInId, input) => {
+      const op = await reconcileMutate({ walkInId, input });
+      void refreshWalkIns();
+      return op;
+    },
+    [reconcileMutate, refreshWalkIns]
+  );
+  return {
+    board: {
+      data: boardData,
+      loaded: boardLoaded,
+      lastFetchFailed: boardFetchFailed,
+      fetchedAt: boardFetchedAt,
+      refresh: refreshBoard
+    },
+    walkIns: {
+      rows: walkInRows,
+      loaded: walkInsLoaded,
+      lastFetchFailed: walkInsFetchFailed,
+      fetchedAt: walkInsFetchedAt,
+      hasMore: walkInsHasNext,
+      refresh: refreshWalkIns,
+      loadMore: loadMoreWalkIns
+    },
+    walkInMeta: {
+      data: metaData,
+      loaded: metaLoaded,
+      lastFetchFailed: metaFetchFailed,
+      refresh: refreshMeta
+    },
+    createWalkIn,
+    postpone,
+    reconcileWalkIn
+  };
+});
+function useTreks(tripRef) {
+  return useTreksInternal(tripRef);
+}
+var ThemeAttributesContext = createContext(null);
+var FAMILY_DEFAULT_FRAME = {
+  admin: "desk",
+  manager: "field",
+  traveller: "document"
+};
+var DESK_MINIMUM_CONTAINER_WIDTH_PX = 640;
+function ShadowIsolationBoundary({
+  className,
+  children
+}) {
+  const hostRef = useRef(null);
+  const [shadowContainer, setShadowContainer] = useState(null);
+  useEffect(() => {
+    const host = hostRef.current;
+    if (host === null) {
+      return;
+    }
+    const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
+    let container = shadow.querySelector("div[data-kf-shadow-content]");
+    if (container === null) {
+      container = document.createElement("div");
+      container.setAttribute("data-kf-shadow-content", "");
+      shadow.appendChild(container);
+    }
+    setShadowContainer(container);
+  }, []);
+  return /* @__PURE__ */ jsx("div", { ref: hostRef, className, "data-kf-isolation": "shadow", children: shadowContainer !== null ? createPortal(children, shadowContainer) : null });
+}
+function useDeskMinimumWidthWarning(rootRef, frame) {
+  useEffect(() => {
+    if (frame !== "desk" || !isDevelopment() || typeof ResizeObserver === "undefined") {
+      return;
+    }
+    const node = rootRef.current;
+    if (node === null) {
+      return;
+    }
+    let warned = false;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry === void 0 || warned) {
+        return;
+      }
+      if (entry.contentRect.width < DESK_MINIMUM_CONTAINER_WIDTH_PX) {
+        warned = true;
+        console.warn(
+          `kaafil-react-uikit: the 'desk' frame's .kf-root is narrower than the stated minimum container width (05-theming-and-branding.md \xA74.4). AppShell never auto-swaps frames \u2014 mount the manager family, or pass frame="field" explicitly, for this container.`
+        );
+      }
+    });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [rootRef, frame]);
+}
+function useUnfilledConnectivitySlotWarning(frame, connectivitySlot) {
+  useEffect(() => {
+    if (frame === "field" && connectivitySlot === void 0 && isDevelopment()) {
+      console.warn(
+        `kaafil-react-uikit: AppShell's "field" frame has no connectivitySlot filled \u2014 the permanently-visible connectivity/sync region this frame reserves is empty (01-app-shell.md, briefing \xA727.2).`
+      );
+    }
+  }, [frame, connectivitySlot]);
+}
+function AppShell({
+  frame,
+  family,
+  isolation = "scoped",
+  navSlot,
+  actionBarSlot,
+  connectivitySlot,
+  children,
+  style
+}) {
+  const themeAttributes = useContext(ThemeAttributesContext);
+  const rootRef = useRef(null);
+  const resolvedFrame = frame ?? (family !== void 0 ? FAMILY_DEFAULT_FRAME[family] : "document");
+  useDeskMinimumWidthWarning(rootRef, resolvedFrame);
+  useUnfilledConnectivitySlotWarning(resolvedFrame, connectivitySlot);
+  const dataAttributes = {
+    "data-kf-frame": resolvedFrame
+  };
+  if (family !== void 0) {
+    dataAttributes["data-kf-family"] = family;
+  }
+  if (themeAttributes !== null) {
+    dataAttributes["data-kf-theme"] = themeAttributes.theme;
+    if (themeAttributes.density !== void 0) {
+      dataAttributes["data-kf-density"] = themeAttributes.density;
+    }
+  }
+  const content = /* @__PURE__ */ jsxs(Fragment$1, { children: [
+    resolvedFrame === "desk" && navSlot !== void 0 ? /* @__PURE__ */ jsx("div", { className: "kf-app-shell__nav", children: navSlot }) : null,
+    /* @__PURE__ */ jsx("div", { className: "kf-app-shell__content", children }),
+    resolvedFrame === "field" && actionBarSlot !== void 0 ? /* @__PURE__ */ jsx("div", { className: "kf-app-shell__action-bar", children: actionBarSlot }) : null,
+    resolvedFrame === "field" && connectivitySlot !== void 0 ? /* @__PURE__ */ jsx("div", { className: "kf-app-shell__connectivity", children: connectivitySlot }) : null,
+    /* @__PURE__ */ jsx("div", { className: "kf-app-shell__live-region", role: "status", "aria-live": "polite" })
+  ] });
+  if (isolation === "shadow") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: rootRef,
+        className: "kf-root",
+        "data-kf-isolation": "shadow",
+        ...dataAttributes,
+        style: tokenStyle(style),
+        children: /* @__PURE__ */ jsx(ShadowIsolationBoundary, { className: "kf-app-shell__shadow-host", children: content })
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: rootRef,
+      className: "kf-root",
+      "data-kf-isolation": "scoped",
+      ...dataAttributes,
+      style: tokenStyle(style),
+      children: content
+    }
+  );
+}
+function ConfigShell({ seedConfig = {}, children }) {
+  const value = useMemo(
+    () => ({
+      resolveSetting(key) {
+        const agencyValue = seedConfig.agency?.[key];
+        if (agencyValue !== void 0) {
+          return agencyValue;
+        }
+        const tenantValue = seedConfig.tenant?.[key];
+        return tenantValue === void 0 ? void 0 : tenantValue;
+      }
+    }),
+    [seedConfig.agency, seedConfig.tenant]
+  );
+  return /* @__PURE__ */ jsx(ConfigContext.Provider, { value, children });
+}
+function classifyForFallback(error) {
+  const classification = classifyError(error);
+  if (classification.code === "RESOURCE_NOT_FOUND") {
+    return { classification: "isolation", code: classification.code };
+  }
+  if (classification.path === "parked" || classification.unsatisfiableScheme) {
+    return { classification: "parked", code: classification.code };
+  }
+  return { classification: "retryable", code: classification.code };
+}
+var FALLBACK_STYLE = {
+  fontFamily: "system-ui, sans-serif",
+  padding: "1.5rem",
+  border: "1px solid #999",
+  borderRadius: "4px",
+  color: "#1a1a1a",
+  background: "#fff"
+};
+function DefaultFallback({
+  ctx,
+  onRetry
+}) {
+  const role = ctx.classification === "retryable" ? "status" : "alert";
+  const ariaLive = ctx.classification === "retryable" ? "polite" : "assertive";
+  const message = ctx.classification === "isolation" ? "Not found." : ctx.classification === "parked" ? "This action can't be completed right now." : "Something went wrong.";
+  return /* @__PURE__ */ jsxs("div", { style: FALLBACK_STYLE, role, "aria-live": ariaLive, children: [
+    /* @__PURE__ */ jsx("p", { style: { margin: 0 }, children: message }),
+    ctx.classification === "retryable" ? /* @__PURE__ */ jsx("button", { type: "button", onClick: onRetry, style: { marginTop: "0.75rem" }, children: "Try again" }) : null
+  ] });
+}
+var ErrorShell = class extends Component {
+  state = { caught: null, retryKey: 0 };
+  static getDerivedStateFromError(error) {
+    return { caught: { error } };
+  }
+  handleRetry = () => {
+    this.setState((current) => ({ caught: null, retryKey: current.retryKey + 1 }));
+  };
+  render() {
+    if (this.state.caught !== null) {
+      const ctx = classifyForFallback(this.state.caught.error);
+      if (this.props.fallbackSlot !== void 0) {
+        return this.props.fallbackSlot(ctx);
+      }
+      return /* @__PURE__ */ jsx(DefaultFallback, { ctx, onRetry: this.handleRetry });
+    }
+    return /* @__PURE__ */ jsx(Fragment, { children: this.props.children }, this.state.retryKey);
+  }
+};
+var SessionExpiryBridgeContext = createContext(void 0);
+function OfflineShell({
+  storage,
+  blob,
+  conflictResolver,
+  readEntity,
+  scope,
+  children
+}) {
+  const client = useContext(KaafilClientContext);
+  const persona = usePersona();
+  const session = useSession();
+  const reportExpired = useContext(SessionExpiryBridgeContext);
+  const [engine, setEngine] = useState(null);
+  const engineRef = useRef(null);
+  const derivedScope = scope ?? `${persona}:${session.agencyRef ?? "share"}`;
+  useEffect(() => {
+    if (session.status !== "authenticated" || client === null) {
+      return;
+    }
+    const newEngine = client.openOffline({
+      storage,
+      scope: derivedScope,
+      ...readEntity !== void 0 ? { readEntity } : {},
+      ...conflictResolver !== void 0 ? { conflictResolver } : {},
+      ...blob !== void 0 ? { blob } : {}
+      // GAP flagged in this phase's report: a share session's local
+      // `expiresAt` enforcement (`OpenOfflineOptions.share`,
+      // `07-offline-and-sync.md §8`) needs an `expiresAt` this shell has no
+      // source for yet — it is not on `useSession()`'s derived shape and no
+      // prop carries it. Omitted here rather than guessed; a share engine
+      // opens without the local expiry/grace/purge enforcement until that
+      // value has a wire source.
+    });
+    engineRef.current = newEngine;
+    setEngine(newEngine);
+    const unsubscribeSessionExpired = persona !== "share" ? newEngine.events.on("session.expired", () => reportExpired?.("session")) : void 0;
+    const unsubscribeShareExpired = persona === "share" ? newEngine.events.on("share.expired", () => reportExpired?.("share")) : void 0;
+    const unsubscribeShareRevoked = persona === "share" ? newEngine.events.on("share.revoked", () => reportExpired?.("share")) : void 0;
+    return () => {
+      unsubscribeSessionExpired?.();
+      unsubscribeShareExpired?.();
+      unsubscribeShareRevoked?.();
+      newEngine.close();
+      if (engineRef.current === newEngine) {
+        engineRef.current = null;
+      }
+    };
+  }, [client, derivedScope, session.status, persona, reportExpired]);
+  return /* @__PURE__ */ jsx(OfflineEngineContext.Provider, { value: engine, children });
+}
+
+// src/core/shells/internal/jwtKind.ts
+function base64UrlDecode(segment) {
+  const padded = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const withPadding = padded + "=".repeat((4 - padded.length % 4) % 4);
+  return atob(withPadding);
+}
+function decodeManagerOrAgencyAdminKind(accessToken) {
+  const segments = accessToken.split(".");
+  const payloadSegment = segments[1];
+  if (segments.length !== 3 || payloadSegment === void 0) {
+    throw new Error(
+      'SessionShell could not parse "accessToken" as a JWT \u2014 it does not have the three dot-separated segments every manager/agencyAdmin session token has.'
+    );
+  }
+  let claim;
+  try {
+    claim = JSON.parse(base64UrlDecode(payloadSegment));
+  } catch {
+    throw new Error(
+      `SessionShell could not decode "accessToken"'s payload segment as JSON \u2014 the value handed to <KaafilUIKitProvider accessToken> is not a well-formed JWT.`
+    );
+  }
+  const kind = claim.kind;
+  if (kind === "agencyAdmin") {
+    return "agencyAdmin";
+  }
+  if (kind === "managerSession" || kind === "manager") {
+    return "managerSession";
+  }
+  throw new Error(
+    `SessionShell read an unrecognised "kind" claim ("${String(kind)}") off "accessToken" \u2014 expected the manager or agencyAdmin session JWT shape (00-decisions.md U-003).`
+  );
+}
+async function resolveCredential(props) {
+  if (props.credentialResolver !== void 0) {
+    const resolved = await props.credentialResolver();
+    if ("shareToken" in resolved) {
+      return { kind: "share", shareToken: resolved.shareToken };
+    }
+    const kind2 = decodeManagerOrAgencyAdminKind(resolved.accessToken) === "agencyAdmin" ? "agencyAdmin" : "manager";
+    return { kind: kind2, ...resolved };
+  }
+  if (props.shareToken !== void 0) {
+    return { kind: "share", shareToken: props.shareToken };
+  }
+  const kind = decodeManagerOrAgencyAdminKind(props.accessToken) === "agencyAdmin" ? "agencyAdmin" : "manager";
+  return {
+    kind,
+    accessToken: props.accessToken,
+    refreshToken: props.refreshToken,
+    agencyRef: props.agencyRef
+  };
+}
+function SessionShell(props) {
+  const { environment = "live", onRefresh, onSessionExpired, children } = props;
+  const [state, setState] = useState(null);
+  const expiredCallbackFiredRef = useRef(false);
+  const currentPersonaRef = useRef("manager");
+  const reportExpired = useCallback(() => {
+    if (expiredCallbackFiredRef.current) {
+      return;
+    }
+    expiredCallbackFiredRef.current = true;
+    onSessionExpired?.(currentPersonaRef.current);
+    setState(
+      (current) => current === null ? current : { ...current, session: { ...current.session, status: "expired" } }
+    );
+  }, [onSessionExpired]);
+  const accessTokenDep = "accessToken" in props ? props.accessToken : void 0;
+  const refreshTokenDep = "refreshToken" in props ? props.refreshToken : void 0;
+  const agencyRefDep = "agencyRef" in props ? props.agencyRef : void 0;
+  const shareTokenDep = "shareToken" in props ? props.shareToken : void 0;
+  useEffect(() => {
+    let cancelled = false;
+    const client = new KaafilClient({ environment });
+    expiredCallbackFiredRef.current = false;
+    async function open() {
+      const credential = await resolveCredential(props);
+      if (cancelled) {
+        return;
+      }
+      currentPersonaRef.current = credential.kind;
+      if (credential.kind === "share") {
+        client.share.open({ token: credential.shareToken });
+      } else if (credential.kind === "agencyAdmin") {
+        client.admin.open({
+          accessToken: credential.accessToken,
+          refreshToken: credential.refreshToken,
+          agencyRef: credential.agencyRef,
+          ...onRefresh !== void 0 ? { onRefresh } : {}
+        });
+      } else {
+        client.session.open({
+          accessToken: credential.accessToken,
+          refreshToken: credential.refreshToken,
+          agencyRef: credential.agencyRef,
+          ...onRefresh !== void 0 ? { onRefresh } : {}
+        });
+      }
+      setState({
+        client,
+        session: {
+          status: "authenticated",
+          persona: credential.kind,
+          agencyRef: credential.agencyRef,
+          environment
+        }
+      });
+    }
+    void open();
+    return () => {
+      cancelled = true;
+      client.close();
+    };
+  }, [environment, accessTokenDep, refreshTokenDep, agencyRefDep, shareTokenDep]);
+  if (state === null) {
+    return /* @__PURE__ */ jsx(SessionExpiryBridgeContext.Provider, { value: reportExpired, children: /* @__PURE__ */ jsx(
+      SessionContext.Provider,
+      {
+        value: { status: "opening", persona: "manager", agencyRef: void 0, environment },
+        children
+      }
+    ) });
+  }
+  return /* @__PURE__ */ jsx(SessionExpiryBridgeContext.Provider, { value: reportExpired, children: /* @__PURE__ */ jsx(KaafilClientContext.Provider, { value: state.client, children: /* @__PURE__ */ jsx(SessionContext.Provider, { value: state.session, children }) }) });
+}
+function emit(onEvent, event) {
+  if (onEvent === void 0) {
+    return;
+  }
+  try {
+    onEvent(event);
+  } catch {
+  }
+}
+function TelemetryShell({ onEvent, children }) {
+  const session = useSession();
+  const serverTime = useServerTime();
+  const previousStatusRef = useRef(void 0);
+  useEffect(() => {
+    const previousStatus = previousStatusRef.current;
+    if (serverTime.sinceLastSync !== void 0) {
+      if (session.status === "authenticated" && previousStatus !== "authenticated") {
+        emit(onEvent, {
+          type: "session.opened",
+          timestamp: serverTime.now(),
+          persona: session.persona
+        });
+      }
+      if (session.status === "expired" && previousStatus !== "expired") {
+        emit(onEvent, {
+          type: "session.expired",
+          timestamp: serverTime.now(),
+          persona: session.persona
+        });
+      }
+    }
+    previousStatusRef.current = session.status;
+  }, [session.status, serverTime.sinceLastSync]);
+  return /* @__PURE__ */ jsx(Fragment$1, { children });
+}
+function resolveSystemTheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function ThemeShell({ theme = "system", density, children }) {
+  const [systemTheme, setSystemTheme] = useState(
+    () => theme === "system" ? resolveSystemTheme() : theme
+  );
+  useEffect(() => {
+    if (theme !== "system" || typeof window === "undefined" || typeof window.matchMedia !== "function") {
+      return;
+    }
+    const query = window.matchMedia("(prefers-color-scheme: dark)");
+    const listener = (event) => {
+      setSystemTheme(event.matches ? "dark" : "light");
+    };
+    query.addEventListener("change", listener);
+    return () => query.removeEventListener("change", listener);
+  }, [theme]);
+  const resolvedTheme = theme === "system" ? systemTheme : theme;
+  const value = useMemo(() => ({ theme: resolvedTheme, density }), [resolvedTheme, density]);
+  return /* @__PURE__ */ jsx(ThemeAttributesContext.Provider, { value, children });
+}
+var DefaultCapabilityViewsContext = createContext({});
+function useDefaultCapabilityViews() {
+  return useContext(DefaultCapabilityViewsContext);
+}
+function KaafilUIKitProvider(props) {
+  const {
+    environment,
+    onSessionExpired,
+    density,
+    theme,
+    brand,
+    locale,
+    isolation,
+    onEvent,
+    storage,
+    blob,
+    conflictResolver,
+    readEntity,
+    offlineScope,
+    seedConfig,
+    defaultCapabilityViews,
+    children,
+    ...credential
+  } = props;
+  const inner = /* @__PURE__ */ jsx(DefaultCapabilityViewsContext.Provider, { value: defaultCapabilityViews ?? {}, children: /* @__PURE__ */ jsx(ConfigShell, { seedConfig, children: /* @__PURE__ */ jsx(
+    BrandShell,
+    {
+      appName: brand?.appName,
+      logo: brand?.logo,
+      logoMark: brand?.logoMark,
+      favicon: brand?.favicon,
+      headStrategy: brand?.headStrategy,
+      children: /* @__PURE__ */ jsx(TelemetryShell, { onEvent, children })
+    }
+  ) }) });
+  return /* @__PURE__ */ jsx(ErrorShell, { children: /* @__PURE__ */ jsx(ThemeShell, { theme, density, children: /* @__PURE__ */ jsx(I18nShell, { locale, children: /* @__PURE__ */ jsx(AppShell, { isolation, children: /* @__PURE__ */ jsx(
+    SessionShell,
+    {
+      ...credential,
+      environment,
+      onSessionExpired,
+      children: storage !== void 0 ? /* @__PURE__ */ jsx(
+        OfflineShell,
+        {
+          storage,
+          blob,
+          conflictResolver,
+          readEntity,
+          scope: offlineScope,
+          children: inner
+        }
+      ) : inner
+    }
+  ) }) }) }) });
+}
+var HAZARD_LABELS = {
+  "global-box-sizing-reset": "A global box-sizing reset escapes this widget's scope.",
+  "global-button-input-unset": "A global button/input unset rule is active.",
+  "tailwind-preflight-after-ours": "A Tailwind preflight is loaded after this widget's CSS.",
+  "global-margin-padding-reset": "A global margin/padding reset is active.",
+  "conflicting-layer-order": "A conflicting @layer declaration order was detected.",
+  "global-img-max-width": "A global img max-width rule fights this widget's media components.",
+  "host-css-reset-library": "A host-level CSS reset library (e.g. normalize.css) loads after this widget's CSS.",
+  "global-focus-outline-removed": "A global :focus outline removal defeats this widget's focus-visible ring."
+};
+function detectHazards() {
+  if (typeof document === "undefined") {
+    return [];
+  }
+  const probe = document.createElement("div");
+  probe.setAttribute("data-kf-host-css-probe", "");
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  document.body.appendChild(probe);
+  const button = document.createElement("button");
+  probe.appendChild(button);
+  const img = document.createElement("img");
+  probe.appendChild(img);
+  const buttonStyle = getComputedStyle(button);
+  const imgStyle = getComputedStyle(img);
+  const probeStyle = getComputedStyle(probe);
+  const hazards = [];
+  if (probeStyle.boxSizing !== "border-box" && probeStyle.boxSizing !== "content-box") {
+    hazards.push("global-box-sizing-reset");
+  }
+  if (buttonStyle.appearance === "none" && buttonStyle.border === "0px none") {
+    hazards.push("global-button-input-unset");
+  }
+  if (probeStyle.margin !== "" && probeStyle.margin === "0px" && probeStyle.padding === "0px") {
+    hazards.push("global-margin-padding-reset");
+  }
+  if (imgStyle.maxWidth === "100%") {
+    hazards.push("global-img-max-width");
+  }
+  if (buttonStyle.outlineStyle === "none") {
+    hazards.push("global-focus-outline-removed");
+  }
+  document.body.removeChild(probe);
+  return hazards;
+}
+function HostCssCompatibilityProbe({
+  style
+} = {}) {
+  const chrome = useKaafilChrome();
+  const [hazards, setHazards] = useState(null);
+  useEffect(() => {
+    if (isDevelopment()) {
+      setHazards(detectHazards());
+    }
+  }, []);
+  if (!isDevelopment() || hazards === null) {
+    return null;
+  }
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: tokenStyle(style, {
+        border: "1px solid #999",
+        padding: "0.75rem",
+        borderRadius: "4px"
+      }),
+      children: [
+        /* @__PURE__ */ jsx("p", { style: { margin: 0, fontWeight: 600 }, children: chrome.t("probe.hostCss.title") }),
+        hazards.length === 0 ? /* @__PURE__ */ jsx("p", { style: { margin: "0.5rem 0 0" }, children: chrome.t("probe.hostCss.clean") }) : /* @__PURE__ */ jsx("ul", { style: { margin: "0.5rem 0 0" }, children: hazards.map((hazard) => /* @__PURE__ */ jsx("li", { children: HAZARD_LABELS[hazard] }, hazard)) }),
+        hazards.length > 0 ? /* @__PURE__ */ jsxs("p", { style: { margin: "0.5rem 0 0" }, children: [
+          "Recommended: pass ",
+          /* @__PURE__ */ jsx("code", { children: 'isolation="shadow"' }),
+          " to <KaafilUIKitProvider> (05-theming-and-branding.md \xA77, rung 2)."
+        ] }) : null
+      ]
+    }
+  );
+}
+function KaafilSessionProbe({
+  expectedEnvironment,
+  style
+}) {
+  const session = useSession();
+  const chrome = useKaafilChrome();
+  if (session.status === "expired") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        role: "status",
+        style: tokenStyle(style, {
+          border: "1px solid #c00",
+          padding: "0.75rem",
+          borderRadius: "4px"
+        }),
+        children: "Tokens invalid or already expired at mount \u2014 the values handed to <KaafilUIKitProvider> were rejected before a successful open (00-decisions.md U-014)."
+      }
+    );
+  }
+  if (expectedEnvironment !== void 0 && session.status === "authenticated" && session.environment !== expectedEnvironment) {
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        role: "status",
+        style: tokenStyle(style, {
+          border: "1px solid #c00",
+          padding: "0.75rem",
+          borderRadius: "4px"
+        }),
+        children: [
+          'Wrong environment \u2014 expected "',
+          expectedEnvironment,
+          '" but the opened credential is "',
+          session.environment,
+          '"',
+          session.environment === "test" && expectedEnvironment === "live" ? " (test key on live)." : "."
+        ]
+      }
+    );
+  }
+  if (session.status === "opening") {
+    return /* @__PURE__ */ jsx("div", { role: "status", style: tokenStyle(style), children: chrome.t("chrome.loading") });
+  }
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: tokenStyle(style, {
+        border: "1px solid #0a0",
+        padding: "0.75rem",
+        borderRadius: "4px"
+      }),
+      children: [
+        /* @__PURE__ */ jsx("p", { style: { margin: 0 }, children: chrome.t("probe.session.ok") }),
+        /* @__PURE__ */ jsxs("dl", { style: { margin: "0.5rem 0 0" }, children: [
+          /* @__PURE__ */ jsx("dt", { children: chrome.t("probe.session.credentialKind") }),
+          /* @__PURE__ */ jsx("dd", { children: session.persona }),
+          /* @__PURE__ */ jsx("dt", { children: chrome.t("probe.session.environment") }),
+          /* @__PURE__ */ jsx("dd", { children: session.environment }),
+          session.agencyRef !== void 0 ? /* @__PURE__ */ jsxs(Fragment$1, { children: [
+            /* @__PURE__ */ jsx("dt", { children: chrome.t("probe.session.agency") }),
+            /* @__PURE__ */ jsx("dd", { children: session.agencyRef })
+          ] }) : null
+        ] })
+      ]
+    }
+  );
+}
+
+export { AppShell, ConfigShell, ErrorShell, HostCssCompatibilityProbe, KaafilSessionProbe, KaafilUIKitProvider, NotImplementedError, OfflineShell, SessionShell, TelemetryShell, ThemeShell, useBlobStatus, useDefaultCapabilityViews, useFeedbackNps, useJourney, useResolvedSetting, useSnapshotEntity, useStaleness, useTreks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map