@chrysb/alphaclaw 0.4.6-beta.4 → 0.4.6-beta.6

package/lib/public/js/components/usage-tab/constants.js

@@ -1,8 +1,8 @@
 export const kColorPalette = [
   "#7dd3fc",
   "#22d3ee",
-  "#34d399",
   "#fbbf24",
+  "#34d399",
   "#fb7185",
   "#a78bfa",
   "#f472b6",

package/lib/public/js/components/usage-tab/overview-section.js

@@ -1,7 +1,11 @@
 import { h } from "https://esm.sh/preact";
 import { useEffect, useState } from "https://esm.sh/preact/hooks";
 import htm from "https://esm.sh/htm";
-import { formatInteger, formatUsd } from "../../lib/format.js";
+import {
+  formatCompactNumber,
+  formatInteger,
+  formatUsd,
+} from "../../lib/format.js";
 import { SegmentedControl } from "../segmented-control.js";
 import { kRangeOptions, kUsageSourceOrder } from "./constants.js";
 import { renderSourceLabel } from "./formatters.js";
@@ -14,6 +18,34 @@ const formatCountLabel = (value, singular, plural) => {
   return `${formatInteger(count)} ${label}`;
 };
 
+const formatPercent = (ratio) => `${(Number(ratio || 0) * 100).toFixed(1)}%`;
+
+const getCacheHitRateValueClass = (ratio) => {
+  const percent = Number(ratio || 0) * 100;
+  if (percent <= 0) return "text-gray-300";
+  if (percent >= 70) return "text-green-400";
+  if (percent >= 40) return "text-amber-300";
+  return "text-red-400";
+};
+
+const getOverviewMetrics = (summary) => {
+  const totals = summary?.totals || {};
+  const cacheReadTokens = Number(totals.cacheReadTokens || 0);
+  const inputTokens = Number(totals.inputTokens || 0);
+  const promptTokens = inputTokens + cacheReadTokens;
+  const turnCount = Number(totals.turnCount || 0);
+  const totalTokens = Number(totals.totalTokens || 0);
+  const totalCost = Number(totals.totalCost || 0);
+  return {
+    cacheHitRate: promptTokens > 0 ? cacheReadTokens / promptTokens : 0,
+    cacheReadTokens,
+    promptTokens,
+    avgTokensPerTurn: turnCount > 0 ? totalTokens / turnCount : 0,
+    avgCostPerTurn: turnCount > 0 ? totalCost / turnCount : 0,
+    turnCount,
+  };
+};
+
 const SummaryCard = ({ title, tokens, cost }) => html`
   <div class="bg-surface border border-border rounded-xl p-4">
     <h3 class="card-label text-xs">${title}</h3>
@@ -25,6 +57,25 @@ const SummaryCard = ({ title, tokens, cost }) => html`
   </div>
 `;
 
+const MetricCard = ({
+  title,
+  value,
+  detail = "",
+  valueClass = "",
+  valueSuffix = "",
+}) => html`
+  <div class="bg-surface border border-border rounded-xl p-4">
+    <h3 class="card-label text-xs">${title}</h3>
+    <div class=${`text-lg font-semibold mt-1 ${valueClass}`.trim()}>
+      ${value}
+      ${valueSuffix
+        ? html`<span class="text-xs text-[var(--text-muted)] ml-1">${valueSuffix}</span>`
+        : null}
+    </div>
+    <div class="text-xs text-[var(--text-muted)] mt-1">${detail}</div>
+  </div>
+`;
+
 const AgentCostDistribution = ({ summary }) => {
   const agents = Array.isArray(summary?.costByAgent?.agents)
     ? summary.costByAgent.agents
@@ -167,55 +218,78 @@ export const OverviewSection = ({
   overviewCanvasRef,
   onDaysChange = () => {},
   onMetricChange = () => {},
-}) => html`
-  <div class="space-y-4">
-    <div class="grid grid-cols-1 md:grid-cols-3 gap-3">
-      <${SummaryCard}
-        title="Today"
-        tokens=${periodSummary.today.tokens}
-        cost=${periodSummary.today.cost}
-      />
-      <${SummaryCard}
-        title="Last 7 days"
-        tokens=${periodSummary.week.tokens}
-        cost=${periodSummary.week.cost}
-      />
-      <${SummaryCard}
-        title="Last 30 days"
-        tokens=${periodSummary.month.tokens}
-        cost=${periodSummary.month.cost}
-      />
-    </div>
-    <div class="bg-surface border border-border rounded-xl p-4">
-      <div
-        class="flex flex-col sm:flex-row sm:items-center justify-between gap-2 mb-3"
-      >
-        <h2 class="card-label text-xs">
-          Daily ${metric === "tokens" ? "tokens" : "cost"} by model
-        </h2>
-        <div class="flex items-center gap-2">
-          <${SegmentedControl}
-            options=${kRangeOptions.map((option) => ({
-              label: option.label,
-              value: option.value,
-            }))}
-            value=${days}
-            onChange=${onDaysChange}
-          />
-          <${SegmentedControl}
-            options=${[
-              { label: "tokens", value: "tokens" },
-              { label: "cost", value: "cost" },
-            ]}
-            value=${metric}
-            onChange=${onMetricChange}
-          />
-        </div>
+}) => {
+  const overviewMetrics = getOverviewMetrics(summary);
+
+  return html`
+    <div class="space-y-4">
+      <div class="grid grid-cols-1 md:grid-cols-3 gap-3">
+        <${SummaryCard}
+          title="Today"
+          tokens=${periodSummary.today.tokens}
+          cost=${periodSummary.today.cost}
+        />
+        <${SummaryCard}
+          title="Last 7 days"
+          tokens=${periodSummary.week.tokens}
+          cost=${periodSummary.week.cost}
+        />
+        <${SummaryCard}
+          title="Last 30 days"
+          tokens=${periodSummary.month.tokens}
+          cost=${periodSummary.month.cost}
+        />
       </div>
-      <div style=${{ height: "280px" }}>
-        <canvas ref=${overviewCanvasRef}></canvas>
+      <div class="grid grid-cols-1 md:grid-cols-3 gap-3">
+        <${MetricCard}
+          title="Cache hit rate"
+          value=${formatPercent(overviewMetrics.cacheHitRate)}
+          valueClass=${getCacheHitRateValueClass(overviewMetrics.cacheHitRate)}
+          detail=${`${formatCompactNumber(overviewMetrics.cacheReadTokens)} cached · ${formatCompactNumber(overviewMetrics.promptTokens)} prompt`}
+        />
+        <${MetricCard}
+          title="Avg tokens per turn"
+          value=${formatCompactNumber(overviewMetrics.avgTokensPerTurn)}
+          valueSuffix="tokens"
+          detail=${`${formatCountLabel(overviewMetrics.turnCount, "turn", "turns")} last ${days} days`}
+        />
+        <${MetricCard}
+          title="Avg cost per turn"
+          value=${formatUsd(overviewMetrics.avgCostPerTurn)}
+          detail=${`${formatCountLabel(overviewMetrics.turnCount, "turn", "turns")} last ${days} days`}
+        />
       </div>
+      <div class="bg-surface border border-border rounded-xl p-4">
+        <div
+          class="flex flex-col sm:flex-row sm:items-center justify-between gap-2 mb-3"
+        >
+          <h2 class="card-label text-xs">
+            Daily ${metric === "tokens" ? "tokens" : "cost"} by model
+          </h2>
+          <div class="flex items-center gap-2">
+            <${SegmentedControl}
+              options=${kRangeOptions.map((option) => ({
+                label: option.label,
+                value: option.value,
+              }))}
+              value=${days}
+              onChange=${onDaysChange}
+            />
+            <${SegmentedControl}
+              options=${[
+                { label: "tokens", value: "tokens" },
+                { label: "cost", value: "cost" },
+              ]}
+              value=${metric}
+              onChange=${onMetricChange}
+            />
+          </div>
+        </div>
+        <div style=${{ height: "280px" }}>
+          <canvas ref=${overviewCanvasRef}></canvas>
+        </div>
+      </div>
+      <${AgentCostDistribution} summary=${summary} />
     </div>
-    <${AgentCostDistribution} summary=${summary} />
-  </div>
-`;
+  `;
+};

package/lib/public/js/components/usage-tab/use-usage-tab.js

@@ -1,4 +1,10 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "https://esm.sh/preact/hooks";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "https://esm.sh/preact/hooks";
 import {
   fetchUsageSessionDetail,
   fetchUsageSessions,
@@ -17,12 +23,17 @@ import { toChartColor, toLocalDayKey } from "./formatters.js";
 export const useUsageTab = ({ sessionId = "" }) => {
   const [days, setDays] = useState(() => {
     const settings = readUiSettings();
-    const parsedDays = Number.parseInt(String(settings[kUsageDaysUiSettingKey] ?? ""), 10);
+    const parsedDays = Number.parseInt(
+      String(settings[kUsageDaysUiSettingKey] ?? ""),
+      10,
+    );
     return [7, 30, 90].includes(parsedDays) ? parsedDays : kDefaultUsageDays;
   });
   const [metric, setMetric] = useState(() => {
     const settings = readUiSettings();
-    return settings[kUsageMetricUiSettingKey] === "cost" ? "cost" : kDefaultUsageMetric;
+    return settings[kUsageMetricUiSettingKey] === "cost"
+      ? "cost"
+      : kDefaultUsageMetric;
   });
   const [summary, setSummary] = useState(null);
   const [sessions, setSessions] = useState([]);
@@ -104,9 +115,14 @@ export const useUsageTab = ({ sessionId = "" }) => {
     const safeSessionId = String(sessionId || "").trim();
     if (!safeSessionId) return;
     setExpandedSessionIds((currentValue) =>
-      currentValue.includes(safeSessionId) ? currentValue : [...currentValue, safeSessionId],
+      currentValue.includes(safeSessionId)
+        ? currentValue
+        : [...currentValue, safeSessionId],
     );
-    if (!sessionDetailById[safeSessionId] && !loadingDetailById[safeSessionId]) {
+    if (
+      !sessionDetailById[safeSessionId] &&
+      !loadingDetailById[safeSessionId]
+    ) {
       loadSessionDetail(safeSessionId);
     }
   }, [sessionId, sessionDetailById, loadingDetailById, loadSessionDetail]);
@@ -115,8 +131,12 @@ export const useUsageTab = ({ sessionId = "" }) => {
     const rows = Array.isArray(summary?.daily) ? summary.daily : [];
     const now = new Date();
     const dayKey = toLocalDayKey(now);
-    const weekStart = toLocalDayKey(new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000));
-    const monthStart = toLocalDayKey(new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000));
+    const weekStart = toLocalDayKey(
+      new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000),
+    );
+    const monthStart = toLocalDayKey(
+      new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000),
+    );
     const zero = { tokens: 0, cost: 0 };
     return rows.reduce(
       (acc, row) => {
@@ -156,9 +176,13 @@ export const useUsageTab = ({ sessionId = "" }) => {
     const datasets = Array.from(allModels).map((model) => ({
       label: model,
       data: rows.map((row) => {
-        const found = (row.models || []).find((m) => String(m.model || "") === model);
+        const found = (row.models || []).find(
+          (m) => String(m.model || "") === model,
+        );
         if (!found) return 0;
-        return metric === "cost" ? Number(found.totalCost || 0) : Number(found.totalTokens || 0);
+        return metric === "cost"
+          ? Number(found.totalCost || 0)
+          : Number(found.totalTokens || 0);
       }),
       backgroundColor: toChartColor(model),
     }));
@@ -186,13 +210,20 @@ export const useUsageTab = ({ sessionId = "" }) => {
             stacked: true,
             ticks: {
               color: "rgba(156,163,175,1)",
-              callback: (v) => (metric === "cost" ? `$${Number(v).toFixed(2)}` : formatInteger(v)),
+              callback: (v) =>
+                metric === "cost"
+                  ? `$${Number(v).toFixed(2)}`
+                  : formatInteger(v),
             },
           },
         },
         plugins: {
           legend: {
-            labels: { color: "rgba(209,213,219,1)", boxWidth: 10, boxHeight: 10 },
+            labels: {
+              color: "rgba(209,213,219,1)",
+              boxWidth: 10,
+              boxHeight: 10,
+            },
           },
           tooltip: {
             callbacks: {

package/lib/public/js/components/welcome.js

@@ -101,7 +101,7 @@ export const Welcome = ({ onComplete }) => {
         : selectedProvider === "google"
           ? !!vals.GEMINI_API_KEY
           : selectedProvider === "openai-codex"
-            ? !!(codexStatus.connected || vals.OPENAI_API_KEY)
+            ? !!codexStatus.connected
             : false;
 
   const allValid = kWelcomeGroups.every((g) => g.validate(vals, { hasAi }));

package/lib/public/js/hooks/use-app-shell-controller.js

@@ -0,0 +1,230 @@
+import { useState, useEffect, useCallback } from "https://esm.sh/preact/hooks";
+import {
+  fetchStatus,
+  fetchOnboardStatus,
+  fetchAuthStatus,
+  fetchAlphaclawVersion,
+  updateAlphaclaw,
+  fetchRestartStatus,
+  restartGateway,
+  fetchWatchdogStatus,
+  fetchDoctorStatus,
+  updateOpenclaw,
+} from "../lib/api.js";
+import { shouldRequireRestartForBrowsePath } from "../lib/browse-restart-policy.js";
+import { usePolling } from "./usePolling.js";
+import { showToast } from "../components/toast.js";
+
+export const useAppShellController = ({ location = "" } = {}) => {
+  const [onboarded, setOnboarded] = useState(null);
+  const [authEnabled, setAuthEnabled] = useState(false);
+  const [acVersion, setAcVersion] = useState(null);
+  const [acLatest, setAcLatest] = useState(null);
+  const [acHasUpdate, setAcHasUpdate] = useState(false);
+  const [acUpdating, setAcUpdating] = useState(false);
+  const [restartRequired, setRestartRequired] = useState(false);
+  const [browseRestartRequired, setBrowseRestartRequired] = useState(false);
+  const [restartingGateway, setRestartingGateway] = useState(false);
+  const [gatewayRestartSignal, setGatewayRestartSignal] = useState(0);
+  const [statusPollCadenceMs, setStatusPollCadenceMs] = useState(15000);
+  const [openclawUpdateInProgress, setOpenclawUpdateInProgress] = useState(false);
+
+  const sharedStatusPoll = usePolling(fetchStatus, statusPollCadenceMs, {
+    enabled: onboarded === true,
+  });
+  const sharedWatchdogPoll = usePolling(fetchWatchdogStatus, statusPollCadenceMs, {
+    enabled: onboarded === true,
+  });
+  const sharedDoctorPoll = usePolling(fetchDoctorStatus, statusPollCadenceMs, {
+    enabled: onboarded === true,
+  });
+  const sharedStatus = sharedStatusPoll.data || null;
+  const sharedWatchdogStatus = sharedWatchdogPoll.data?.status || null;
+  const sharedDoctorStatus = sharedDoctorPoll.data?.status || null;
+  const isAnyRestartRequired = restartRequired || browseRestartRequired;
+
+  const refreshSharedStatuses = useCallback(() => {
+    sharedStatusPoll.refresh();
+    sharedWatchdogPoll.refresh();
+    sharedDoctorPoll.refresh();
+  }, [sharedDoctorPoll.refresh, sharedStatusPoll.refresh, sharedWatchdogPoll.refresh]);
+
+  useEffect(() => {
+    fetchOnboardStatus()
+      .then((data) => setOnboarded(data.onboarded))
+      .catch(() => setOnboarded(false));
+    fetchAuthStatus()
+      .then((data) => setAuthEnabled(!!data.authEnabled))
+      .catch(() => {});
+  }, []);
+
+  useEffect(() => {
+    if (!onboarded) return;
+    let active = true;
+    const check = async (refresh = false) => {
+      try {
+        const data = await fetchAlphaclawVersion(refresh);
+        if (!active) return;
+        setAcVersion(data.currentVersion || null);
+        setAcLatest(data.latestVersion || null);
+        setAcHasUpdate(!!data.hasUpdate);
+      } catch {}
+    };
+    check(true);
+    const id = setInterval(() => check(false), 5 * 60 * 1000);
+    return () => {
+      active = false;
+      clearInterval(id);
+    };
+  }, [onboarded]);
+
+  const refreshRestartStatus = useCallback(async () => {
+    if (!onboarded) return;
+    try {
+      const data = await fetchRestartStatus();
+      setRestartRequired(!!data.restartRequired);
+      setRestartingGateway(!!data.restartInProgress);
+    } catch {}
+  }, [onboarded]);
+
+  useEffect(() => {
+    if (!onboarded) return;
+    refreshRestartStatus();
+  }, [onboarded, refreshRestartStatus]);
+
+  useEffect(() => {
+    if (onboarded !== true) return;
+    const inStatusView =
+      location.startsWith("/general") || location.startsWith("/watchdog");
+    const gatewayStatus = sharedStatus?.gateway ?? null;
+    const watchdogHealth = String(sharedWatchdogStatus?.health || "").toLowerCase();
+    const watchdogLifecycle = String(sharedWatchdogStatus?.lifecycle || "").toLowerCase();
+    const shouldFastPollWatchdog =
+      watchdogHealth === "unknown" ||
+      watchdogLifecycle === "restarting" ||
+      watchdogLifecycle === "stopped" ||
+      !!sharedWatchdogStatus?.operationInProgress;
+    const shouldFastPollGateway = !gatewayStatus || gatewayStatus !== "running";
+    const nextCadenceMs =
+      inStatusView && (shouldFastPollWatchdog || shouldFastPollGateway) ? 2000 : 15000;
+    setStatusPollCadenceMs((currentCadenceMs) =>
+      currentCadenceMs === nextCadenceMs ? currentCadenceMs : nextCadenceMs,
+    );
+  }, [
+    location,
+    onboarded,
+    sharedStatus?.gateway,
+    sharedWatchdogStatus?.health,
+    sharedWatchdogStatus?.lifecycle,
+    sharedWatchdogStatus?.operationInProgress,
+  ]);
+
+  useEffect(() => {
+    if (!onboarded || (!restartRequired && !restartingGateway)) return;
+    const id = setInterval(refreshRestartStatus, 2000);
+    return () => clearInterval(id);
+  }, [onboarded, restartRequired, restartingGateway, refreshRestartStatus]);
+
+  useEffect(() => {
+    const handleBrowseFileSaved = (event) => {
+      const savedPath = String(event?.detail?.path || "");
+      if (!shouldRequireRestartForBrowsePath(savedPath)) return;
+      setBrowseRestartRequired(true);
+    };
+    window.addEventListener("alphaclaw:browse-file-saved", handleBrowseFileSaved);
+    return () => {
+      window.removeEventListener("alphaclaw:browse-file-saved", handleBrowseFileSaved);
+    };
+  }, []);
+
+  const handleGatewayRestart = useCallback(async () => {
+    if (restartingGateway) return;
+    setRestartingGateway(true);
+    try {
+      const data = await restartGateway();
+      if (!data?.ok) throw new Error(data?.error || "Gateway restart failed");
+      setRestartRequired(!!data.restartRequired);
+      setBrowseRestartRequired(false);
+      setGatewayRestartSignal(Date.now());
+      refreshSharedStatuses();
+      showToast("Gateway restarted", "success");
+      setTimeout(refreshRestartStatus, 800);
+    } catch (err) {
+      showToast(err.message || "Restart failed", "error");
+      setTimeout(refreshRestartStatus, 800);
+    } finally {
+      setRestartingGateway(false);
+    }
+  }, [refreshRestartStatus, refreshSharedStatuses, restartingGateway]);
+
+  const handleOpenclawUpdate = useCallback(async () => {
+    if (openclawUpdateInProgress) {
+      return { ok: false, error: "OpenClaw update already in progress" };
+    }
+    setOpenclawUpdateInProgress(true);
+    try {
+      const data = await updateOpenclaw();
+      return data;
+    } finally {
+      setOpenclawUpdateInProgress(false);
+      refreshSharedStatuses();
+      setTimeout(refreshSharedStatuses, 1200);
+      setTimeout(refreshSharedStatuses, 3500);
+      setTimeout(refreshRestartStatus, 1200);
+    }
+  }, [openclawUpdateInProgress, refreshRestartStatus, refreshSharedStatuses]);
+
+  const handleOpenclawVersionActionComplete = useCallback(
+    ({ type }) => {
+      if (type !== "update") return;
+      refreshSharedStatuses();
+      setTimeout(refreshSharedStatuses, 1200);
+    },
+    [refreshSharedStatuses],
+  );
+
+  const handleAcUpdate = useCallback(async () => {
+    if (acUpdating) return;
+    setAcUpdating(true);
+    try {
+      const data = await updateAlphaclaw();
+      if (data.ok) {
+        showToast("AlphaClaw updated — restarting...", "success");
+        setTimeout(() => window.location.reload(), 5000);
+      } else {
+        showToast(data.error || "AlphaClaw update failed", "error");
+        setAcUpdating(false);
+      }
+    } catch (err) {
+      showToast(err.message || "Could not update AlphaClaw", "error");
+      setAcUpdating(false);
+    }
+  }, [acUpdating]);
+
+  return {
+    state: {
+      acHasUpdate,
+      acLatest,
+      acUpdating,
+      acVersion,
+      authEnabled,
+      gatewayRestartSignal,
+      isAnyRestartRequired,
+      onboarded,
+      openclawUpdateInProgress,
+      restartingGateway,
+      sharedDoctorStatus,
+      sharedStatus,
+      sharedWatchdogStatus,
+    },
+    actions: {
+      handleAcUpdate,
+      handleGatewayRestart,
+      handleOnboardingComplete: () => setOnboarded(true),
+      handleOpenclawUpdate,
+      handleOpenclawVersionActionComplete,
+      refreshSharedStatuses,
+      setRestartRequired,
+    },
+  };
+};

package/lib/public/js/hooks/use-app-shell-ui.js

@@ -0,0 +1,112 @@
+import { useState, useEffect, useRef, useCallback } from "https://esm.sh/preact/hooks";
+import { readUiSettings, writeUiSettings } from "../lib/ui-settings.js";
+
+const kDefaultSidebarWidthPx = 220;
+const kSidebarMinWidthPx = 180;
+const kSidebarMaxWidthPx = 460;
+
+const clampSidebarWidth = (value) =>
+  Math.max(kSidebarMinWidthPx, Math.min(kSidebarMaxWidthPx, value));
+
+export const useAppShellUi = () => {
+  const appShellRef = useRef(null);
+  const menuRef = useRef(null);
+  const [menuOpen, setMenuOpen] = useState(false);
+  const [sidebarWidthPx, setSidebarWidthPx] = useState(() => {
+    const settings = readUiSettings();
+    if (!Number.isFinite(settings.sidebarWidthPx)) return kDefaultSidebarWidthPx;
+    return clampSidebarWidth(settings.sidebarWidthPx);
+  });
+  const [isResizingSidebar, setIsResizingSidebar] = useState(false);
+  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
+  const [mobileTopbarScrolled, setMobileTopbarScrolled] = useState(false);
+
+  const closeMenu = useCallback((event) => {
+    if (menuRef.current && !menuRef.current.contains(event.target)) {
+      setMenuOpen(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (menuOpen) {
+      document.addEventListener("click", closeMenu, true);
+      return () => document.removeEventListener("click", closeMenu, true);
+    }
+  }, [closeMenu, menuOpen]);
+
+  useEffect(() => {
+    if (!mobileSidebarOpen) return;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = previousOverflow;
+    };
+  }, [mobileSidebarOpen]);
+
+  useEffect(() => {
+    const settings = readUiSettings();
+    settings.sidebarWidthPx = sidebarWidthPx;
+    writeUiSettings(settings);
+  }, [sidebarWidthPx]);
+
+  const resizeSidebarWithClientX = useCallback((clientX) => {
+    const shellElement = appShellRef.current;
+    if (!shellElement) return;
+    const shellBounds = shellElement.getBoundingClientRect();
+    const nextWidth = clampSidebarWidth(Math.round(clientX - shellBounds.left));
+    setSidebarWidthPx(nextWidth);
+  }, []);
+
+  const onSidebarResizerPointerDown = useCallback((event) => {
+    event.preventDefault();
+    setIsResizingSidebar(true);
+    resizeSidebarWithClientX(event.clientX);
+  }, [resizeSidebarWithClientX]);
+
+  useEffect(() => {
+    if (!isResizingSidebar) return () => {};
+    const onPointerMove = (event) => resizeSidebarWithClientX(event.clientX);
+    const onPointerUp = () => setIsResizingSidebar(false);
+    window.addEventListener("pointermove", onPointerMove);
+    window.addEventListener("pointerup", onPointerUp);
+    const previousUserSelect = document.body.style.userSelect;
+    const previousCursor = document.body.style.cursor;
+    document.body.style.userSelect = "none";
+    document.body.style.cursor = "col-resize";
+    return () => {
+      window.removeEventListener("pointermove", onPointerMove);
+      window.removeEventListener("pointerup", onPointerUp);
+      document.body.style.userSelect = previousUserSelect;
+      document.body.style.cursor = previousCursor;
+    };
+  }, [isResizingSidebar, resizeSidebarWithClientX]);
+
+  const handlePaneScroll = useCallback((event) => {
+    const nextScrolled = event.currentTarget.scrollTop > 0;
+    setMobileTopbarScrolled((currentScrolled) =>
+      currentScrolled === nextScrolled ? currentScrolled : nextScrolled,
+    );
+  }, []);
+
+  return {
+    refs: {
+      appShellRef,
+      menuRef,
+    },
+    state: {
+      isResizingSidebar,
+      menuOpen,
+      mobileSidebarOpen,
+      mobileTopbarScrolled,
+      sidebarWidthPx,
+    },
+    actions: {
+      closeMobileSidebar: () => setMobileSidebarOpen(false),
+      handlePaneScroll,
+      onSidebarResizerPointerDown,
+      onToggleMenu: () => setMenuOpen((open) => !open),
+      setMenuOpen,
+      setMobileSidebarOpen,
+    },
+  };
+};