@pablopunk/webr 0.1.1

package/server/update/hint.ts

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+import { installedEntry } from '../entry';
+import { packageInfo } from '../package-info';
+import { fetchLatestVersion, isCacheFresh, readCachedLatest, writeCachedLatest } from './latest';
+import { isNewerVersion } from './versions';
+
+export const updateCheckDisabled = (env: NodeJS.ProcessEnv = process.env) => !!env.WEBR_NO_UPDATE_CHECK && env.WEBR_NO_UPDATE_CHECK !== '0';
+
+const availableMessage = (latest: string) => `A new version of Webr is available: ${latest}. Run "webr update" to install it.`;
+
+export async function refreshLatestVersionCache(env: NodeJS.ProcessEnv = process.env) {
+  const { name, version } = packageInfo();
+  const latest = await fetchLatestVersion(name).catch(() => readCachedLatest(env)?.latest ?? version);
+  writeCachedLatest(latest, env);
+}
+
+const refreshInBackground = () => {
+  spawn(process.execPath, [installedEntry(), 'refresh-update-cache'], { detached: true, stdio: 'ignore', windowsHide: true, env: process.env }).unref();
+};
+
+export function updateHint(env: NodeJS.ProcessEnv = process.env, refresh: () => void = refreshInBackground, now = Date.now()): string | undefined {
+  if (updateCheckDisabled(env)) return undefined;
+  const cached = readCachedLatest(env);
+  if (!isCacheFresh(cached, now)) refresh();
+  return cached && isNewerVersion(cached.latest, packageInfo().version) ? availableMessage(cached.latest) : undefined;
+}

package/server/update/index.ts

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+import { packageInfo } from '../package-info';
+import { fetchLatestVersion, writeCachedLatest } from './latest';
+import { detectPackageManager, globalInstallCommand, installedPackagePath, type InstallCommand } from './package-manager';
+import { isNewerVersion } from './versions';
+
+export type UpdateEnvironment = {
+  installPath: () => string;
+  latestVersion: (packageName: string) => Promise<string>;
+  install: (command: InstallCommand) => boolean;
+  restartPlugin: () => Promise<string[] | undefined>;
+};
+
+const installInTerminal = ({ command, args }: InstallCommand) => spawnSync(command, args, { stdio: 'inherit', shell: process.platform === 'win32' }).status === 0;
+
+export const realUpdateEnvironment = (restartPlugin: UpdateEnvironment['restartPlugin']): UpdateEnvironment => ({
+  installPath: installedPackagePath,
+  latestVersion: fetchLatestVersion,
+  install: installInTerminal,
+  restartPlugin,
+});
+
+export async function runUpdate(environment: UpdateEnvironment) {
+  const { name, version } = packageInfo();
+  const manager = detectPackageManager(environment.installPath());
+  if (!manager) throw new Error('This copy of Webr was not installed globally, so it cannot update itself. If it is a git checkout, pull and rebuild it.');
+  const latest = await environment.latestVersion(name);
+  writeCachedLatest(latest);
+  if (!isNewerVersion(latest, version)) return [`Webr ${version} is the latest version.`];
+  const command = globalInstallCommand(manager, name);
+  if (!environment.install(command)) throw new Error(`${manager} could not install ${name}@${latest}. Run it yourself to see why: ${command.command} ${command.args.join(' ')}`);
+  return [`Updated Webr ${version} → ${latest}.`, ...((await environment.restartPlugin()) ?? ['Restart Herdr to use the new version.'])];
+}

package/server/update/latest.ts

@@ -0,0 +1,33 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { webrHome } from '../home';
+
+const REGISTRY = 'https://registry.npmjs.org';
+const REQUEST_TIMEOUT_MS = 5000;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+type Fetch = typeof fetch;
+type CachedLatest = { checkedAt: number; latest: string };
+
+const cachePath = (env: NodeJS.ProcessEnv) => join(webrHome(env), 'update-check.json');
+const registryUrl = (packageName: string) => `${REGISTRY}/${packageName.replace('/', '%2F')}/latest`;
+
+export async function fetchLatestVersion(packageName: string, request: Fetch = fetch): Promise<string> {
+  const response = await request(registryUrl(packageName), { headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`The npm registry answered ${response.status}.`);
+  const { version } = await response.json() as { version?: unknown };
+  if (typeof version !== 'string') throw new Error('The npm registry sent no version.');
+  return version;
+}
+
+export function readCachedLatest(env: NodeJS.ProcessEnv = process.env): CachedLatest | undefined {
+  try { return JSON.parse(readFileSync(cachePath(env), 'utf8')) as CachedLatest; } catch { return undefined; }
+}
+
+export function writeCachedLatest(latest: string, env: NodeJS.ProcessEnv = process.env, now = Date.now()) {
+  const path = cachePath(env);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ checkedAt: now, latest } satisfies CachedLatest));
+}
+
+export const isCacheFresh = (cached: CachedLatest | undefined, now = Date.now()): cached is CachedLatest => !!cached && now - cached.checkedAt < CACHE_TTL_MS;

package/server/update/package-manager.ts

@@ -0,0 +1,24 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export type PackageManager = 'npm' | 'pnpm' | 'bun';
+export type InstallCommand = { command: string; args: string[] };
+
+const isInsideNodeModules = (path: string) => /[\\/]node_modules[\\/]/.test(path);
+const isBunInstall = (path: string) => /[\\/]\.bun[\\/]/.test(path);
+const isPnpmInstall = (path: string) => /[\\/]pnpm[\\/]/.test(path) || /[\\/]\.pnpm[\\/]/.test(path);
+
+export function detectPackageManager(installPath: string): PackageManager | undefined {
+  if (!isInsideNodeModules(installPath)) return undefined;
+  if (isBunInstall(installPath)) return 'bun';
+  return isPnpmInstall(installPath) ? 'pnpm' : 'npm';
+}
+
+export const installedPackagePath = () => realpathSync(fileURLToPath(new URL('../../package.json', import.meta.url)));
+
+export function globalInstallCommand(manager: PackageManager, packageName: string): InstallCommand {
+  const target = `${packageName}@latest`;
+  if (manager === 'pnpm') return { command: 'pnpm', args: ['add', '-g', target] };
+  if (manager === 'bun') return { command: 'bun', args: ['add', '-g', target] };
+  return { command: 'npm', args: ['install', '-g', target] };
+}

package/server/update/versions.ts

@@ -0,0 +1,15 @@
+type Version = { core: number[]; prerelease: boolean };
+
+const parse = (text: string): Version | undefined => {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(-[^+]+)?/.exec(text.trim());
+  return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: !!match[4] } : undefined;
+};
+
+export function isNewerVersion(candidate: string, current: string) {
+  const next = parse(candidate);
+  const installed = parse(current);
+  if (!next || !installed) return false;
+  const differing = next.core.findIndex((part, index) => part !== installed.core[index]);
+  if (differing >= 0) return next.core[differing] > installed.core[differing];
+  return installed.prerelease && !next.prerelease;
+}

package/src/lib/avatars.ts

@@ -0,0 +1,15 @@
+import { botAvatarTypes } from 'bot-avatars';
+import type { Thread } from './models';
+
+const GOLDEN_ANGLE_DEGREES = 137.508;
+
+const hueFarFromThePreviousThread = (index: number) => ((index * GOLDEN_ANGLE_DEGREES) % 360).toFixed(3);
+
+export function avatarForThread(thread: Thread) {
+  const index = thread.avatarIndex;
+  return {
+    type: botAvatarTypes[index % botAvatarTypes.length],
+    color: `hsl(${hueFarFromThePreviousThread(index)} 72% 58%)`,
+    seed: (index * 0.61803398875) % 1,
+  };
+}

package/src/lib/launch.ts

@@ -0,0 +1,16 @@
+import type { Thread } from './models';
+
+export const launchSteps = [
+  { id: 'validate', label: 'Checking the machine', active: 'Checking the machine…' },
+  { id: 'checkout', label: 'Creating the worktree', active: 'Creating the worktree…' },
+  { id: 'start', label: 'Starting the agent', active: 'Starting the agent…' },
+  { id: 'prompt', label: 'Sending your prompt', active: 'Sending your prompt…' },
+] as const;
+const RECENT_FAILURE_MS = 10 * 60_000;
+
+export const launchStepIndex = (step: string) => step === 'checkout_complete' ? 2 : Math.max(0, launchSteps.findIndex((item) => item.id === step));
+export const isLaunching = (thread: Thread) => ['pending', 'running'].includes(thread.operation?.state ?? '') && !thread.panes.some((pane) => pane.kind === 'agent');
+export const launchFailed = (thread: Thread) => ['failed', 'unknown'].includes(thread.operation?.state ?? '') && !thread.panes.some((pane) => pane.kind === 'agent');
+export const launchLabel = (thread: Thread) => launchSteps[launchStepIndex(thread.operation?.step ?? 'validate')].active;
+const failedRecently = (thread: Thread, now: number) => now - Date.parse(thread.updatedAt) < RECENT_FAILURE_MS;
+export const isListedThread = (thread: Thread, now = Date.now()) => thread.panes.some((pane) => pane.kind === 'agent') || isLaunching(thread) || launchFailed(thread) && failedRecently(thread, now);

package/src/lib/machines.ts

@@ -0,0 +1,41 @@
+export type MachineHarness = { id: string; name: string; models: string[]; customModels?: boolean; launchEnabled?: boolean; reason?: string };
+export type Machine = {
+  id: string;
+  name: string;
+  connected: boolean;
+  session: string;
+  projectPaths: Record<string, string>;
+  harnesses: MachineHarness[];
+  error?: string;
+  writable?: boolean;
+  configVersion?: number;
+};
+
+export const machines: Machine[] = [
+  {
+    id: 'local', name: 'Local', connected: true, session: 'default',
+    projectPaths: { herdr: '~/src/herdr', maze: '~/src/maze/monorepo', spotifin: '~/src/spotifin' },
+    harnesses: [
+      { id: 'claude', name: 'Claude Code', models: ['Default', 'sonnet', 'opus'] },
+      { id: 'codex', name: 'Codex', models: ['Default'] },
+      { id: 'opencode', name: 'OpenCode', models: ['Default'] },
+      { id: 'pi', name: 'Pi', models: ['Default'] },
+    ],
+  },
+  {
+    id: 'demo-build', name: 'Build machine (demo)', connected: true, session: 'agents',
+    projectPaths: { herdr: '/srv/herdr', spotifin: '/srv/spotifin' },
+    harnesses: [
+      { id: 'opencode', name: 'OpenCode', models: ['Default', 'demo/remote-model'] },
+      { id: 'pi', name: 'Pi', models: ['Default', 'demo/remote-model'] },
+    ],
+  },
+  {
+    id: 'demo-offline', name: 'Offline machine (demo)', connected: false, session: 'default',
+    projectPaths: {}, harnesses: [],
+  },
+];
+
+export function findMachine(id: string): Machine | undefined {
+  return machines.find((machine) => machine.id === id);
+}

package/src/lib/mock-store.ts

@@ -0,0 +1,82 @@
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { exampleThreads, harnessName, projects, type Thread } from './models';
+import { findMachine } from './machines';
+
+const dataFile = join(process.cwd(), '.data', 'threads.json');
+let pendingWrite: Promise<unknown> = Promise.resolve();
+const requireFixtureMode = () => { if (process.env.NODE_ENV !== 'test' && !(process.env.WEBR_FIXTURES === '1' && process.env.NODE_ENV !== 'production')) throw new Error('Mock data requires explicit fixture mode'); };
+
+async function savedThreads(): Promise<Thread[]> {
+  try {
+    return JSON.parse(await readFile(dataFile, 'utf8')) as Thread[];
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export async function listThreads(): Promise<Thread[]> {
+  requireFixtureMode();
+  await pendingWrite;
+  const examples = exampleThreads();
+  const saved = (await savedThreads()).map((thread, index) => ({
+    ...thread, avatarIndex: thread.avatarIndex ?? examples.length + index,
+    prompt: thread.prompt ?? thread.title, model: thread.model ?? 'Default',
+    machineId: thread.machineId ?? 'local',
+  }));
+  return [...examples, ...saved]
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export async function findThread(id: string): Promise<Thread | undefined> {
+  return (await listThreads()).find((thread) => thread.id === id);
+}
+
+export function createThread(input: {
+  projectId: string;
+  machineId: string;
+  prompt: string;
+  agent: string;
+  model: string;
+  worktree: boolean;
+}): Promise<Thread> {
+  requireFixtureMode();
+  const operation = pendingWrite.then(async () => {
+    const machine = findMachine(input.machineId);
+    if (!machine?.connected) throw new Error('Machine is not connected');
+    if (!projects.some((project) => project.id === input.projectId)) throw new Error('Unknown project');
+    if (!Object.hasOwn(machine.projectPaths, input.projectId)) throw new Error('Project is not available on this machine');
+    if (!machine.harnesses.some((harness) => harness.id === input.agent.trim())) throw new Error('Harness is not available on this machine');
+    const id = randomUUID().slice(0, 8);
+    const prompt = input.prompt.trim();
+    if (!prompt || prompt.length > 8000 || !input.agent.trim() || !input.model.trim()) throw new Error('Invalid thread details');
+    const name = prompt.split('\n').find((line) => line.trim())?.trim().replace(/\s+/g, ' ').slice(0, 90) ?? '';
+    if (!name) throw new Error('Enter a prompt');
+    const branch = input.worktree
+      ? `${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 32)}-${id}`
+      : 'main';
+    const threads = await savedThreads();
+    const thread: Thread = {
+      id, avatarIndex: exampleThreads().length + threads.length,
+      projectId: input.projectId, machineId: machine.id, title: name, prompt, agent: input.agent.trim(), model: input.model.trim(),
+      status: 'idle', updatedAt: new Date().toISOString(), branch,
+      worktree: input.worktree, session: machine.session, tabId: `mock:t${id}`,
+      panes: [{ id: `mock:p${id}`, title: harnessName(input.agent.trim()), kind: 'agent', lines: [
+        `Machine: ${machine.name} · ${machine.projectPaths[input.projectId]}`,
+        `${harnessName(input.agent.trim())} · ${input.model.trim()}`, 'Prompt:',
+        ...prompt.replace(/[\x00-\x09\x0b-\x1f\x7f]/g, '').split('\n'), '',
+        'This is a design prototype. The Herdr connection is not active yet.',
+        'Type in this terminal to try the layout.', '', '$',
+      ] }],
+    };
+    await mkdir(join(process.cwd(), '.data'), { recursive: true });
+    const tempFile = `${dataFile}.${id}.tmp`;
+    await writeFile(tempFile, JSON.stringify([...threads, thread], null, 2));
+    await rename(tempFile, dataFile);
+    return thread;
+  });
+  pendingWrite = operation.catch(() => {});
+  return operation;
+}

package/src/lib/models.ts

@@ -0,0 +1,139 @@
+export type AgentStatus = 'working' | 'blocked' | 'done' | 'idle' | 'unknown';
+export const harnessNames: Record<string, string> = {
+  claude: 'Claude Code', codex: 'Codex', opencode: 'OpenCode', pi: 'Pi',
+};
+
+export function harnessName(agent: string): string {
+  return Object.hasOwn(harnessNames, agent) ? harnessNames[agent] : agent;
+}
+
+export type Project = {
+  id: string;
+  name: string;
+  path: string;
+  color: string;
+  initial: string;
+  iconUrl?: string;
+  machineId?: string;
+  localId?: string;
+  logicalId?: string;
+};
+
+export type Pane = {
+  id: string;
+  title: string;
+  kind: 'agent' | 'shell';
+  lines?: string[];
+  terminalId?: string;
+};
+
+export type Thread = {
+  id: string;
+  avatarIndex: number;
+  projectId: string;
+  machineId: string;
+  title: string;
+  prompt: string;
+  agent: string;
+  model: string;
+  status: AgentStatus;
+  updatedAt: string;
+  branch: string;
+  worktree: boolean;
+  ownsWorktree?: boolean;
+  session: string;
+  tabId: string;
+  panes: Pane[];
+  bindingState?: 'attached' | 'detached' | 'pending';
+  operation?: { id: string; state: string; step: string };
+  bindingFingerprint?: string;
+  bindingConfigVersion?: number;
+  semanticSignature?: string;
+  archivedAt?: string;
+  terminalHidden?: boolean;
+};
+
+export const projects: Project[] = [
+  { id: 'herdr', name: 'herdr', path: '~/src/herdr', color: '#9b83df', initial: 'H' },
+  { id: 'maze', name: 'maze-monorepo', path: '~/src/maze/monorepo', color: '#e6a76d', initial: 'M' },
+  { id: 'spotifin', name: 'spotifin', path: '~/src/spotifin', color: '#70b6a1', initial: 'S' },
+];
+
+const at = (minutesAgo: number) => new Date(Date.now() - minutesAgo * 60_000).toISOString();
+
+export function exampleThreads(): Thread[] {
+  return [
+    {
+      id: 'terminal-web-bridge', avatarIndex: 0, projectId: 'herdr', machineId: 'local', title: 'Build the web terminal bridge',
+      prompt: 'Build the web terminal bridge', agent: 'claude', model: 'Default', status: 'working', updatedAt: at(2), branch: 'web-terminal-bridge',
+      worktree: true, session: 'default', tabId: 'w1:t2',
+      panes: [
+        { id: 'w1:p3', title: 'Claude Code', kind: 'agent', lines: [
+          '$ claude', '✳ Building the web terminal bridge', '',
+          'I found the terminal session control API. Each pane can stream',
+          'rendered ANSI frames and accept input, resize, and mouse events.', '',
+          '▸ Reading src/client/terminal_sessions.rs', '▸ Checking the frame protocol', '',
+          'Working…',
+        ] },
+        { id: 'w1:p4', title: 'Shell', kind: 'shell', lines: [
+          '$ git status --short', ' M src/client/terminal_sessions.rs',
+          '$ cargo test terminal_session', '',
+          'running 18 tests', 'test terminal::frame_encoding ... ok',
+          'test terminal::controller_lifecycle ... ok', '',
+          'test result: ok. 18 passed; 0 failed', '$',
+        ] },
+      ],
+    },
+    {
+      id: 'review-socket-api', avatarIndex: 1, projectId: 'herdr', machineId: 'local', title: 'Review socket API changes',
+      prompt: 'Review socket API changes', agent: 'codex', model: 'Default', status: 'blocked', updatedAt: at(14), branch: 'socket-api-review',
+      worktree: true, session: 'default', tabId: 'w1:t3',
+      panes: [{ id: 'w1:p5', title: 'Codex', kind: 'agent', lines: [
+        '$ codex', 'Review complete. One change needs your approval.', '',
+        'The new endpoint can replace the active controller.',
+        'Allow this change?', '', '> Waiting for input',
+      ] }],
+    },
+    {
+      id: 'sidebar-interactions', avatarIndex: 2, projectId: 'herdr', machineId: 'local', title: 'Polish sidebar interactions',
+      prompt: 'Polish sidebar interactions', agent: 'opencode', model: 'Default', status: 'done', updatedAt: at(82), branch: 'sidebar-polish',
+      worktree: true, session: 'default', tabId: 'w1:t4',
+      panes: [{ id: 'w1:p6', title: 'OpenCode', kind: 'agent', lines: [
+        '$ opencode', 'Done. The sidebar now keeps its scroll position when',
+        'thread status changes. Ready for review.', '', '✓ 12 tests passed', '$',
+      ] }],
+    },
+    {
+      id: 'fix-editor-loading', avatarIndex: 3, projectId: 'maze', machineId: 'local', title: 'Fix editor loading state',
+      prompt: 'Fix editor loading state', agent: 'claude', model: 'Default', status: 'working', updatedAt: at(7), branch: 'fix-editor-loading',
+      worktree: true, session: 'default', tabId: 'w2:t1',
+      panes: [{ id: 'w2:p1', title: 'Claude Code', kind: 'agent', lines: [
+        '$ claude', '✳ Investigating the loading state', '',
+        'The editor starts a second request while the first one is still',
+        'active. I am tracing the state transition now.', '', 'Working…',
+      ] }],
+    },
+    {
+      id: 'coverflow-motion', avatarIndex: 4, projectId: 'spotifin', machineId: 'local', title: 'Tune coverflow motion',
+      prompt: 'Tune coverflow motion', agent: 'pi', model: 'Default', status: 'idle', updatedAt: at(1440), branch: 'coverflow-motion',
+      worktree: false, session: 'default', tabId: 'w3:t1',
+      panes: [{ id: 'w3:p1', title: 'Pi', kind: 'agent', lines: [
+        '$ pi', 'The transition timing is now 280ms. All changes are ready',
+        'for you to inspect.', '', 'Ready for input',
+      ] }],
+    },
+  ];
+}
+
+export function relativeTime(value: string): string {
+  const minutes = Math.max(0, Math.floor((Date.now() - new Date(value).getTime()) / 60_000));
+  if (minutes < 1) return 'now';
+  if (minutes < 60) return `${minutes}m`;
+  if (minutes < 1440) return `${Math.floor(minutes / 60)}h`;
+  return `${Math.floor(minutes / 1440)}d`;
+}
+
+export function timeAgo(value: string): string {
+  const relative = relativeTime(value);
+  return relative === 'now' ? 'just now' : `${relative} ago`;
+}

package/src/lib/project-icons.ts

@@ -0,0 +1,120 @@
+import { homedir } from 'node:os';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { projects, type Project } from './models';
+
+const maxBytes = 1_000_000;
+const cacheForMs = 60_000;
+const contentTypes: Record<string, string> = {
+  '.png': 'image/png', '.ico': 'image/x-icon', '.svg': 'image/svg+xml',
+  '.webp': 'image/webp', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+};
+
+type ProjectIcon = { bytes: Uint8Array<ArrayBuffer>; contentType: string };
+const cache = new Map<string, { until: number; icon: Promise<ProjectIcon | undefined> }>();
+
+function unavailable(error: unknown): boolean {
+  return ['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM'].includes((error as NodeJS.ErrnoException).code ?? '');
+}
+
+function rank(name: string, generic: boolean): number {
+  const base = name.slice(0, -extname(name).length).toLowerCase();
+  const extension = extname(name).toLowerCase();
+  if (!contentTypes[extension]) return Infinity;
+  if (generic) return extension === '.png' ? 0 : Infinity;
+  if (base === 'favicon') return 0;
+  if (base.startsWith('favicon-')) return 1;
+  if (base.startsWith('apple-touch-icon')) return 2;
+  if (base === 'icon' || base === 'app-icon') return 3;
+  if (base.startsWith('icon-') || base === 'logo' || base === 'brand' || base === 'mark') return 4;
+  if (base.startsWith('logo-') || base.startsWith('brand-')) return 5;
+  return Infinity;
+}
+
+function withinRoot(root: string, path: string): boolean {
+  const part = relative(root, path);
+  return part !== '..' && !part.startsWith(`..${sep}`) && !isAbsolute(part);
+}
+
+function squarePng(bytes: Uint8Array): boolean {
+  if (bytes.length < 24 || bytes[0] !== 137 || bytes[1] !== 80 || bytes[2] !== 78 || bytes[3] !== 71) return false;
+  const size = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const width = size.getUint32(16);
+  const height = size.getUint32(20);
+  return width >= 16 && width <= 512 && height >= 16 && height <= 512 && width / height >= 0.8 && width / height <= 1.25;
+}
+
+async function iconInDirectory(root: string, directory: string, generic = false): Promise<ProjectIcon | undefined> {
+  try {
+    const actualDirectory = await realpath(directory);
+    if (!withinRoot(root, actualDirectory)) return;
+    const entries = (await readdir(actualDirectory, { withFileTypes: true }))
+      .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && Number.isFinite(rank(entry.name, generic)))
+      .sort((a, b) => rank(a.name, generic) - rank(b.name, generic) || a.name.localeCompare(b.name))
+      .slice(0, generic ? 12 : undefined);
+    for (const entry of entries) {
+      try {
+        const path = await realpath(join(actualDirectory, entry.name));
+        if (!withinRoot(root, path)) continue;
+        const info = await stat(path);
+        if (!info.isFile() || info.size === 0 || info.size > maxBytes) continue;
+        const bytes = new Uint8Array(await readFile(path));
+        if (generic && !squarePng(bytes)) continue;
+        return { bytes, contentType: contentTypes[extname(entry.name).toLowerCase()] };
+      } catch (error) {
+        if (!unavailable(error)) throw error;
+      }
+    }
+  } catch (error) {
+    if (!unavailable(error)) throw error;
+  }
+}
+
+async function discover(project: Project): Promise<ProjectIcon | undefined> {
+  const directory = project.path.startsWith('~/') ? join(homedir(), project.path.slice(2)) : resolve(project.path);
+  let root: string;
+  try { root = await realpath(directory); } catch (error) {
+    if (unavailable(error)) return;
+    throw error;
+  }
+
+  let apps = [] as string[];
+  try {
+    const appsDirectory = await realpath(join(root, 'apps'));
+    if (withinRoot(root, appsDirectory)) {
+      apps = (await readdir(appsDirectory, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory()).map((entry) => entry.name)
+        .sort((a, b) => Number(!a.includes(project.id)) - Number(!b.includes(project.id)) || a.localeCompare(b))
+        .slice(0, 8);
+    }
+  } catch (error) {
+    if (!unavailable(error)) throw error;
+  }
+  const directories = [
+    ...['', 'public', 'static', 'assets', 'web', 'web/public', 'app', 'app/public', 'src/assets', 'src/app', 'frontend/public'].map((path) => join(root, path)),
+    ...apps.flatMap((app) => ['public', 'src/assets', 'assets'].map((path) => join(root, 'apps', app, path))),
+  ];
+  for (const generic of [false, true]) {
+    for (const directory of directories) {
+      const icon = await iconInDirectory(root, directory, generic);
+      if (icon) return icon;
+    }
+  }
+}
+
+export function findProjectIcon(project: Project): Promise<ProjectIcon | undefined> {
+  const cached = cache.get(project.id);
+  if (cached && cached.until > Date.now()) return cached.icon;
+  const icon = discover(project).catch((error) => {
+    cache.delete(project.id);
+    throw error;
+  });
+  cache.set(project.id, { until: Date.now() + cacheForMs, icon });
+  return icon;
+}
+
+export async function projectsWithIcons(): Promise<Project[]> {
+  return Promise.all(projects.map(async (project) => ({
+    ...project, iconUrl: await findProjectIcon(project) ? `/api/projects/${encodeURIComponent(project.id)}/icon` : undefined,
+  })));
+}

package/src/lib/terminal-split.ts

@@ -0,0 +1,23 @@
+import type { Pane, Thread } from './models';
+import type { Layout, Rect } from '../shared/runtime';
+
+export type PeekSide = 'right' | 'bottom';
+export const threadAgent = (thread: Thread): Pane | undefined => thread.panes.find((pane) => pane.kind === 'agent') ?? thread.panes[0];
+export const threadShell = (thread: Thread): Pane | undefined => { const main = threadAgent(thread); return thread.panes.find((pane) => pane.kind === 'shell' && pane.id !== main?.id); };
+export const peekSide = (shell: Rect, area: Rect): PeekSide => shell.x > area.x && shell.y === area.y ? 'right' : 'bottom';
+export const terminalDirection = (side: PeekSide) => side === 'right' ? 'right' as const : 'down' as const;
+
+export function hiddenTerminalLayout(thread: Thread, layout: Layout) {
+  const shell = threadShell(thread); const agent = threadAgent(thread);
+  const shellRect = shell && layout.panes.find((rect) => rect.paneId === shell.id)?.rect;
+  const otherPanes = thread.panes.filter((pane) => pane.id !== shell?.id && pane.id !== agent?.id);
+  if (!thread.terminalHidden || !shell || !agent || !shellRect || otherPanes.length) return undefined;
+  return { shell, agent, side: peekSide(shellRect, layout.area) };
+}
+
+export function currentTerminalDirection(thread: Thread, layouts: Layout[], narrow: boolean) {
+  const shell = threadShell(thread);
+  const layout = layouts.find((layout) => layout.panes.some((rect) => rect.paneId === shell?.id));
+  const rect = layout?.panes.find((rect) => rect.paneId === shell?.id)?.rect;
+  return rect && layout ? terminalDirection(peekSide(rect, layout.area)) : narrow ? 'down' : 'right';
+}

package/src/lib/uuid.ts

@@ -0,0 +1,10 @@
+const hex = (bytes: Uint8Array) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+export function uuid() {
+  if (typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = bytes[6] & 0x0f | 0x40;
+  bytes[8] = bytes[8] & 0x3f | 0x80;
+  const text = hex(bytes);
+  return `${text.slice(0, 8)}-${text.slice(8, 12)}-${text.slice(12, 16)}-${text.slice(16, 20)}-${text.slice(20)}`;
+}

package/src/server/auth/access.ts

@@ -0,0 +1,22 @@
+import type { IncomingHttpHeaders } from 'node:http';
+
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+const FORWARDING_HEADERS = ['x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'forwarded', 'via'];
+
+const hostnameOf = (host: string | undefined) => { try { return new URL(`http://${host}`).hostname; } catch { return undefined; } };
+const isLoopbackAddress = (address: string | undefined) => !!address && (address === '::1' || address.startsWith('127.') || address.startsWith('::ffff:127.'));
+const isForwarded = (headers: IncomingHttpHeaders) => FORWARDING_HEADERS.some((name) => name in headers) || Object.keys(headers).some((name) => name.startsWith('tailscale-'));
+const isIpLiteral = (hostname: string) => hostname.startsWith('[') || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname);
+const isNameControlledByNetwork = (hostname: string) => hostname.endsWith('.local') || hostname.endsWith('.ts.net');
+
+export const sourceAddress = (address: string) => address.replace(/^::ffff:/, '');
+export const isLoopbackHost = (host: string | undefined) => LOOPBACK_HOSTNAMES.has(hostnameOf(host) ?? '');
+
+export function isLocalRequest(request: { headers: IncomingHttpHeaders; socket: { remoteAddress?: string } }) {
+  return isLoopbackAddress(request.socket.remoteAddress) && isLoopbackHost(request.headers.host) && !isForwarded(request.headers);
+}
+
+export function isTrustedHost(host: string | undefined, configuredHost: string) {
+  const hostname = hostnameOf(host);
+  return !!host && !!hostname && (host === configuredHost || LOOPBACK_HOSTNAMES.has(hostname) || isIpLiteral(hostname) || isNameControlledByNetwork(hostname));
+}

package/src/server/auth/audit.ts

@@ -0,0 +1,15 @@
+import type { MetadataDatabase } from '../storage/database';
+
+export type AuditKind = 'pair_requested' | 'pair_approved' | 'pair_denied' | 'invite_created' | 'invite_redeemed' | 'device_revoked' | 'session_expired';
+export type AuditEvent = { id: number; at: number; kind: AuditKind; source: string | null; deviceName: string | null };
+type Subject = { source?: string; deviceName?: string };
+
+const RECENT_LIMIT = 50;
+
+export class AuditLog {
+  constructor(private readonly database: MetadataDatabase, private readonly now = Date.now) {}
+  record(kind: AuditKind, { source, deviceName }: Subject = {}) {
+    this.database.addAuditEvent({ at: this.now(), kind, source: source ?? null, deviceName: deviceName ?? null });
+  }
+  recent(limit = RECENT_LIMIT) { return this.database.auditEvents(limit); }
+}