From 78542e1a8a63214e2d77c4b85ae4225ef179f6bf Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Mon, 17 Aug 2026 22:07:24 -0400
Subject: [PATCH 1/2] feat(viewer): add recent posts home

---
 .changeset/bright-homes-gather.md |   5 +
 e2e/viewer.spec.ts                |  86 ++++++++++++++-
 viewer/src/App.tsx                |  34 ++++--
 viewer/src/Home.tsx               | 172 ++++++++++++++++++++++++++++++
 viewer/src/api.ts                 |  21 ++++
 viewer/src/state.ts               |  57 ++++++++--
 viewer/src/styles.css             | 128 ++++++++++++++++++++++
 7 files changed, 483 insertions(+), 20 deletions(-)
 create mode 100644 .changeset/bright-homes-gather.md
 create mode 100644 viewer/src/Home.tsx

diff --git a/.changeset/bright-homes-gather.md b/.changeset/bright-homes-gather.md
new file mode 100644
index 0000000..4c17ebf
--- /dev/null
+++ b/.changeset/bright-homes-gather.md
@@ -0,0 +1,5 @@
+---
+"sideshow": patch
+---
+
+Show a recent-posts Home view for first-time visitors to multi-session workspaces, with live updates and safe themed previews.
diff --git a/e2e/viewer.spec.ts b/e2e/viewer.spec.ts
index a91a31d..406b90b 100644
--- a/e2e/viewer.spec.ts
+++ b/e2e/viewer.spec.ts
@@ -368,6 +368,85 @@ test("a surface kind this viewer doesn't know shows a refresh hint, not a broken
   await expect(card.locator(".diff-error")).toHaveCount(0);
 });
 
+test("the workspace root shows a live recent posts home", async ({ page, server }) => {
+  const first = await publish(server.url, {
+    html: "<h2>first preview</h2>",
+    title: "First recent",
+    agent: "alpha",
+    sessionTitle: "Alpha work",
+  });
+  const second = await publish(server.url, {
+    html: "<h2>second preview</h2>",
+    title: "Second recent",
+    agent: "beta",
+    sessionTitle: "Beta work",
+  });
+
+  await page.goto(server.url);
+
+  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
+  await expect(page.locator(".home-card")).toHaveCount(2);
+  await expect(page.locator(".home-card-title")).toContainText(["Second recent", "First recent"]);
+  await expect(page.locator(".home-card", { hasText: "Alpha work" })).toContainText("First recent");
+  await expect(page.locator("#sessionView")).toHaveCount(0);
+  const preview = page.locator(".home-preview-frame").first();
+  await expect(preview).toHaveAttribute("sandbox", "allow-scripts");
+  await expect(preview).toHaveAttribute("src", /\/s\/.+\?part=0&ver=1&theme=.+&mode=(light|dark)$/);
+
+  // First-time Home is stable even when an event leaves only one session.
+  const removeSecond = await fetch(`${server.url}/api/sessions/${second.sessionId}`, {
+    method: "DELETE",
+  });
+  expect(removeSecond.ok).toBe(true);
+  await expect(page.locator(".home-card")).toHaveCount(1);
+  await expect(page.locator(".sess.sel")).toHaveCount(0);
+
+  const live = await publish(server.url, {
+    html: "<h2>live preview</h2>",
+    title: "Live recent",
+    agent: "gamma",
+    sessionTitle: "Gamma work",
+  });
+  await expect(page.locator(".home-card")).toHaveCount(2);
+  await expect(page.locator(".home-card-title").first()).toHaveText("Live recent");
+
+  await page.locator(".home-card", { hasText: "First recent" }).click();
+  await expect(page).toHaveURL(new RegExp(`/session/${first.sessionId}/p/${first.id}$`));
+  await expect(page.locator(`.card[data-id="${first.id}"] .card-title`)).toHaveText("First recent");
+
+  // Returning Home is intentional: later session events must not re-open the
+  // saved stream, and Home's session metadata must remain live.
+  await page.locator(".brand:visible").first().click();
+  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
+  const rename = await fetch(`${server.url}/api/sessions/${first.sessionId}`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ title: "Renamed Alpha" }),
+  });
+  expect(rename.ok).toBe(true);
+  await expect(page.locator(".home-card", { hasText: "First recent" })).toContainText(
+    "Renamed Alpha",
+  );
+  await expect(page.locator(".sess.sel")).toHaveCount(0);
+
+  const remove = await fetch(`${server.url}/api/sessions/${first.sessionId}`, { method: "DELETE" });
+  expect(remove.ok).toBe(true);
+  await expect(page.locator(".home-card")).toHaveCount(1);
+  await expect(page.locator(".home-card", { hasText: "First recent" })).toHaveCount(0);
+
+  // The explicit Home choice also remains stable once one session is left.
+  const renameOnly = await fetch(`${server.url}/api/sessions/${live.sessionId}`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ title: "Only remaining session" }),
+  });
+  expect(renameOnly.ok).toBe(true);
+  await expect(page.locator(".home-card", { hasText: "Live recent" })).toContainText(
+    "Only remaining session",
+  );
+  await expect(page.locator(".sess.sel")).toHaveCount(0);
+});
+
 test("opening a session shows a skeleton while posts load", async ({ page, server }) => {
   const first = await publish(server.url, {
     html: "<p>slow</p>",
@@ -626,10 +705,13 @@ test("Cmd+Option+Up/Down switches between sessions, wrapping at the ends", async
   await publish(server.url, { html: "<p>b</p>", title: "Second", agent: "two" });
 
   await page.goto(server.url);
-  // the newest session sits at the top of the list and is selected on load
+  await expect(page.getByRole("heading", { name: "Home" })).toBeVisible();
+
+  // With no selected session on Home, Down opens the newest session.
+  await page.keyboard.press("Meta+Alt+ArrowDown");
   await expect(page.locator(".sess.sel .sess-title")).toContainText("two session");
 
-  // Down moves to the next (older) session down the list
+  // Down then moves to the next (older) session down the list.
   await page.keyboard.press("Meta+Alt+ArrowDown");
   await expect(page.locator(".sess.sel .sess-title")).toContainText("one session");
 
diff --git a/viewer/src/App.tsx b/viewer/src/App.tsx
index 9eb9508..96d62f7 100644
--- a/viewer/src/App.tsx
+++ b/viewer/src/App.tsx
@@ -15,6 +15,7 @@ import {
 import { host, isShadow, navHostEl, root, SLOTS } from "./host.ts";
 import { applyFrameHeight, Card, cardForPost, frameForSource } from "./Card.tsx";
 import { ConnectInstructions } from "./Connect.tsx";
+import { HomeView, isHomePreviewFrame, resizeHomeFrame } from "./Home.tsx";
 import { renderNotes } from "./notes.ts";
 import { SessionTimeline } from "./SessionTimeline.tsx";
 import { StreamSkeleton } from "./Skeleton.tsx";
@@ -82,6 +83,8 @@ const [connectPath, setConnectPath] = createSignal(isConnectPath());
 // current session's stream. Driven by the host's `layout` (cloud embed) or the
 // self-hosted public-read "session" link (see api.ts `layoutMode`).
 const streamMode = () => layoutMode() === "stream";
+const homePath = () =>
+  !streamMode() && !connectPath() && initialLoaded() && sessions.length > 0 && !selected();
 
 // The wordmark, doubling as a home link: clicking it clears the current session
 // and returns to the empty workspace (goHome). A real <button> so it's keyboard- and
@@ -345,12 +348,19 @@ export default function App() {
                 <Show
                   when={connectPath()}
                   fallback={
-                    <>
-                      <Show when={!streamMode()}>
-                        <Onboard />
-                      </Show>
-                      <SessionView />
-                    </>
+                    <Show
+                      when={homePath()}
+                      fallback={
+                        <>
+                          <Show when={!streamMode()}>
+                            <Onboard />
+                          </Show>
+                          <SessionView />
+                        </>
+                      }
+                    >
+                      <HomeView />
+                    </Show>
                   }
                 >
                   <ConnectPage />
@@ -492,6 +502,7 @@ async function onBridgeMessage(ev: MessageEvent) {
     key?: string;
   } | null;
   if (!d || !d.__sideshow) return;
+  const fromHomePreview = isHomePreviewFrame(ev.source);
   // Every host-affecting message must come from a frame the viewer actually
   // embedded — never an unexpected/nested frame. send-prompt and resize prove
   // this implicitly (frameForSource resolves the exact html frame); the
@@ -500,7 +511,7 @@ async function onBridgeMessage(ev: MessageEvent) {
   // by those, but open-link is sent by rich-surface frames too, so use the
   // broader check that recognizes any embedded iframe.)
   if (d.type === "switch-session") {
-    if (!isOwnFrame(ev.source)) return;
+    if (fromHomePreview || !isOwnFrame(ev.source)) return;
     if (streamMode()) return;
     // A post iframe forwarded the session-switch shortcut because focus was
     // inside it (see server/surfacePage.ts). Mirror the parent keydown handler.
@@ -510,8 +521,9 @@ async function onBridgeMessage(ev: MessageEvent) {
   // Resolve the source post + iframe by contentWindow — a post may own
   // several html-surface iframes, so resize must target the exact one.
   const src = frameForSource(ev.source);
-  if (d.type === "resize" && src) {
-    applyFrameHeight(src.iframe, d.height);
+  if (d.type === "resize") {
+    if (src) applyFrameHeight(src.iframe, d.height);
+    else resizeHomeFrame(ev.source, d.height);
   } else if (d.type === "send-prompt" && src) {
     if (isReadonly()) return;
     // sendPrompt is post-originated: a script inside the sandbox can fire it
@@ -528,7 +540,7 @@ async function onBridgeMessage(ev: MessageEvent) {
       body: JSON.stringify({ surface: src.id, text: String(d.text), author: "surface" }),
     });
     toast("Added to this post’s thread");
-  } else if (d.type === "open-link" && isOwnFrame(ev.source)) {
+  } else if (d.type === "open-link" && !fromHomePreview && isOwnFrame(ev.source)) {
     // Only ever open real external links. The in-frame click handler forwards
     // just http(s) hrefs, but a post can call openLink() directly (or post
     // this message raw) with any scheme — javascript:, data:, file: — so
@@ -545,7 +557,7 @@ async function onBridgeMessage(ev: MessageEvent) {
     if (link.protocol !== "http:" && link.protocol !== "https:") return;
     if (confirm(`Open external link?\n\n${link.href}`))
       window.open(link.href, "_blank", "noopener,noreferrer");
-  } else if (d.type === "copy" && isOwnFrame(ev.source)) {
+  } else if (d.type === "copy" && !fromHomePreview && isOwnFrame(ev.source)) {
     void navigator.clipboard?.writeText(String(d.text)).catch(() => {});
   }
 }
diff --git a/viewer/src/Home.tsx b/viewer/src/Home.tsx
new file mode 100644
index 0000000..13f5d3a
--- /dev/null
+++ b/viewer/src/Home.tsx
@@ -0,0 +1,172 @@
+import { createResource, For, onCleanup, Show } from "solid-js";
+import { isSandboxedSurfaceKind, SURFACE_FRAME_CLASSES } from "../../server/types.ts";
+import { appPath, getRecentPosts, relTime, type RecentPostRow, type RecentSurface } from "./api.ts";
+import { activeTheme, resolvedMode } from "./theme.ts";
+import { homeRefreshVersion, select } from "./state.ts";
+import { StreamSkeleton } from "./Skeleton.tsx";
+
+const previewFrames = new Set<HTMLIFrameElement>();
+
+// The App-level bridge listener delegates Home resize messages here. This stays
+// separate from Card's post-keyed registry: Home can show surfaces from several
+// sessions, and two embedded engines can coexist in one module realm.
+export function isHomePreviewFrame(source: unknown): boolean {
+  for (const frame of previewFrames) {
+    if (frame.contentWindow === source) return true;
+  }
+  return false;
+}
+
+export function resizeHomeFrame(source: unknown, height: unknown): boolean {
+  if (!Number.isFinite(height)) return false;
+  for (const frame of previewFrames) {
+    if (frame.contentWindow === source) {
+      frame.style.height = `${Math.min(240, Math.max(120, Math.round(height as number)))}px`;
+      return true;
+    }
+  }
+  return false;
+}
+
+function sessionTitle(post: RecentPostRow): string {
+  return post.sessionTitle || (post.agent ? `${post.agent} session` : "Untitled session");
+}
+
+function partSummary(post: RecentPostRow): string {
+  return post.partKinds.length === 0 ? "post" : post.partKinds.join(" · ");
+}
+
+function postHref(post: RecentPostRow): string {
+  return appPath(`/session/${encodeURIComponent(post.sessionId)}/p/${encodeURIComponent(post.id)}`);
+}
+
+function surfaceSrc(post: RecentPostRow, surface: RecentSurface): string {
+  return appPath(
+    `/s/${encodeURIComponent(post.id)}?part=${surface.index}&ver=${post.version}&theme=${activeTheme()}&mode=${resolvedMode()}`,
+  );
+}
+
+function JsonPreview(props: { surface: RecentSurface }) {
+  const text = () =>
+    JSON.stringify(props.surface.kind === "json" ? props.surface.data : null, null, 2);
+  return <pre class="home-json-preview">{text()}</pre>;
+}
+
+function ImagePreview(props: {
+  post: RecentPostRow;
+  surface: Extract<RecentSurface, { kind: "image" }>;
+}) {
+  return (
+    <img
+      class="home-image-preview"
+      src={appPath(`/a/${encodeURIComponent(props.surface.assetId)}`)}
+      alt={props.surface.alt ?? props.post.title}
+      loading="lazy"
+    />
+  );
+}
+
+function NativePreview(props: { post: RecentPostRow; surface: RecentSurface }) {
+  const surface = () => props.surface;
+  return (
+    <Show
+      when={
+        surface().kind === "image" ? (surface() as Extract<RecentSurface, { kind: "image" }>) : null
+      }
+      fallback={
+        <Show
+          when={surface().kind === "json"}
+          fallback={<div class="home-data-preview">{surface().kind} surface</div>}
+        >
+          <JsonPreview surface={surface()} />
+        </Show>
+      }
+    >
+      {(image) => <ImagePreview post={props.post} surface={image()} />}
+    </Show>
+  );
+}
+
+function SurfacePreview(props: { post: RecentPostRow; surface: RecentSurface }) {
+  let frame: HTMLIFrameElement | undefined;
+  onCleanup(() => {
+    if (frame) previewFrames.delete(frame);
+  });
+  const surface = () => props.surface;
+  return (
+    <Show
+      when={isSandboxedSurfaceKind(surface().kind)}
+      fallback={<NativePreview post={props.post} surface={surface()} />}
+    >
+      <iframe
+        class={`home-preview-frame ${SURFACE_FRAME_CLASSES[surface().kind] ?? ""}`}
+        src={surfaceSrc(props.post, surface())}
+        title={`${props.post.title} preview`}
+        sandbox="allow-scripts"
+        loading="lazy"
+        aria-hidden="true"
+        tabIndex={-1}
+        ref={(el) => {
+          frame = el;
+          previewFrames.add(el);
+        }}
+      />
+    </Show>
+  );
+}
+
+function HomeCard(props: { post: RecentPostRow }) {
+  const open = (event: MouseEvent) => {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0)
+      return;
+    event.preventDefault();
+    void select(props.post.sessionId, { initialPostId: props.post.id });
+  };
+  return (
+    <a class="home-card" href={postHref(props.post)} onClick={open}>
+      <div class="home-card-head">
+        <span class="home-card-title">{props.post.title}</span>
+        <span class="home-card-meta">{relTime(props.post.updatedAt)}</span>
+      </div>
+      <div class="home-card-sub">
+        {sessionTitle(props.post)} · {partSummary(props.post)}
+      </div>
+      <Show when={props.post.surfaces[0]}>
+        {(surface) => (
+          <div class="home-previews" aria-hidden="true">
+            <SurfacePreview post={props.post} surface={surface()} />
+          </div>
+        )}
+      </Show>
+      <div class="home-card-foot">View full post →</div>
+    </a>
+  );
+}
+
+export function HomeView() {
+  const [recent] = createResource(homeRefreshVersion, () => getRecentPosts(30).catch(() => []));
+  const posts = () => recent() ?? [];
+  return (
+    <section class="home-page" aria-label="Home">
+      <header class="home-head">
+        <h1>Home</h1>
+        <p>Recent posts across your sideshow sessions.</p>
+      </header>
+      <Show when={!recent.loading} fallback={<StreamSkeleton />}>
+        <Show
+          when={posts().length > 0}
+          fallback={
+            <div class="home-empty">
+              <h2>No posts yet</h2>
+              <p>Open a session from the sidebar, or connect an agent to start publishing.</p>
+            </div>
+          }
+        >
+          <div class="home-feed">
+            <For each={posts()}>{(post) => <HomeCard post={post} />}</For>
+          </div>
+        </Show>
+      </Show>
+    </section>
+  );
+}
diff --git a/viewer/src/api.ts b/viewer/src/api.ts
index 58de672..13684ff 100644
--- a/viewer/src/api.ts
+++ b/viewer/src/api.ts
@@ -56,6 +56,23 @@ export interface VersionInfo {
   notes?: string | null;
 }
 
+// A bounded, cross-session row returned by GET /api/posts/recent. Sandboxed
+// surface bodies are never rendered from this data; Home uses their /s document.
+export type RecentSurface = Surface & { index: number; truncated?: boolean };
+
+export interface RecentPostRow {
+  id: string;
+  sessionId: string;
+  sessionTitle: string | null;
+  agent: string | null;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  version: number;
+  surfaces: RecentSurface[];
+  partKinds: string[];
+}
+
 declare global {
   interface Window {
     // __SIDESHOW_BASE_PATH__ lives in host.ts (the default host reads it).
@@ -128,6 +145,10 @@ export async function api<T = unknown>(path: string, init?: RequestInit): Promis
   return res.json() as Promise<T>;
 }
 
+export function getRecentPosts(limit = 30): Promise<RecentPostRow[]> {
+  return api<RecentPostRow[]>(`/api/posts/recent?limit=${limit}`);
+}
+
 export const sessionLabel = (s: Session) => s.title || s.agent + " session";
 
 export function relTime(iso: string): string {
diff --git a/viewer/src/state.ts b/viewer/src/state.ts
index d0e99b5..8cac443 100644
--- a/viewer/src/state.ts
+++ b/viewer/src/state.ts
@@ -67,6 +67,11 @@ export function groupSessions(list: readonly SessionRow[], now: Date): SessionGr
 }
 const [selectedState, setSelectedInternal] = createSignal<string | null>(null);
 export const selected = selectedState;
+// True after the user (or browser history) explicitly returns to the sessionless
+// Home route. It prevents later lifecycle events from treating Home as merely a
+// missing selection and reopening a stream.
+const [explicitHomeState, setExplicitHome] = createSignal(false);
+const explicitHome = explicitHomeState;
 
 // Standalone (direct-link) mode: a bare /s/:id route with no session shows that
 // one post full-page — no sidebar, no session feed, no comments — instead of
@@ -109,6 +114,11 @@ export const [scrollTarget, setScrollTarget] = createSignal<string | null>(null)
 // Post id the "new post ↓" pill jumps to — set instead of scrolling
 // when the user is reading further up.
 export const [pillTarget, setPillTarget] = createSignal<string | null>(null);
+// Increments after a coalesced post mutation so a mounted Home resource can
+// refresh without polling. No Home is mounted in stream-only/embedded host-home
+// views, so the signal is inert there.
+const [homeRefreshVersionState, setHomeRefreshVersion] = createSignal(0);
+export const homeRefreshVersion = homeRefreshVersionState;
 
 const [toastTextState, setToastTextInternal] = createSignal("");
 export const toastText = toastTextState;
@@ -221,6 +231,10 @@ function isConnectRoute(): boolean {
   return location.pathname === appPath("/connect");
 }
 
+function isSessionlessHomeRoute(route = host().router.get()): boolean {
+  return !route.sessionId && !route.surfaceId && !isConnectRoute();
+}
+
 export async function refreshSessions(targetPostId?: string | null) {
   if (isReadonly() && publicReadMode() === "session") {
     const route = host().router.get();
@@ -265,10 +279,16 @@ export async function refreshSessions(targetPostId?: string | null) {
     // host's home shows with nothing selected (no auto-open, no highlight).
     const route = host().router.get();
     const lastId = localStorage.getItem(LAST_SESSION_KEY);
+    const validLastId = lastId && sessions.some((s) => s.id === lastId) ? lastId : null;
+    // Preserve the familiar return-to-last-session and single-session boot paths.
+    // A first-time visitor to a multi-session workspace instead lands on Home;
+    // remember that choice so a later deletion down to one session stays there.
+    const initialHome = isSessionlessHomeRoute(route) && !validLastId && sessions.length > 1;
+    if (initialHome) setExplicitHome(true);
     const fallback =
-      host().homeView || isConnectRoute()
+      host().homeView || explicitHome() || isConnectRoute() || initialHome
         ? null
-        : (lastId && sessions.some((s) => s.id === lastId) && lastId) || sessions[0].id;
+        : validLastId || sessions[0].id;
     const target =
       (route.sessionId && sessions.some((s) => s.id === route.sessionId) && route.sessionId) ||
       fallback;
@@ -314,6 +334,7 @@ export async function select(
   id: string,
   opts?: { fromPopState?: boolean; replace?: boolean; initialPostId?: string },
 ) {
+  setExplicitHome(false);
   setSelectedInternal(id);
   if (opts?.fromPopState) {
     // The host already moved the route (back/forward); don't touch it.
@@ -366,6 +387,11 @@ export function focusPost(postId: string) {
 // clears it. The host itself dedupes a no-op move. applyRoute ignores a null
 // sessionId (back/forward to home shouldn't thrash a load), so we deselect here.
 export function goHome() {
+  // Home is an explicit navigation choice, not a temporary deselection. Forget
+  // the auto-open hint so subsequent session events cannot pull the user back
+  // into the last stream.
+  localStorage.removeItem(LAST_SESSION_KEY);
+  setExplicitHome(true);
   setSelectedInternal(null);
   setNavOpen(false);
   host().router.navigate({ sessionId: null, surfaceId: null });
@@ -385,11 +411,12 @@ export function applyRoute(route: Route) {
       fromPopState: true,
       initialPostId: route.surfaceId ?? undefined,
     });
-  } else if (!route.sessionId && host().homeView && selected()) {
-    // A host that owns a session-less landing: a route with no session IS that
-    // home view, so clear the selection — otherwise the previously-open session
-    // stays highlighted behind the host's home. (Self-hosted leaves homeView off
-    // and keeps ignoring a null route here; it deselects explicitly via goHome.)
+  } else if (!route.sessionId && (host().homeView || isSessionlessHomeRoute(route)) && selected()) {
+    // A session-less route is a Home view, so clear the prior selection rather
+    // than leaving a session highlighted behind it. Browser Back to Home is as
+    // intentional as the wordmark click, so don't later auto-open the old stream.
+    localStorage.removeItem(LAST_SESSION_KEY);
+    setExplicitHome(true);
     setSelectedInternal(null);
   }
 }
@@ -513,6 +540,16 @@ const WS_HEARTBEAT_MS = 30_000;
 const WS_RECONNECT_MS = 1000;
 const FEED_SESSION_REFRESH_DELAY_MS = 50;
 const FEED_SESSION_REFRESH_MAX_WAIT_MS = 250;
+const HOME_REFRESH_DELAY_MS = 100;
+
+let homeRefreshTimer: ReturnType<typeof setTimeout> | undefined;
+function scheduleHomeRefresh() {
+  if (homeRefreshTimer !== undefined) return;
+  homeRefreshTimer = setTimeout(() => {
+    homeRefreshTimer = undefined;
+    setHomeRefreshVersion((version) => version + 1);
+  }, HOME_REFRESH_DELAY_MS);
+}
 
 let feedSessionRefreshVersion = 0;
 let pendingFeedSessionRefresh: Promise<void> | undefined;
@@ -572,13 +609,16 @@ async function handleFeedData(data: string) {
   if (e.type === "theme-changed") {
     applyTheme(e.id);
   } else if (e.type.startsWith("session-")) {
+    scheduleHomeRefresh();
     await refreshSessions();
   } else if (e.type === "post-created" || e.type === "post-updated") {
     if (away && e.sessionId) markUnread(e.sessionId);
+    scheduleHomeRefresh();
     const sessionRefresh = refreshSessionsAfterFeedEvent();
     if (e.sessionId === selected()) await upsertPost(e.id);
     await sessionRefresh;
   } else if (e.type === "post-deleted") {
+    scheduleHomeRefresh();
     const idx = posts.findIndex((s) => s.id === e.id);
     if (idx >= 0) setPostsInternal(produce((arr) => arr.splice(idx, 1)));
     await refreshSessionsAfterFeedEvent();
@@ -674,6 +714,9 @@ function connectWebSocket(): () => void {
 async function resyncSelected() {
   const before = selected();
   await refreshSessions();
+  // A reconnect may have missed post or session changes while Home was open.
+  // Bump after the session refresh so a Home card can't retain a deleted session.
+  scheduleHomeRefresh();
   if (!before || selected() !== before) return; // select() rebuilt the stream
   void fetchTrace(before);
   const details = await fetchSessionPostDetails(before);
diff --git a/viewer/src/styles.css b/viewer/src/styles.css
index e74fdce..fffbb6a 100644
--- a/viewer/src/styles.css
+++ b/viewer/src/styles.css
@@ -563,6 +563,134 @@ main {
   color: var(--muted);
 }
 
+.home-page {
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 34px 22px 70px;
+}
+.home-head {
+  margin-bottom: 20px;
+}
+.home-head h1 {
+  margin: 0 0 6px;
+  font-size: 28px;
+  letter-spacing: -0.03em;
+}
+.home-head p {
+  margin: 0;
+  color: var(--muted);
+}
+.home-feed {
+  display: grid;
+  gap: 16px;
+}
+.home-card {
+  display: block;
+  color: inherit;
+  text-decoration: none;
+  background: var(--surface);
+  border: 0.5px solid var(--border);
+  border-radius: 14px;
+  overflow: hidden;
+  transition:
+    border-color 0.15s ease,
+    box-shadow 0.15s ease,
+    transform 0.15s ease;
+}
+.home-card:hover,
+.home-card:focus-visible {
+  border-color: color-mix(in srgb, var(--accent) 40%, var(--border));
+  box-shadow: 0 14px 40px rgba(0, 0, 0, 0.12);
+  transform: translateY(-1px);
+  outline: none;
+}
+.home-card-head {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 13px 16px 2px;
+}
+.home-card-title {
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-weight: 600;
+}
+.home-card-meta,
+.home-card-sub,
+.home-card-foot {
+  color: var(--faint);
+  font-size: 12px;
+}
+.home-card-sub {
+  padding: 0 16px 12px;
+}
+.home-previews {
+  display: grid;
+  gap: 10px;
+  padding: 0 16px 14px;
+  max-height: 270px;
+  overflow: hidden;
+  position: relative;
+}
+.home-previews::after {
+  content: "";
+  position: absolute;
+  inset: auto 16px 14px;
+  height: 52px;
+  pointer-events: none;
+  background: linear-gradient(to bottom, transparent, var(--surface));
+}
+.home-preview-frame,
+.home-image-preview,
+.home-json-preview,
+.home-data-preview {
+  width: 100%;
+  min-height: 120px;
+  border: 0.5px solid var(--border);
+  border-radius: 10px;
+  background: var(--bg);
+}
+.home-preview-frame {
+  height: 210px;
+  pointer-events: none;
+}
+.home-image-preview {
+  display: block;
+  max-height: 240px;
+  object-fit: contain;
+}
+.home-json-preview,
+.home-data-preview {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 12px;
+  color: var(--muted);
+  font: 12px/1.5 var(--mono);
+  overflow: hidden;
+  white-space: pre-wrap;
+}
+.home-card-foot {
+  padding: 11px 16px 13px;
+  border-top: 0.5px solid var(--border);
+}
+.home-empty {
+  background: var(--surface);
+  border: 0.5px solid var(--border);
+  border-radius: 14px;
+  padding: 26px;
+  text-align: center;
+}
+.home-empty h2 {
+  margin: 0 0 6px;
+}
+.home-empty p {
+  margin: 0;
+  color: var(--muted);
+}
+
 .card {
   background: var(--surface);
   border: 0.5px solid var(--border);

From 984e2827df922fe9bd725ecb16508ece39d5786f Mon Sep 17 00:00:00 2001
From: Ben Vinegar <ben@benv.ca>
Date: Mon, 17 Aug 2026 22:19:37 -0400
Subject: [PATCH 2/2] fix(viewer): bound home feed previews

---
 e2e/embed-home-view.spec.ts  |  1 +
 server/apiViews.ts           | 19 +++++++++++++++++--
 server/app.ts                | 11 +++++++----
 test/surfaces-recent.test.ts | 23 +++++++++++++++++++++++
 viewer/src/App.tsx           |  7 ++++++-
 viewer/src/api.ts            | 17 +++++++++++++----
 6 files changed, 67 insertions(+), 11 deletions(-)

diff --git a/e2e/embed-home-view.spec.ts b/e2e/embed-home-view.spec.ts
index ea2961d..43eda5a 100644
--- a/e2e/embed-home-view.spec.ts
+++ b/e2e/embed-home-view.spec.ts
@@ -64,6 +64,7 @@ test("homeView: a session-less route lands with NO session selected", async ({ p
   await expect(page.locator(".sess.sel")).toHaveCount(0);
   await expect(page.locator(".sess[aria-current='true']")).toHaveCount(0);
   await expect(page.locator(".card:not(#whatsNew)")).toHaveCount(0);
+  await expect(page.locator(".home-page")).toHaveCount(0);
 });
 
 test("homeView OFF (self-hosted default): a session-less route auto-selects the latest", async ({
diff --git a/server/apiViews.ts b/server/apiViews.ts
index 82fcf89..dc53f3f 100644
--- a/server/apiViews.ts
+++ b/server/apiViews.ts
@@ -246,8 +246,23 @@ export const recentSurfacePreviewView = (surface: Surface, index: number) => ({
   index,
 });
 
-export const recentPostRowView = (post: Post, session: Session | null | undefined) => {
-  const surfaces = post.surfaces.map(recentSurfacePreviewView);
+// The self-hosted Home uses one preview per post. Rich surfaces render from their
+// immutable /s document and trace only needs a kind label, so only image/json
+// retain inline data. This bounds Home's 30-row response without weakening the
+// full recent-feed contract used by embedders.
+export const recentHomeSurfaceView = (surface: Surface, index: number) =>
+  surface.kind === "image" || surface.kind === "json"
+    ? recentSurfacePreviewView(surface, index)
+    : surfaceRef(surface, index);
+
+export const recentPostRowView = (
+  post: Post,
+  session: Session | null | undefined,
+  opts?: { homePreview?: boolean },
+) => {
+  const surfaces = opts?.homePreview
+    ? post.surfaces.slice(0, 1).map(recentHomeSurfaceView)
+    : post.surfaces.map(recentSurfacePreviewView);
   return {
     id: post.id,
     sessionId: post.sessionId,
diff --git a/server/app.ts b/server/app.ts
index 46196f2..f3a2f17 100644
--- a/server/app.ts
+++ b/server/app.ts
@@ -1056,13 +1056,14 @@ export function createApp({
   // agent for the feed card, canonical surfaces, legacy partKinds, and capped
   // previews.
   //
-  // Previews are bounded by recentPostRowView (large inline text clipped with
-  // truncated:true); images travel as plain assetId refs (served at /a/:id),
-  // so the response stays cheap. Same auth as /api/sessions — see
+  // Full previews are bounded by recentPostRowView (large inline text clipped
+  // with truncated:true); `?preview=home` returns only one compact preview per
+  // post for the self-hosted Home. Same auth as /api/sessions — see
   // isPublicReadAllowed, which intentionally does NOT expose this path on a
   // session-scoped publicRead workspace.
   const listRecentPosts = async (c: any) => {
     const limit = parseRecentLimit(c.req.query("limit"));
+    const homePreview = c.req.query("preview") === "home";
     const posts = await store.listRecentPosts(limit);
     // Resolve each post's session once (agent + session title for the feed card).
     const sessions = new Map<string, Session | null>();
@@ -1070,7 +1071,9 @@ export function createApp({
       if (!sessions.has(p.sessionId))
         sessions.set(p.sessionId, await store.getSession(p.sessionId));
     }
-    return c.json(posts.map((p) => recentPostRowView(p, sessions.get(p.sessionId))));
+    return c.json(
+      posts.map((p) => recentPostRowView(p, sessions.get(p.sessionId), { homePreview })),
+    );
   };
   app.get("/api/surfaces/recent", listRecentPosts);
   app.get("/api/posts/recent", listRecentPosts);
diff --git a/test/surfaces-recent.test.ts b/test/surfaces-recent.test.ts
index 3b7815f..1822536 100644
--- a/test/surfaces-recent.test.ts
+++ b/test/surfaces-recent.test.ts
@@ -188,6 +188,29 @@ test("GET /api/surfaces/recent caps oversized text parts and flags truncation",
   assert.equal(code.truncated, undefined);
 });
 
+test("GET /api/posts/recent?preview=home returns one compact surface per post", async () => {
+  const app = makeApp();
+  const s = await createSession(app, "amp");
+  await publish(app, {
+    session: s.id,
+    parts: [
+      { kind: "html", html: "x".repeat(20_000) },
+      { kind: "markdown", markdown: "# hidden from Home" },
+      { kind: "json", data: { also: "hidden from Home" } },
+    ],
+  });
+
+  const feed = (await (await app.request("/api/posts/recent?preview=home")).json()) as any[];
+  assert.deepEqual(feed[0].partKinds, ["html", "markdown", "json"]);
+  assert.equal(feed[0].surfaces.length, 1);
+  assert.deepEqual(feed[0].surfaces[0], {
+    id: feed[0].surfaces[0].id,
+    kind: "html",
+    index: 0,
+  });
+  assert.deepEqual(feed[0].parts, feed[0].surfaces);
+});
+
 test("GET /api/surfaces/recent leaves image parts as plain assetId refs", async () => {
   const app = makeApp();
   const s = await createSession(app, "amp");
diff --git a/viewer/src/App.tsx b/viewer/src/App.tsx
index 96d62f7..f20f7df 100644
--- a/viewer/src/App.tsx
+++ b/viewer/src/App.tsx
@@ -84,7 +84,12 @@ const [connectPath, setConnectPath] = createSignal(isConnectPath());
 // self-hosted public-read "session" link (see api.ts `layoutMode`).
 const streamMode = () => layoutMode() === "stream";
 const homePath = () =>
-  !streamMode() && !connectPath() && initialLoaded() && sessions.length > 0 && !selected();
+  !host().homeView &&
+  !streamMode() &&
+  !connectPath() &&
+  initialLoaded() &&
+  sessions.length > 0 &&
+  !selected();
 
 // The wordmark, doubling as a home link: clicking it clears the current session
 // and returns to the empty workspace (goHome). A real <button> so it's keyboard- and
diff --git a/viewer/src/api.ts b/viewer/src/api.ts
index 13684ff..3d6ca64 100644
--- a/viewer/src/api.ts
+++ b/viewer/src/api.ts
@@ -56,9 +56,18 @@ export interface VersionInfo {
   notes?: string | null;
 }
 
-// A bounded, cross-session row returned by GET /api/posts/recent. Sandboxed
-// surface bodies are never rendered from this data; Home uses their /s document.
-export type RecentSurface = Surface & { index: number; truncated?: boolean };
+// A compact, cross-session row returned by GET /api/posts/recent?preview=home.
+// Sandboxed surface bodies are never rendered from this data; Home uses their
+// /s document. Image and JSON retain the small native payload Home needs.
+type RecentSurfaceRef = {
+  id: string;
+  index: number;
+  truncated?: boolean;
+  kind: Exclude<Surface["kind"], "image" | "json">;
+};
+type RecentImageSurface = ImageSurface & { index: number; truncated?: boolean };
+type RecentJsonSurface = JsonSurface & { index: number; truncated?: boolean };
+export type RecentSurface = RecentSurfaceRef | RecentImageSurface | RecentJsonSurface;
 
 export interface RecentPostRow {
   id: string;
@@ -146,7 +155,7 @@ export async function api<T = unknown>(path: string, init?: RequestInit): Promis
 }
 
 export function getRecentPosts(limit = 30): Promise<RecentPostRow[]> {
-  return api<RecentPostRow[]>(`/api/posts/recent?limit=${limit}`);
+  return api<RecentPostRow[]>(`/api/posts/recent?limit=${limit}&preview=home`);
 }
 
 export const sessionLabel = (s: Session) => s.title || s.agent + " session";