@the-portland-company/shell 0.52.0 → 0.53.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.53.0 — 2026-09-29
+
+### Added — Loading Screen boot surface (Specs/Loading-Screen)
+
+`PolitogyAppFrame` now renders the platform's boot screen: a full-screen
+`ink-900` surface with the Politogy VRM lockup, a determinate/monotonic
+gradient progress bar (Race Blue → Race Red), and a throttled monospace
+status line, shown on cold start / hard reload / organization switch / mode
+switch — the four events Global-Rules' Boot Screen Exception names — and
+never for an in-page fetch or navigation. New export
+`LoadingScreen`/`BootProgress` from `@the-portland-company/shell/app-chrome`
+lets an app report real pipeline stages; a new `PolitogyAppFrame` prop
+`appReady` lets an app dismiss the screen explicitly. Neither is required:
+an app that passes nothing gets a truthful two-stage report driven by the
+same org/nav resolution signal the frame already computes, so all 14
+consumer apps keep working unchanged. `prefers-reduced-motion` skips the
+exit transition; the bar is `role="progressbar"` with `aria-live` announced
+copy throttled to one per 1.5s (final "Ready." always announced).
+
 ## 0.52.0 — 2026-09-12
 
 ### Added — mobile navigation (GLOBAL)

package/dist/app-chrome.cjs

@@ -3256,6 +3256,182 @@ function watchLogout(onLogout, options = {}) {
   }
   return cleanup;
 }
+var SYNTHETIC_STAGES = [
+  { pct: 20, label: "Connecting to your organization\u2026" },
+  { pct: 100, label: "Ready." }
+];
+var ANNOUNCE_THROTTLE_MS = 1500;
+var MIN_DWELL_MS = 450;
+var FILL_EASE_MS = 380;
+var HOLD_MS = 240;
+var FADE_MS = 300;
+function usePrefersReducedMotion() {
+  const [reduced, setReduced] = react.useState(false);
+  react.useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setReduced(mq.matches);
+    const onChange = () => setReduced(mq.matches);
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+  return reduced;
+}
+function useThrottledAnnouncement(label, isFinal) {
+  const [announced, setAnnounced] = react.useState(label);
+  const lastAtRef = react.useRef(0);
+  react.useEffect(() => {
+    const now = Date.now();
+    if (isFinal || now - lastAtRef.current >= ANNOUNCE_THROTTLE_MS) {
+      lastAtRef.current = now;
+      setAnnounced(label);
+      return;
+    }
+    const wait = ANNOUNCE_THROTTLE_MS - (now - lastAtRef.current);
+    const t = setTimeout(() => {
+      lastAtRef.current = Date.now();
+      setAnnounced(label);
+    }, wait);
+    return () => clearTimeout(t);
+  }, [label, isFinal]);
+  return announced;
+}
+function useDwelledLabel(label) {
+  const [displayed, setDisplayed] = react.useState(label);
+  const shownAtRef = react.useRef(0);
+  const pendingRef = react.useRef(null);
+  react.useEffect(() => {
+    if (label === displayed) return;
+    const elapsed = Date.now() - shownAtRef.current;
+    if (pendingRef.current) clearTimeout(pendingRef.current);
+    if (elapsed >= MIN_DWELL_MS) {
+      shownAtRef.current = Date.now();
+      setDisplayed(label);
+    } else {
+      pendingRef.current = setTimeout(() => {
+        shownAtRef.current = Date.now();
+        setDisplayed(label);
+      }, MIN_DWELL_MS - elapsed);
+    }
+    return () => {
+      if (pendingRef.current) clearTimeout(pendingRef.current);
+    };
+  }, [label]);
+  return displayed;
+}
+function LoadingScreen({
+  bootProgress,
+  syntheticReady,
+  visible,
+  onExitComplete
+}) {
+  const reducedMotion = usePrefersReducedMotion();
+  const synthetic = react.useMemo(() => {
+    const stage = syntheticReady ? SYNTHETIC_STAGES[1] : SYNTHETIC_STAGES[0];
+    return {
+      pct: stage.pct,
+      label: stage.label,
+      phase: syntheticReady ? "done" : "booting"
+    };
+  }, [syntheticReady]);
+  const pct = bootProgress?.pct ?? synthetic.pct;
+  const rawLabel = bootProgress?.label ?? synthetic.label;
+  const phase = bootProgress?.phase ?? synthetic.phase;
+  const isFinal = phase === "done" && pct >= 100;
+  const highWaterRef = react.useRef(0);
+  const clampedPct = Math.max(pct, highWaterRef.current);
+  react.useEffect(() => {
+    highWaterRef.current = clampedPct;
+  }, [clampedPct]);
+  const displayedLabel = useDwelledLabel(rawLabel);
+  const announced = useThrottledAnnouncement(displayedLabel, isFinal);
+  const [fading, setFading] = react.useState(false);
+  react.useEffect(() => {
+    if (!isFinal) return;
+    const holdMs = reducedMotion ? 0 : HOLD_MS;
+    const fadeMs = reducedMotion ? 0 : FADE_MS;
+    const holdTimer = setTimeout(() => {
+      setFading(true);
+      const fadeTimer = setTimeout(onExitComplete, fadeMs);
+      return () => clearTimeout(fadeTimer);
+    }, holdMs);
+    return () => clearTimeout(holdTimer);
+  }, [isFinal, reducedMotion]);
+  if (!visible) return null;
+  const isError = phase === "error";
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      "data-testid": "politogy-loading-screen",
+      style: {
+        position: "fixed",
+        inset: 0,
+        zIndex: 2147483e3,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: "2rem",
+        background: "var(--color-ink-900, #0a0a0c)",
+        color: "#fff",
+        opacity: fading ? 0 : 1,
+        transition: reducedMotion ? void 0 : `opacity ${FADE_MS}ms ease-out`
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx("img", { src: "/politogy-lockup-white.svg", alt: "Politogy VRM", style: { width: 220, height: "auto" } }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { style: { width: 320, maxWidth: "80vw" }, children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              role: "progressbar",
+              "aria-valuemin": 0,
+              "aria-valuemax": 100,
+              "aria-valuenow": Math.round(clampedPct),
+              "aria-label": "Loading your workspace",
+              style: {
+                height: 3,
+                width: "100%",
+                borderRadius: 2,
+                background: "rgba(255,255,255,0.12)",
+                overflow: "hidden"
+              },
+              children: /* @__PURE__ */ jsxRuntime.jsx(
+                "div",
+                {
+                  style: {
+                    height: "100%",
+                    width: `${clampedPct}%`,
+                    background: "linear-gradient(90deg, var(--color-race-blue, #1d4ed8), var(--color-race-red, #dc2626))",
+                    transition: reducedMotion ? void 0 : `width ${FILL_EASE_MS}ms ease-out`
+                  }
+                }
+              )
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "div",
+            {
+              role: "status",
+              "aria-live": "polite",
+              style: {
+                marginTop: "0.75rem",
+                fontFamily: "var(--font-mono, ui-monospace, monospace)",
+                fontSize: "0.8125rem",
+                color: isError ? "var(--color-race-red, #dc2626)" : "rgba(255,255,255,0.72)",
+                textAlign: "center"
+              },
+              children: announced
+            }
+          ),
+          isError && (bootProgress?.onRetry || bootProgress?.onSignOut) && /* @__PURE__ */ jsxRuntime.jsxs("div", { style: { marginTop: "1rem", display: "flex", gap: "0.75rem", justifyContent: "center" }, children: [
+            bootProgress?.onRetry && /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick: bootProgress.onRetry, children: "Retry" }),
+            bootProgress?.onSignOut && /* @__PURE__ */ jsxRuntime.jsx("button", { type: "button", onClick: bootProgress.onSignOut, children: "Sign out" })
+          ] })
+        ] })
+      ]
+    }
+  );
+}
 var CORE_APP = "vrm";
 var DEFAULT_SIGN_OUT_URL = "/auth/signout";
 var DEFAULT_BRAND_LOGO = "/brand/logos/relationship-mode-logo.png";
@@ -3306,6 +3482,8 @@ function PolitogyAppFrame({
   signOutUrl = DEFAULT_SIGN_OUT_URL,
   buildMeta,
   data,
+  bootProgress,
+  appReady,
   children
 }) {
   const meta = POLITOGY_APPS[app];
@@ -3334,6 +3512,8 @@ function PolitogyAppFrame({
           signOutUrl,
           buildMeta,
           data,
+          bootProgress,
+          appReady,
           children
         }
       )
@@ -3350,10 +3530,33 @@ function FrameBody({
   signOutUrl,
   buildMeta,
   data,
+  bootProgress,
+  appReady,
   children
 }) {
   const meta = POLITOGY_APPS[app];
   const chrome = useChromeState();
+  const bootAppMode = meta.mode;
+  const bootOrgId = chrome?.orgId ?? null;
+  const [bootVisible, setBootVisible] = react.useState(true);
+  const [bootGeneration, setBootGeneration] = react.useState(0);
+  const seenOrgRef = react.useRef(bootOrgId);
+  const seenModeRef = react.useRef(bootAppMode);
+  react.useEffect(() => {
+    if (seenOrgRef.current !== null && seenOrgRef.current !== bootOrgId) {
+      setBootVisible(true);
+      setBootGeneration((g) => g + 1);
+    }
+    seenOrgRef.current = bootOrgId;
+  }, [bootOrgId]);
+  react.useEffect(() => {
+    if (seenModeRef.current !== void 0 && seenModeRef.current !== bootAppMode) {
+      setBootVisible(true);
+      setBootGeneration((g) => g + 1);
+    }
+    seenModeRef.current = bootAppMode;
+  }, [bootAppMode]);
+  const chromeResolved = chrome == null || !chrome.orgsLoading;
   const signOutRef = react.useRef(onSignOut);
   signOutRef.current = onSignOut;
   const signingOutRef = react.useRef(false);
@@ -3428,70 +3631,82 @@ function FrameBody({
     [navItems, pathname, search, meta.origin]
   );
   const breadcrumbs = core ? core.page?.breadcrumbs : grants?.includes("breadcrumbs") ? granted("breadcrumbs") : derivedBreadcrumbs;
-  return /* @__PURE__ */ jsxRuntime.jsx(
-    NavAppShell,
-    {
-      sidebar: {
-        pathname,
-        brand: {
-          logoSrc: core?.brandLogoSrc ?? modeBrandLogo(appMode),
-          logoAlt: "Politogy",
-          badgeLabel: "P",
-          title: "Politogy"
-        },
-        nav: {
-          // A flat rail's sub-menu IS the nav, so the 'tabs only' preference
-          // (which strips children) would leave one childless parent row —
-          // flat apps ignore the stripping.
-          items: navDisplay === "tabs" && meta.navShape !== "flat" ? navItems.map(({ children: _sub, ...item }) => item) : navItems,
-          flatten: meta.navShape === "flat"
-        },
-        // The app's own workspace is NOT the organization — it is a per-app
-        // bootstrap account with a different id in every app. Showing it while
-        // the chrome API resolves flashed the wrong org on every load ("not
-        // connected to the account"). Shimmer while in flight; only fall back
-        // to the app label once the chrome lookup has actually failed.
-        org: activeCoreOrg ? {
-          name: activeCoreOrg.name,
-          id: activeCoreOrg.id,
-          logoUrl: activeCoreOrg.logoUrl,
-          brandColor: activeCoreOrg.brandColor,
-          organizations: coreOrgs,
-          onSwitch: chrome?.setOrgId
-        } : chrome?.orgsLoading ? { name: null, id: null, loading: true } : { name: session.accountName, id: session.accountId },
-        mode,
-        footer,
-        linkComponent
+  return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      LoadingScreen,
+      {
+        visible: bootVisible,
+        bootProgress,
+        syntheticReady: appReady ?? chromeResolved,
+        onExitComplete: () => setBootVisible(false)
       },
-      betaBanner: meta.beta === false ? void 0 : {},
-      modeId: appMode,
-      contentWrapper: core?.contentWrapper ?? granted("contentWrapper"),
-      topBar: {
-        // Core's pages publish their own identity; every other app is one
-        // product surface and takes its registry title.
-        title: core?.page?.title ?? (grants?.includes("title") ? data?.frame?.title : void 0) ?? meta.title,
-        breadcrumbs,
-        user: {
-          name: identity.userName,
-          email: identity.email,
-          // The chrome API's avatar wins; the app may supply a fallback chain
-          // (e.g. a stored memoji) for users with no uploaded photo.
-          avatarUrl: identity.avatarUrl ?? data?.fallbackAvatarUrl ?? null,
-          role: session.role
+      bootGeneration
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      NavAppShell,
+      {
+        sidebar: {
+          pathname,
+          brand: {
+            logoSrc: core?.brandLogoSrc ?? modeBrandLogo(appMode),
+            logoAlt: "Politogy",
+            badgeLabel: "P",
+            title: "Politogy"
+          },
+          nav: {
+            // A flat rail's sub-menu IS the nav, so the 'tabs only' preference
+            // (which strips children) would leave one childless parent row —
+            // flat apps ignore the stripping.
+            items: navDisplay === "tabs" && meta.navShape !== "flat" ? navItems.map(({ children: _sub, ...item }) => item) : navItems,
+            flatten: meta.navShape === "flat"
+          },
+          // The app's own workspace is NOT the organization — it is a per-app
+          // bootstrap account with a different id in every app. Showing it while
+          // the chrome API resolves flashed the wrong org on every load ("not
+          // connected to the account"). Shimmer while in flight; only fall back
+          // to the app label once the chrome lookup has actually failed.
+          org: activeCoreOrg ? {
+            name: activeCoreOrg.name,
+            id: activeCoreOrg.id,
+            logoUrl: activeCoreOrg.logoUrl,
+            brandColor: activeCoreOrg.brandColor,
+            organizations: coreOrgs,
+            onSwitch: chrome?.setOrgId
+          } : chrome?.orgsLoading ? { name: null, id: null, loading: true } : { name: session.accountName, id: session.accountId },
+          mode,
+          footer,
+          linkComponent
         },
-        userMenu,
-        onSignOut: handleSignOut,
-        // The action cluster is IDENTICAL everywhere — core included. Page
-        // actions sit BEFORE it, never inside it, so the Alerts bell keeps its
-        // required position: farthest right, immediately before My Account.
-        actions: /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-          core?.page?.actions,
-          /* @__PURE__ */ jsxRuntime.jsx(ChromeTopBarActions, {})
-        ] })
-      },
-      children
-    }
-  );
+        betaBanner: meta.beta === false ? void 0 : {},
+        modeId: appMode,
+        contentWrapper: core?.contentWrapper ?? granted("contentWrapper"),
+        topBar: {
+          // Core's pages publish their own identity; every other app is one
+          // product surface and takes its registry title.
+          title: core?.page?.title ?? (grants?.includes("title") ? data?.frame?.title : void 0) ?? meta.title,
+          breadcrumbs,
+          user: {
+            name: identity.userName,
+            email: identity.email,
+            // The chrome API's avatar wins; the app may supply a fallback chain
+            // (e.g. a stored memoji) for users with no uploaded photo.
+            avatarUrl: identity.avatarUrl ?? data?.fallbackAvatarUrl ?? null,
+            role: session.role
+          },
+          userMenu,
+          onSignOut: handleSignOut,
+          // The action cluster is IDENTICAL everywhere — core included. Page
+          // actions sit BEFORE it, never inside it, so the Alerts bell keeps its
+          // required position: farthest right, immediately before My Account.
+          actions: /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+            core?.page?.actions,
+            /* @__PURE__ */ jsxRuntime.jsx(ChromeTopBarActions, {})
+          ] })
+        },
+        children
+      }
+    )
+  ] });
 }
 var standardNavIcons = {
   home: fi.FiHome,
@@ -3969,6 +4184,7 @@ function useChromeMode(arg = {}) {
 }
 
 exports.ChromeTopBarActions = ChromeTopBarActions;
+exports.LoadingScreen = LoadingScreen;
 exports.POLITOGY_APPS = POLITOGY_APPS;
 exports.PolitogyAppChrome = PolitogyAppChrome;
 exports.PolitogyAppFrame = PolitogyAppFrame;