feat: deep-linkable session and surface URLs (#78)

* feat(server): serve the viewer SPA at /session/:id and /session/:id/s/:surfaceId

Add two new GET routes that serve the same viewer HTML document
as the root (/). This lets the SPA handle deep links to specific
sessions and surfaces — the server does not validate the ids,
leaving resolution to the client.

Routes:
  /session/:id              — viewer with a session pre-selected
  /session/:id/s/:surfaceId — viewer with session + surface focused

The standalone surface route (/s/:id) is unchanged.

Both routes respect auth when SIDESHOW_TOKEN is configured, matching
the existing behavior of the root route.

Covered by four new unit tests in test/api.test.ts.

* feat(viewer): sync URL with session/surface navigation

The viewer URL now reflects what the user is looking at, making
every position in the board a shareable, resumable deep link.

URL scheme:
  /session/:id              — session selected in the sidebar
  /session/:id/s/:surfaceId — session + surface in view
  /                         — redirects to last-viewed session (localStorage)
  /s/:id                    — standalone surface (unchanged)

Behavior:
- Clicking a session in the sidebar pushes /session/:id.
- Scrolling past surfaces updates /session/:id/s/:surfaceId via
  replaceState (IntersectionObserver at 50% threshold), so the
  address bar always reflects the visible card without polluting
  browser history.
- Navigating directly to a session/surface URL selects the session
  and scrolls to the surface on load.
- The root (/) checks the URL, then localStorage, then falls back
  to the first session — using replaceState so the initial redirect
  does not create an extra history entry.
- Browser back/forward triggers popstate, which re-selects the
  session without pushing a duplicate entry.

Covered by seven new e2e tests in e2e/url-routing.spec.ts.

* fix(viewer): drop scroll-to-surface on deep link, navigate to session top

Surface deep links (/session/:id/s/:surfaceId) now navigate to the
session and show it from the top instead of attempting to scroll to
the specific surface. The surface suffix is still preserved in the
URL for shareability.

scrollIntoView is unreliable here: cards contain sandboxed iframes
whose height resolves asynchronously, so cards above the target
shift the layout after the scroll fires. Rather than add fragile
retry/timing hacks, accept the simpler behavior — the session-level
deep link is the main value, and the surface id in the URL still
updates live as the user scrolls.

* chore: add changeset for URL routing feature

Author: elucid

.changeset/url-routing.md

@@ -0,0 +1,5 @@
+---
+"sideshow": minor
+---
+
+Deep-linkable URLs: the viewer URL now reflects the current session and surface (`/session/:id`, `/session/:id/s/:surfaceId`). Clicking sessions pushes browser history, scrolling updates the surface in the URL via `replaceState`, and `/` redirects to the last-viewed session. Back/forward navigation works across sessions.

e2e/url-routing.spec.ts

@@ -0,0 +1,119 @@
+import { expect, publish, test } from "./fixtures.ts";
+
+test("clicking a session updates the URL to /session/:id", async ({ page, server }) => {
+  const s1 = await publish(server.url, { html: "<p>one</p>", title: "First", agent: "a1" });
+  const s2 = await publish(server.url, { html: "<p>two</p>", title: "Second", agent: "a2" });
+  await page.goto(server.url);
+  await expect(page.locator("#sessionList .sess")).toHaveCount(2);
+
+  // click the second session row
+  await page.locator(`#sessionList .sess[data-id="${s2.sessionId}"]`).click();
+  await expect(page).toHaveURL(new RegExp(`/session/${s2.sessionId}$`));
+
+  // click the first session row
+  await page.locator(`#sessionList .sess[data-id="${s1.sessionId}"]`).click();
+  await expect(page).toHaveURL(new RegExp(`/session/${s1.sessionId}$`));
+});
+
+test("navigating to /session/:id selects that session", async ({ page, server }) => {
+  await publish(server.url, { html: "<p>one</p>", title: "First", agent: "a1" });
+  const s2 = await publish(server.url, { html: "<p>two</p>", title: "Second", agent: "a2" });
+
+  // go directly to the second session
+  await page.goto(`${server.url}/session/${s2.sessionId}`);
+  await expect(page.locator(`#sessionList .sess[data-id="${s2.sessionId}"]`)).toHaveClass(/sel/);
+  await expect(page.locator(".card .card-title")).toHaveText("Second");
+});
+
+test("navigating to /session/:id/s/:surfaceId selects the session", async ({ page, server }) => {
+  const s1 = await publish(server.url, { html: "<p>first</p>", title: "A", agent: "pi" });
+  const s2 = await publish(server.url, {
+    html: "<p>second</p>",
+    title: "B",
+    agent: "pi",
+    session: s1.sessionId,
+  });
+
+  // deep link with a surface id selects the session
+  await page.goto(`${server.url}/session/${s1.sessionId}/s/${s2.id}`);
+  await expect(page.locator(`#sessionList .sess[data-id="${s1.sessionId}"]`)).toHaveClass(/sel/);
+  // both surfaces should be loaded (full session view)
+  await expect(page.locator(".card:not(#whatsNew) .card-title")).toHaveCount(2);
+});
+
+test("browser back/forward navigates between sessions", async ({ page, server }) => {
+  const s1 = await publish(server.url, { html: "<p>one</p>", title: "First", agent: "a1" });
+  const s2 = await publish(server.url, { html: "<p>two</p>", title: "Second", agent: "a2" });
+  await page.goto(server.url);
+  await expect(page.locator("#sessionList .sess")).toHaveCount(2);
+
+  await page.locator(`#sessionList .sess[data-id="${s1.sessionId}"]`).click();
+  await expect(page).toHaveURL(new RegExp(`/session/${s1.sessionId}(\\b|/)`));
+
+  await page.locator(`#sessionList .sess[data-id="${s2.sessionId}"]`).click();
+  await expect(page).toHaveURL(new RegExp(`/session/${s2.sessionId}(\\b|/)`));
+
+  // go back — should return to first session
+  await page.goBack();
+  await expect(page).toHaveURL(new RegExp(`/session/${s1.sessionId}(\\b|/)`));
+  await expect(page.locator(`#sessionList .sess[data-id="${s1.sessionId}"]`)).toHaveClass(/sel/);
+
+  // go forward — should return to second session
+  await page.goForward();
+  await expect(page).toHaveURL(new RegExp(`/session/${s2.sessionId}(\\b|/)`));
+  await expect(page.locator(`#sessionList .sess[data-id="${s2.sessionId}"]`)).toHaveClass(/sel/);
+});
+
+test("/ redirects to the last viewed session from localStorage", async ({ page, server }) => {
+  const s = await publish(server.url, { html: "<p>hi</p>", title: "Sticky", agent: "pi" });
+
+  // visit the session to populate localStorage
+  await page.goto(`${server.url}/session/${s.sessionId}`);
+  await expect(page.locator(`#sessionList .sess[data-id="${s.sessionId}"]`)).toHaveClass(/sel/);
+
+  // now visit root — should redirect to the last session
+  await page.goto(server.url);
+  await expect(page).toHaveURL(new RegExp(`/session/${s.sessionId}$`));
+  await expect(page.locator(`#sessionList .sess[data-id="${s.sessionId}"]`)).toHaveClass(/sel/);
+});
+
+test("scrolling through surfaces updates the URL", async ({ page, server }) => {
+  // publish enough surfaces to force scrolling
+  const s1 = await publish(server.url, {
+    html: '<div style="height:800px"><h2>Top</h2></div>',
+    title: "Surface A",
+    agent: "pi",
+  });
+  await publish(server.url, {
+    html: '<div style="height:800px"><h2>Middle</h2></div>',
+    title: "Surface B",
+    agent: "pi",
+    session: s1.sessionId,
+  });
+  const s3 = await publish(server.url, {
+    html: '<div style="height:800px"><h2>Bottom</h2></div>',
+    title: "Surface C",
+    agent: "pi",
+    session: s1.sessionId,
+  });
+
+  await page.goto(`${server.url}/session/${s1.sessionId}`);
+  await expect(page.locator(".card:not(#whatsNew)")).toHaveCount(3);
+
+  // scroll the last surface into view
+  await page.locator(`.card[data-id="${s3.id}"]`).scrollIntoViewIfNeeded();
+  await expect(page).toHaveURL(new RegExp(`/session/${s1.sessionId}/s/${s3.id}$`));
+
+  // scroll back to the first surface
+  await page.locator(`.card[data-id="${s1.id}"]`).scrollIntoViewIfNeeded();
+  await expect(page).toHaveURL(new RegExp(`/session/${s1.sessionId}/s/${s1.id}$`));
+});
+
+test("/s/:id standalone surface route still works unchanged", async ({ page, server }) => {
+  const s = await publish(server.url, { html: "<h2>Standalone</h2>", title: "Solo" });
+  await page.goto(`${server.url}/s/${s.id}`);
+  // standalone route renders the raw surface, not the viewer SPA
+  await expect(page.locator("h2")).toHaveText("Standalone");
+  // the sidebar should NOT be present
+  await expect(page.locator("#sessionList")).toHaveCount(0);
+});

server/app.ts

@@ -451,6 +451,8 @@ export function createApp({
     text.replaceAll(LOCAL_ORIGIN, new URL(c.req.url).origin);
 
   app.get("/", (c) => c.html(withOrigin(viewerHtml, c)));
+  app.get("/session/:id", (c) => c.html(withOrigin(viewerHtml, c)));
+  app.get("/session/:id/s/:surfaceId", (c) => c.html(withOrigin(viewerHtml, c)));
   app.get("/guide", (c) => c.text(withOrigin(guideMarkdown, c)));
   app.get("/setup", (c) => c.text(withOrigin(setupText, c)));
   app.get("/agent-howto", (c) => c.text(withOrigin(agentHowtoText, c)));

test/api.test.ts

@@ -991,3 +991,50 @@ test("asset routes require auth when a token is set", async () => {
   );
   assert.equal((await app.request("/a/anything")).status, 401);
 });
+
+// --- URL routing: /session/:id and /session/:id/s/:surfaceId ---
+
+test("/session/:id serves the viewer HTML", async () => {
+  const app = makeApp();
+  // create a session with a surface so the id is valid
+  const s = (await (
+    await app.request("/api/snippets", json({ html: "<p>x</p>", agent: "pi" }))
+  ).json()) as any;
+  const res = await app.request(`/session/${s.sessionId}`);
+  assert.equal(res.status, 200);
+  assert.ok(res.headers.get("content-type")?.includes("text/html"));
+  const body = await res.text();
+  assert.ok(body.includes("viewer"), "should serve the viewer document");
+});
+
+test("/session/:id/s/:surfaceId serves the viewer HTML", async () => {
+  const app = makeApp();
+  const s = (await (
+    await app.request("/api/snippets", json({ html: "<p>x</p>", agent: "pi" }))
+  ).json()) as any;
+  const res = await app.request(`/session/${s.sessionId}/s/${s.id}`);
+  assert.equal(res.status, 200);
+  assert.ok(res.headers.get("content-type")?.includes("text/html"));
+  const body = await res.text();
+  assert.ok(body.includes("viewer"), "should serve the viewer document");
+});
+
+test("/session/:id serves viewer even for nonexistent session ids", async () => {
+  const app = makeApp();
+  // the SPA handles resolution; the server just serves the HTML
+  const res = await app.request("/session/deadbeef");
+  assert.equal(res.status, 200);
+  assert.ok(res.headers.get("content-type")?.includes("text/html"));
+});
+
+test("/session routes require auth when a token is set", async () => {
+  const app = makeApp("secret");
+  assert.equal((await app.request("/session/abc123")).status, 401);
+  assert.equal((await app.request("/session/abc123/s/def456")).status, 401);
+  // with auth they serve the viewer
+  const authed = await app.request("/session/abc123", {
+    headers: { authorization: "Bearer secret" },
+  });
+  assert.equal(authed.status, 200);
+  assert.ok((await authed.text()).includes("viewer"));
+});

viewer/src/App.tsx

@@ -11,6 +11,7 @@ import {
   connect,
   dismissUpdate,
   groupSessions,
+  handlePopState,
   live,
   navOpen,
   nearBottom,
@@ -88,6 +89,9 @@ export default function App() {
     };
     window.addEventListener("keydown", onKeydown);
     onCleanup(() => window.removeEventListener("keydown", onKeydown));
+    // URL routing: handle browser back/forward
+    window.addEventListener("popstate", handlePopState);
+    onCleanup(() => window.removeEventListener("popstate", handlePopState));
   });
 
   // unseen activity badges the tab title

viewer/src/Card.tsx

@@ -33,6 +33,7 @@ import { activeTheme } from "./theme.ts";
 import { TracePart } from "./TracePart.tsx";
 import {
   comments,
+  focusSurface,
   scrollTarget,
   sendComment,
   sessions,
@@ -88,6 +89,18 @@ export function Card(props: { surface: Surface }) {
       setScrollTarget(null);
       card.scrollIntoView({ behavior: "smooth", block: "start" });
     }
+    // Update the URL as the user scrolls past surfaces (replaceState, no
+    // history noise). The first card that crosses the 50% threshold wins.
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) focusSurface(props.surface.id);
+        }
+      },
+      { threshold: 0.5 },
+    );
+    observer.observe(card);
+    onCleanup(() => observer.disconnect());
   });
 
   const versionRange = (latest: number) => {
@@ -97,7 +110,7 @@ export function Card(props: { surface: Surface }) {
   };
 
   return (
-    <div class="card" ref={(el) => (card = el)}>
+    <div class="card" data-id={props.surface.id} ref={(el) => (card = el)}>
       <div class="card-head">
         <span class="card-title">{props.surface.title}</span>
         <span class="vslot">

viewer/src/state.ts

@@ -12,6 +12,33 @@ import {
 } from "./api.ts";
 import { applyTheme } from "./theme.ts";
 
+// --- URL routing ---
+// /session/:id            → viewer with that session selected
+// /session/:id/s/:sid     → viewer with session selected, surface focused
+// /                       → redirect to last-viewed session (localStorage)
+const LAST_SESSION_KEY = "sideshow-last-session";
+
+export function parseRoute(pathname: string): { sessionId?: string } {
+  // /session/:id and /session/:id/s/:surfaceId both resolve to the session.
+  // The surface suffix is preserved in the URL for shareability but the
+  // viewer navigates to the top of the session (scroll-to-surface on load
+  // is unreliable with async iframe-heavy content).
+  const match = pathname.match(/^\/session\/([^/]+)/);
+  if (match) return { sessionId: match[1] };
+  return {};
+}
+
+function pushSessionUrl(id: string) {
+  const target = `/session/${id}`;
+  if (window.location.pathname !== target) {
+    history.pushState(null, "", target);
+  }
+}
+
+function replaceSurfaceUrl(sessionId: string, surfaceId: string) {
+  history.replaceState(null, "", `/session/${sessionId}/s/${surfaceId}`);
+}
+
 // A comment as the viewer renders it: server comments plus the optimistic
 // local echo (pending until the POST confirms).
 export type ViewComment = Comment & { pending?: boolean };
@@ -126,11 +153,28 @@ export async function refreshSessionsQuiet() {
 export async function refreshSessions() {
   await refreshSessionsQuiet();
   if (selected() && !sessions.some((s) => s.id === selected())) setSelectedInternal(null);
-  if (!selected() && sessions.length > 0) await select(sessions[0].id);
+  if (!selected() && sessions.length > 0) {
+    // Check the URL first, then localStorage, then fall back to first session.
+    const route = parseRoute(window.location.pathname);
+    const lastId = localStorage.getItem(LAST_SESSION_KEY);
+    const target =
+      (route.sessionId && sessions.some((s) => s.id === route.sessionId) && route.sessionId) ||
+      (lastId && sessions.some((s) => s.id === lastId) && lastId) ||
+      sessions[0].id;
+    await select(target, { replace: true });
+  }
 }
 
-export async function select(id: string) {
+export async function select(id: string, opts?: { fromPopState?: boolean; replace?: boolean }) {
   setSelectedInternal(id);
+  if (opts?.fromPopState) {
+    // Browser already moved the history; don't touch it.
+  } else if (opts?.replace) {
+    history.replaceState(null, "", `/session/${id}`);
+  } else {
+    pushSessionUrl(id);
+  }
+  localStorage.setItem(LAST_SESSION_KEY, id);
   setUnread((prev) => {
     const next = new Set(prev);
     next.delete(id);
@@ -155,6 +199,21 @@ export async function select(id: string) {
   mergeComments(res.comments);
 }
 
+// Update the URL to reflect the currently visible surface (replaceState so
+// scrolling doesn't pollute browser history).
+export function focusSurface(surfaceId: string) {
+  const sid = selected();
+  if (sid) replaceSurfaceUrl(sid, surfaceId);
+}
+
+// Handle browser back/forward by re-selecting the session from the URL.
+export function handlePopState() {
+  const route = parseRoute(window.location.pathname);
+  if (route.sessionId && route.sessionId !== selected()) {
+    void select(route.sessionId, { fromPopState: true });
+  }
+}
+
 // Switch to the session above (-1) or below (+1) the current one in the
 // sidebar list, wrapping at the ends so repeated presses cycle. Drives the
 // Cmd+Option+Up/Down shortcut. No-op with no sessions; jumps to the first