Squash Odysseus development history

static/js/startupShell.js

@@ -0,0 +1,153 @@
+// Odysseus UI — startup shell sequencing
+// ES6 module — no application dependencies, DOM only.
+//
+// Revealing the application shell, retiring the boot loader, settling the
+// sidebar's own loading state, and firing a deferred URL route are separate
+// startup concerns that used to sit inline in app.js behind a single promise.
+// They live here so each step has one owner and so the whole contract can be
+// exercised directly (tests/test_startup_shell_js.py) without booting the app.
+
+const LOADER_ID = 'app-loader';
+const SESSION_BOOTSTRAP_ROW_ID = 'session-list-loading';
+
+// Route openers that read the hydrated session list. Everything else only
+// needs module wiring and must not wait on /api/sessions. `/email` spawns a
+// fresh chat, and that path falls back to the most recent session's model
+// (_createDirectChatFromPreferredModel in app.js) when there is no default
+// chat configured, so it genuinely needs the list.
+const ROUTES_NEEDING_SESSIONS = new Set(['/email']);
+
+let _routeOpener = null;
+let _routeOpenerNeedsSessions = false;
+
+function _loader() {
+  return document.getElementById(LOADER_ID);
+}
+
+/** Run `fn` after the next paint has committed (two animation frames). */
+export function afterNextPaint(fn) {
+  requestAnimationFrame(() => requestAnimationFrame(fn));
+}
+
+// The loader node stays in the DOM while sessions hydrate — sidebar-layout.js
+// and sessions.js both read its presence as a "still starting up" sentinel —
+// but it must stop covering, announcing, and animating over a usable shell.
+function _makeLoaderInert(loader) {
+  if (!loader || loader.dataset.shellRevealed === 'true') return;
+  loader.dataset.shellRevealed = 'true';
+  loader.setAttribute('aria-hidden', 'true');
+  loader.style.pointerEvents = 'none';
+  loader.style.opacity = '0';
+  // index.html's inline bootstrap animates the wave on a 150ms interval.
+  // Nothing of it is visible any more, so stop rendering into it.
+  try { window.__odysseusLoaderWaveStop?.(); } catch (_) {}
+}
+
+/**
+ * Hand the shell to the user once core wiring is done. Deferred by one paint
+ * so the first frame lands with the app already laid out.
+ */
+export function revealApplicationShellAfterPaint() {
+  const loader = _loader();
+  if (!loader || loader.dataset.shellRevealScheduled === 'true') return;
+  loader.dataset.shellRevealScheduled = 'true';
+  afterNextPaint(() => _makeLoaderInert(_loader()));
+}
+
+/** Retire the loader node for good. Safe to call after a reveal. */
+export function removeApplicationLoader() {
+  const loader = _loader();
+  if (!loader) return;
+  _makeLoaderInert(loader);
+  setTimeout(() => loader.remove(), 300);
+}
+
+/**
+ * Turn the sidebar's bootstrap row into a failure row. The write is delayed
+ * until the session renderer's frame has committed so a late success cannot
+ * leave stale failure text behind.
+ */
+export function markSessionListUnavailableIfStillBootstrapping() {
+  afterNextPaint(() => {
+    const row = document.getElementById(SESSION_BOOTSTRAP_ROW_ID);
+    if (!row) return;
+    const status = row.querySelector('[data-session-list-status]') || row;
+    status.textContent = 'Chats unavailable';
+  });
+}
+
+/** True when `path`'s route opener reads the hydrated session list. */
+export function routeNeedsSessionData(path) {
+  return ROUTES_NEEDING_SESSIONS.has(path);
+}
+
+/**
+ * Stash a URL route opener for later. At the point app.js resolves the route,
+ * the modules its handlers drive (the rail new-chat handler, the email
+ * section header handler, sessionModule) are still being wired further down
+ * the same init pass, so the opener cannot run inline.
+ */
+export function deferRouteOpener(path, opener) {
+  if (!opener) return;
+  _routeOpener = opener;
+  _routeOpenerNeedsSessions = routeNeedsSessionData(path);
+}
+
+/**
+ * Fire the deferred route opener if its data is ready. Called once when
+ * wiring completes and again after authoritative session hydration; a route
+ * that needs no session data takes the first call, one that does takes the
+ * second.
+ *
+ * @returns {boolean} whether an opener ran.
+ */
+export function runDeferredRouteOpener({ sessionsSettled = false } = {}) {
+  if (!_routeOpener) return false;
+  if (_routeOpenerNeedsSessions && !sessionsSettled) return false;
+  const opener = _routeOpener;
+  _routeOpener = null;
+  _routeOpenerNeedsSessions = false;
+  try { opener(); } catch (e) { console.warn('route opener failed:', e); }
+  return true;
+}
+
+/**
+ * Drive session hydration and everything that hangs off it settling: the
+ * sidebar's failure row, the loader node, and any session-dependent route.
+ *
+ * @param {(() => Promise<boolean>)|null} loadSessions — resolves true only
+ *   after the session list was authoritatively loaded and applied. Null means
+ *   the session module failed to load.
+ */
+export function settleSessionHydration(loadSessions) {
+  const settle = (succeeded) => {
+    if (!succeeded) {
+      markSessionListUnavailableIfStillBootstrapping();
+      // A later unrelated caller must not be able to release a stale startup
+      // opener against unknown session state.
+      _routeOpener = null;
+      _routeOpenerNeedsSessions = false;
+    }
+    removeApplicationLoader();
+    if (succeeded) runDeferredRouteOpener({ sessionsSettled: true });
+    return succeeded;
+  };
+  if (!loadSessions) {
+    return Promise.resolve(settle(false));
+  }
+  // Kick the request off synchronously — a microtask hop here would delay the
+  // fetch this whole change exists to get off the critical path.
+  let pending;
+  try {
+    pending = loadSessions();
+  } catch (e) {
+    console.warn('loadSessions error:', e);
+    return Promise.resolve(settle(false));
+  }
+  return Promise.resolve(pending)
+    .then(result => settle(result === true))
+    .catch(e => {
+      console.warn('loadSessions error:', e);
+      return settle(false);
+    });
+}