app preview: a panel that points an iframe at a running app

A dashboard can now hold chat, the code editor, the file browser and the app itself — the last piece of working on a project without leaving Officer. ── Why this is ~200 lines and not 560 ── The version deleted on 2026-07-31 spawned `bun dev` in a project directory, found a free port and proxied it under `/api/dev-server-proxy/<id>/`. That prefix is what cost the money: HTML, JS and CSS rewritten; a script injected into the page to monkey-patch fetch/XHR/WebSocket so runtime URLs got the prefix too; a Referer fallback for chunks that resolved at the wrong depth; a websocket bridge for HMR. All of it faking an origin. On a machine with a proxy in front — nginx on edge.pertento.ai, wildcard subdomains — the app is ALREADY served at the root of its own origin, and the browser is already on the tailnet. So there is nothing to fake and no server side at all: no route, no socket, and therefore no permission-registry entry. The old code is not obsolete and is not being thrown away. An install with no proxy in front still has an app on localhost that the browser cannot reach, and that is exactly what it solves. It is at `188b45c1^`; the note is in TODO.md. ── What it does ── Holds a URL per panel, renders it, reloads it, opens it in a real tab. The URL lives in dashboard state so it survives a reload, and is shared LIVE between header and body — the header writes and the body reads, so claim-once would mean typing a URL changed the header and nothing else. The reload counter is deliberately not persisted: it is a signal. Reload remounts the iframe by key rather than calling `contentWindow.location .reload()`, which throws cross-origin. Replacing the element re-requests the URL, which is the same thing from the outside and the only move the parent is allowed. `allow-same-origin` is set and has to be: without it the framed app gets an opaque origin and no localStorage, and it authenticates with a JWT it keeps there. `normalizeUrl` accepts a bare host as https and refuses javascript:, data: and blob: — an iframe src with `javascript:` executes in the PARENT's context. The owner typing in their own panel is not an attacker; it costs one line and removes the category. 5 tests. ── Two iframe facts worth knowing before testing ── Storage is PARTITIONED by top-level site, so the login inside the panel is separate from the login in a tab: expect to sign in once, in the panel. A page can refuse to be framed (X-Frame-Options, CSP frame-ancestors) and renders blank with only a console error. If that happens it is nginx's config, not this code — which is why "open in a new tab" is in the header rather than left to copying the URL out. tsgo clean, frontend builds, 851 pass / 7 fail — +5 new, same 7. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-16 00:21:42 +00:00
parent 20aa0cc880
commit 5c40d4423d
7 changed files with 288 additions and 1 deletions
@@ -20,7 +20,7 @@ export const dashboardsRouter = createRouter();
 // `editor` joined 2026-08-15: which files a code-editor panel has open, and which is in front. Note an
 // unmatched key is a 400 rather than a silent 200 — so a new panel prefix MUST be added here or its state
 // vanishes loudly instead of quietly, which is the whole reason that branch exists.
-const PANEL_STATE_PREFIXES = ['tmux', 'nvim', 'claude-code', 'editor', 'files', 'chat'];
+const PANEL_STATE_PREFIXES = ['tmux', 'nvim', 'claude-code', 'editor', 'files', 'chat', 'preview'];

 // A `LayoutNode` is an object. Everything from the PATCH body down to jsonb is `unknown`, so without this
 // the only thing standing between a wrong-shaped body and the layout columns is the CHECK constraint —
@@ -5,6 +5,7 @@ import { appRegistryMetas as fileBrowserMetas } from '../apps/FileBrowser';
 import { appRegistryMetas as terminalMetas } from '../apps/Terminal';
 import { appRegistryMetas as codeEditorMetas } from '../apps/CodeEditor';
 import { appRegistryMetas as chatMetas } from '../apps/Chat';
+import { appRegistryMetas as previewMetas } from '../apps/Preview';
 import { appRegistryMetas as dashboardMetas } from '../apps/Dashboards';
 import { appRegistryMetas as chatHistoryMetas } from '../apps/ChatHistory';
 import { appRegistryMetas as widgetMetas } from '../apps/Widgets';
@@ -28,6 +29,7 @@ export const apps = [
  ...terminalMetas,
  ...codeEditorMetas,
  ...chatMetas,
+  ...previewMetas,
  ...dashboardMetas,
  ...chatHistoryMetas,
  ...widgetMetas,
@@ -0,0 +1,58 @@
+import { useState } from 'react';
+import { Globe } from 'lucide-react';
+import { useWorkspace } from '../../components/Workspace';
+import { normalizeUrl, usePreview } from './use-preview';
+
+/**
+ * A live app, in a panel.
+ *
+ * The iframe is remounted by `key` on reload rather than reaching for `contentWindow.location.reload()`:
+ * the frame is a different origin, so touching its location object throws a cross-origin error. Replacing
+ * the element re-requests the URL, which is the same thing from the user's side and the only thing the
+ * parent is allowed to do.
+ *
+ * `allow-same-origin` is present, and has to be: without it the framed app gets an opaque origin, which
+ * means no `localStorage` — and it authenticates with a JWT it keeps there, so it could never stay logged
+ * in. It is combined with `allow-scripts`, which the two together do weaken — but the alternative is a
+ * panel that cannot run the app it exists to show, and the URL is one the owner typed.
+ */
+export const PreviewApp = ({ panelId }: { panelId: string }) => {
+  const { workspace } = useWorkspace();
+  const { url, setUrl, reloadToken } = usePreview(panelId, workspace);
+  const [draft, setDraft] = useState('');
+
+  if (!url) {
+    return (
+      <form
+        className="flex h-full w-full flex-col items-center justify-center gap-3 px-6"
+        onSubmit={(ev) => {
+          ev.preventDefault();
+          const next = normalizeUrl(draft);
+          if (next) setUrl(next);
+        }}
+      >
+        <Globe className="h-6 w-6 text-duck-dark/30" />
+        <span className="text-sm text-duck-dark/50">Point this panel at a running app</span>
+        <input
+          autoFocus
+          value={draft}
+          onChange={(ev) => setDraft(ev.target.value)}
+          placeholder="jesper.edge.pertento.ai"
+          className="w-full max-w-sm rounded-md border border-duck-dark/20 bg-transparent px-3 py-1.5 text-sm"
+        />
+        <button
+          type="submit"
+          disabled={!normalizeUrl(draft)}
+          className="rounded-md bg-duck-teal px-3 py-1.5 text-sm text-duck-yellow transition-opacity hover:opacity-90 disabled:opacity-40"
+        >
+          Open
+        </button>
+        <p className="text-xs text-duck-dark/40">
+          Anything the browser can reach. It stays on this panel and survives a reload.
+        </p>
+      </form>
+    );
+  }
+
+  return <iframe key={reloadToken} src={url} title="Preview" className="h-full w-full border-none bg-white" />;
+};
@@ -0,0 +1,91 @@
+import { useEffect, useState } from 'react';
+import { Globe, RefreshCw, ExternalLink, Pencil, Check, X } from 'lucide-react';
+import { useWorkspace } from '../../components/Workspace';
+import { normalizeUrl, usePreview } from './use-preview';
+
+/**
+ * The preview panel's header: where it points, reload, open in a real tab, and change it.
+ *
+ * "Open in a new tab" is not decoration. A framed app gets PARTITIONED storage — the browser keys it by
+ * top-level site — so the login inside this panel is separate from the login in a tab, and a page that
+ * refuses to be framed at all (`X-Frame-Options`, CSP `frame-ancestors`) renders blank here with only a
+ * console error. When either happens, the tab is the answer, and it should be one click away rather than
+ * something you rebuild by copying the URL out.
+ */
+export const PreviewHeader = ({ panelId }: { panelId?: string }) => {
+  const { workspace } = useWorkspace();
+  const { url, setUrl, reload } = usePreview(panelId, workspace);
+
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(url);
+
+  // Follow the stored value while not editing, so a URL set from elsewhere shows up here.
+  useEffect(() => {
+    if (!editing) setDraft(url);
+  }, [url, editing]);
+
+  const commit = () => {
+    const next = normalizeUrl(draft);
+    if (next) setUrl(next);
+    setEditing(false);
+  };
+
+  if (editing) {
+    return (
+      <>
+        <Globe className="h-3.5 w-3.5 shrink-0 text-duck-teal" />
+        <input
+          autoFocus
+          value={draft}
+          onChange={(ev) => setDraft(ev.target.value)}
+          onKeyDown={(ev) => {
+            if (ev.key === 'Enter') commit();
+            if (ev.key === 'Escape') setEditing(false);
+          }}
+          className="min-w-0 flex-1 rounded border border-duck-dark/20 bg-transparent px-1.5 py-0.5 text-xs"
+        />
+        <button onClick={commit} title="Save" className="p-0.5 cursor-pointer shrink-0">
+          <Check className="h-3 w-3" />
+        </button>
+        <button onClick={() => setEditing(false)} title="Cancel" className="p-0.5 cursor-pointer shrink-0">
+          <X className="h-3 w-3" />
+        </button>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <Globe className="h-3.5 w-3.5 shrink-0 text-duck-teal" />
+      <span className="text-xs font-medium shrink-0">Preview</span>
+      {url ? (
+        <>
+          <button onClick={reload} title="Reload" className="p-0.5 rounded hover:bg-black/10 cursor-pointer shrink-0">
+            <RefreshCw className="h-3 w-3" />
+          </button>
+          <span className="min-w-0 flex-1 truncate text-[10px] font-mono opacity-60">
+            {url.replace(/^https?:\/\//, '')}
+          </span>
+          <button
+            onClick={() => setEditing(true)}
+            title="Change URL"
+            className="p-0.5 rounded hover:bg-black/10 cursor-pointer shrink-0"
+          >
+            <Pencil className="h-3 w-3" />
+          </button>
+          <a
+            href={url}
+            target="_blank"
+            rel="noreferrer"
+            title="Open in a new tab"
+            className="p-0.5 rounded hover:bg-black/10 cursor-pointer shrink-0"
+          >
+            <ExternalLink className="h-3 w-3" />
+          </a>
+        </>
+      ) : (
+        <span className="min-w-0 flex-1 truncate text-[10px] font-mono opacity-40">no URL yet</span>
+      )}
+    </>
+  );
+};
@@ -0,0 +1,18 @@
+import type { AppRegistryMeta } from '../../AppRegistry';
+import { Globe } from 'lucide-react';
+import { PreviewApp } from './PreviewApp';
+import { PreviewHeader } from './PreviewHeader';
+
+export { PreviewApp } from './PreviewApp';
+export { PreviewHeader } from './PreviewHeader';
+export { usePreview, normalizeUrl, type PreviewPanelState } from './use-preview';
+
+export const appRegistryMetas: AppRegistryMeta[] = [
+  {
+    key: 'officerdev/preview',
+    name: 'Preview',
+    icon: Globe,
+    component: PreviewApp,
+    header: PreviewHeader,
+  },
+];
@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'bun:test';
+import { normalizeUrl } from './use-preview';
+
+// The panel puts this string straight into an iframe `src`, so what it accepts matters more than it looks.
+
+describe('normalizeUrl', () => {
+  test('a bare host is assumed https, because that is what people type', () => {
+    expect(normalizeUrl('jesper.edge.pertento.ai')).toBe('https://jesper.edge.pertento.ai/');
+  });
+
+  test('an explicit scheme is kept, including http for a local dev server', () => {
+    expect(normalizeUrl('https://jesper.edge.pertento.ai')).toBe('https://jesper.edge.pertento.ai/');
+    expect(normalizeUrl('http://localhost:5173')).toBe('http://localhost:5173/');
+  });
+
+  test('a path survives', () => {
+    expect(normalizeUrl('backend-jesper.edge.pertento.ai/api')).toBe('https://backend-jesper.edge.pertento.ai/api');
+  });
+
+  test('refuses the three schemes that turn a text box into script execution', () => {
+    // `javascript:` in an iframe src executes in the PARENT's context. data: and blob: are the other two
+    // shapes with the same ending. The owner typing into their own panel is not an attacker, but this
+    // costs one line and removes the category.
+    expect(normalizeUrl('javascript:alert(1)')).toBeNull();
+    expect(normalizeUrl('data:text/html,<script>alert(1)</script>')).toBeNull();
+    expect(normalizeUrl('blob:https://x/y')).toBeNull();
+  });
+
+  test('empty and nonsense are null, so the button can stay disabled', () => {
+    expect(normalizeUrl('')).toBeNull();
+    expect(normalizeUrl('   ')).toBeNull();
+    expect(normalizeUrl('not a url at all')).toBeNull();
+  });
+});
@@ -0,0 +1,84 @@
+import { useCallback } from 'react';
+import { useGlobal } from 'hooks/useGlobal';
+import { useDashboardState } from 'state/useDashboardState';
+import { panelStateKey, type WorkspaceIdentity } from '../../components/Workspace';
+
+/**
+ * What a preview panel is pointing at, and a way to reload it.
+ *
+ * ── Why there is no server behind this ──
+ *
+ * A previous version of this feature spawned `bun dev` in a project directory, found a free port, and
+ * proxied it under `/api/dev-server-proxy/<id>/` — which then required rewriting HTML, JS and CSS, a
+ * script injected into the page to monkey-patch `fetch`/`XHR`/`WebSocket`, a Referer fallback for chunks
+ * that resolved at the wrong depth, and a websocket bridge for HMR. Roughly 360 lines, all of it the cost
+ * of serving an app under a path prefix the app does not know about. It is at `188b45c1^` if that case
+ * comes back — an install with no proxy in front still needs it.
+ *
+ * This version does none of that, because it does not have to: the app is already served at the root of
+ * its own origin (`https://jesper.edge.pertento.ai`), reachable by the browser over the tailnet. So the
+ * panel is an iframe and a URL, and the page inside behaves exactly as it does in a tab. Nothing of ours
+ * sits in the middle to interfere with its calls to its own backend.
+ *
+ * ── Live, not claim-once ──
+ *
+ * The header writes the URL and the body reads it — two components with no props between them — so this
+ * is the same shape as the chat session picker rather than `usePanelMemory`. Claim-once would mean typing
+ * a URL changed the header and nothing else.
+ *
+ * The URL persists (dashboard state, keyed per panel). The reload counter does NOT: it is a signal, and a
+ * reload that survived a refresh would be meaningless.
+ */
+export type PreviewPanelState = { url: string };
+
+const EMPTY: Record<string, PreviewPanelState> = {};
+
+export function usePreview(panelId: string | undefined, workspace: WorkspaceIdentity | null) {
+  const { value: bag, setValue: setBag } = useDashboardState<Record<string, PreviewPanelState>>(
+    panelStateKey('preview', workspace),
+    EMPTY,
+  );
+
+  const url = panelId ? (bag[panelId]?.url ?? '') : '';
+
+  const setUrl = useCallback(
+    (next: string) => {
+      if (!panelId) return;
+      setBag((prev) => {
+        if (prev[panelId]?.url === next) return prev;
+        return { ...prev, [panelId]: { url: next } };
+      });
+    },
+    [panelId, setBag],
+  );
+
+  // Keyed per panel so two previews reload independently. Same shape the terminal uses for its connection
+  // state, and deliberately not persisted.
+  const [reloadToken, setReloadToken] = useGlobal<number>(`preview-reload-${panelId ?? 'none'}`, 0);
+  const reload = useCallback(() => setReloadToken((n) => n + 1), [setReloadToken]);
+
+  return { url, setUrl, reloadToken, reload };
+}
+
+/**
+ * A URL we are willing to put in an iframe.
+ *
+ * `http` and `https` only. Without this the field would accept `javascript:` — which an iframe `src` will
+ * execute in the parent's context — and `data:`/`blob:`, which are the other two shapes that turn a text
+ * box into script execution. This is a text field on the owner's own screen rather than untrusted input,
+ * so the check is a guard against a mistake rather than an attacker, but it costs one line.
+ *
+ * A bare host (`jesper.edge.pertento.ai`) is accepted and assumed https, because that is what people type.
+ */
+export function normalizeUrl(raw: string): string | null {
+  const text = raw.trim();
+  if (!text) return null;
+  const withScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(text) ? text : `https://${text}`;
+  try {
+    const parsed = new URL(withScheme);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}