@chatcode/cco-better-sidebar 0.18.0-alpha.0

package/src/client/api.ts

@@ -0,0 +1,433 @@
+/**
+ * Typed fetch wrapper over the /sidebar JSON API. Every call posts to
+ * `/sidebar/api/<method>` with the sessionId and — when known — the session's
+ * cwd from the client's own list summary. The host prefers its attached
+ * session header and uses the summary cwd only while the session is still
+ * hydrating at page load (a detached session would otherwise fail the
+ * request). Failures surface as {@link SidebarApiError} with the wire code.
+ */
+import { encodeHtmlUrl } from '../html-route.ts'
+import type { BrowserProbeResult } from './browser.ts'
+
+/** One wire failure. */
+export class SidebarApiError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * Whether a wire failure is the workspace fence refusing a path outside the
+ * session workspace (the host message reads `path "..." is outside
+ * workspace`). The request-trust fence answers code `forbidden` with the
+ * bare message 'forbidden', so the message fragment — not the code alone —
+ * identifies this case.
+ */
+export function isOutsideWorkspaceError(error: unknown): boolean {
+  return error instanceof SidebarApiError && isOutsideWorkspaceMessage(error.message)
+}
+
+/** Message-level variant for surfaces that stored the raw text (file-tree level errors). */
+export function isOutsideWorkspaceMessage(message: string): boolean {
+  return message.includes('outside workspace')
+}
+
+/** Explorer row (host fs-tree shape). */
+export interface FsEntry {
+  name: string
+  path: string
+  isDir: boolean
+  hidden: boolean
+  /** Whether the row is a symlink; `isDir` then describes the link's target. */
+  isSymlink: boolean
+  /** For symlinks: the target is missing or unreadable (stat failed). */
+  broken: boolean
+}
+
+/** Git status entry (host git shape). */
+export interface GitStatusEntry {
+  path: string
+  xy: string
+}
+
+/** Git status snapshot. */
+export interface GitStatusResult {
+  isRepo: boolean
+  branch?: string
+  entries: GitStatusEntry[]
+  /** True when the host capped `entries` (huge untracked set); the panel
+   *  shows a truncation notice instead of freezing (#369). */
+  truncated?: boolean
+  root?: string
+  repositories?: string[]
+}
+
+/** One linked Git checkout. */
+export interface GitWorktree {
+  path: string
+  branch: string
+  current: boolean
+  changes: number
+}
+
+/** One git log row. */
+export interface GitLogEntry {
+  /** Short hash (7+ chars, display). */
+  hash: string
+  /** Full 40-char hash (advanced operations). */
+  hashFull: string
+  subject: string
+  author: string
+  /** ISO 8601 author date (`%ai`). */
+  date: string
+  /** Ref decorations (--decorate=short), e.g. `HEAD -> main, origin/main`; '' when none. */
+  refs: string
+}
+
+/** Text read result. */
+export interface FsTextResult { kind: 'text'; content: string; truncated: boolean }
+/** Binary read result (no content; images load through the media route).
+ *  `head` carries the first bytes (base64) for viewer detect sniffing. */
+export interface FsBinaryResult { kind: 'binary'; size: number; truncated: boolean; head: string }
+
+/** Terminal dependency status (mirror of the host's depsStatus; issue #140). */
+export type TerminalDepsStatus =
+  | { ok: true }
+  | {
+    ok: false
+    /** The require-time error message (module missing, native binding broken…). */
+    cause: string
+    /** The pasteable repair command (terminal/cmd). */
+    command: string
+    /** The detected profile name (null when undetected → the command defaults to web). */
+    profile: string | null
+    /** Optional supplementary hint (fallback command only). */
+    note?: string
+  }
+
+/** Display-only CodingPlan model returned by the sidebar host. Provider
+ * endpoints, protocol details, and API keys intentionally do not exist in
+ * this browser-facing type. */
+export interface CodingPlanModel {
+  logicalModelId: string
+  displayName: string
+  description?: string
+  accessType?: string
+  maxToken?: number
+  contextWindow?: number
+}
+
+/** Cached CodingPlan catalogue state. */
+export interface CodingPlanCatalogue {
+  status: 'loading' | 'ready' | 'unavailable'
+  models: CodingPlanModel[]
+  fetchedAt?: string
+}
+
+/** Browser-safe ChatCode account state returned by the optional host plugin. */
+export interface ChatCodeAuthState {
+  required?: boolean
+  validation?: 'valid' | 'invalid' | 'unavailable' | 'none'
+  login?: { sessionId: string; state: 'pending' | 'succeeded' | 'failed' | 'timed-out' | 'cancelled'; expiresAtMs: number }
+  available: boolean
+  configured?: boolean
+  expired?: boolean
+  userName?: string
+  emailAddress?: string
+}
+
+/** One day of personal token usage (the platform userTokenTrend row). */
+export interface ChatCodeTokenDay {
+  statDate: string
+  tokensIn: number
+  tokensOut: number
+  totalTokens: number
+}
+
+/** One personal commit record (the platform gitCommitRecord row; numeric
+ *  fields are coerced defensively at render time). */
+export interface ChatCodeCommitRecord {
+  projectName: string
+  name: string
+  email: string
+  authorEmail: string
+  additions: number
+  deletions: number
+  total: number
+  aiTotal: number
+  orgname: string
+  deptname: string
+  title: string
+  shortId: string
+  authoredDate: string
+}
+
+/** Exact release note for the running package version. */
+export interface ReleaseNoteResult {
+  registered: boolean
+  release: null | {
+    id: number
+    packageName: string
+    versionNum: string
+    title?: string
+    contentMd: string
+    updatedAt?: string
+  }
+}
+
+/** The package the "update" section's action upgrades. */
+export const CHATCODE_CLI_PKG = '@chatcode/chatcode-cli'
+
+/** One package's version-check result (mirror of the host chatcode-update). */
+export interface ChatCodeUpdateCheck {
+  packageName: string
+  current: string | null
+  latest: string | null
+  needsUpdate: boolean
+}
+
+/** One package's perform-update result (mirror of the host chatcode-update). */
+export interface ChatCodeUpdateResult {
+  packageName: string
+  from: string | null
+  to: string | null
+  ok: boolean
+  message: string
+}
+
+async function call<T>(method: string, payload: Record<string, unknown>, signal?: AbortSignal): Promise<T> {
+  let response: Response
+  try {
+    response = await fetch(`/sidebar/api/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal,
+    })
+  } catch (error) {
+    throw new SidebarApiError('network', error instanceof Error ? error.message : String(error))
+  }
+  const parsed: { ok?: boolean; value?: unknown; error?: { code?: string; message?: string } } | null
+    = await response.json().catch(() => null)
+  if (!response.ok || parsed === null || parsed.ok !== true || parsed.value === undefined) {
+    throw new SidebarApiError(
+      parsed?.error?.code ?? 'http',
+      parsed?.error?.message ?? `HTTP ${response.status}`,
+    )
+  }
+  return parsed.value as T
+}
+
+/**
+ * Upload one file to the sidebar's raw upload route: the File goes straight
+ * into the POST body (no JSON/base64 re-encoding — the host streams it into
+ * the workspace). Failure surfaces as {@link SidebarApiError} with the wire
+ * code, exactly like every `/sidebar/api` call. An aborted `signal` rejects
+ * with the DOMException as-is (the caller decides whether that is an error).
+ */
+async function fetchUpload<T>(
+  scope: SessionScope,
+  dir: string,
+  relativePath: string,
+  body: Blob,
+  signal?: AbortSignal,
+): Promise<T> {
+  const params = new URLSearchParams({ sessionId: scope.sessionId, dir, relativePath })
+  if (scope.cwd !== undefined && scope.cwd !== '') params.set('cwd', scope.cwd)
+  let response: Response
+  try {
+    response = await fetch(`/sidebar/upload?${params.toString()}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/octet-stream' },
+      body,
+      signal,
+    })
+  } catch (error) {
+    if (error instanceof DOMException && error.name === 'AbortError') throw error
+    throw new SidebarApiError('network', error instanceof Error ? error.message : String(error))
+  }
+  const parsed: { ok?: boolean; value?: unknown; error?: { code?: string; message?: string } } | null
+    = await response.json().catch(() => null)
+  if (!response.ok || parsed === null || parsed.ok !== true || parsed.value === undefined) {
+    throw new SidebarApiError(
+      parsed?.error?.code ?? 'http',
+      parsed?.error?.message ?? `HTTP ${response.status}`,
+    )
+  }
+  return parsed.value as T
+}
+
+/** One request's session scope: the conversation id plus its cwd when known. */
+export interface SessionScope {
+  sessionId: string
+  /** The session's working directory from the client list summary (optional). */
+  cwd?: string
+  /** Selected Git repository when cwd is a workspace container. */
+  repoRoot?: string
+}
+
+/** Fold a scope into a JSON payload ({cwd} only when present). */
+function scopePayload(scope: SessionScope, extra: Record<string, unknown>): Record<string, unknown> {
+  return {
+    sessionId: scope.sessionId,
+    ...(scope.cwd !== undefined && scope.cwd !== '' ? { cwd: scope.cwd } : {}),
+    ...(scope.repoRoot !== undefined && scope.repoRoot !== '' ? { repoRoot: scope.repoRoot } : {}),
+    ...extra,
+  }
+}
+
+/** Add a linked-worktree selection to a scoped Git request. The host validates
+ * membership before using it as a command cwd. */
+function gitPayload(scope: SessionScope, worktree: string | undefined, extra: Record<string, unknown>): Record<string, unknown> {
+  return scopePayload(scope, { ...(worktree !== undefined && worktree !== '' ? { worktree } : {}), ...extra })
+}
+
+/** The sidebar API surface (session scope threaded through every call). */
+export const api = {
+  chatcodeStatus: (signal?: AbortSignal) => call<ChatCodeAuthState>('chatcode.status', {}, signal),
+  chatcodeStart: () => call<{ sessionId: string; url: string }>('chatcode.start', {}),
+  chatcodeCancel: (sessionId: string) => call<{ ok: true }>('chatcode.cancel', { sessionId }),
+  chatcodeLogout: () => call<{ ok: true }>('chatcode.logout', {}),
+  /** Check both ChatCode packages (web + CLI) against the npm registry. */
+  chatcodeUpdateCheck: (signal?: AbortSignal) =>
+    call<{ packages: ChatCodeUpdateCheck[] }>('chatcode.update.check', {}, signal),
+  /** Upgrade both ChatCode packages to their npm-latest versions. */
+  chatcodeUpdatePerform: (signal?: AbortSignal) =>
+    call<{ results: ChatCodeUpdateResult[] }>('chatcode.update.perform', {}, signal),
+  releaseNoteCurrent: (packageName: string, versionNum: string, signal?: AbortSignal) =>
+    call<ReleaseNoteResult>('release-note.current', { packageName, versionNum }, signal),
+  /** Per-day token usage of one day range (`YYYY-MM-DD`). */
+  chatcodeTokenTrend: (begin: string, end: string, signal?: AbortSignal) =>
+    call<ChatCodeTokenDay[]>('chatcode.token-trend', { begin, end }, signal),
+  /** Personal commit records of one day range (AI-ratio view). */
+  chatcodeGitCommitStats: (begin: string, end: string, signal?: AbortSignal) =>
+    call<ChatCodeCommitRecord[]>('chatcode.git-commit-stats', { begin, end }, signal),
+  sessionCwd: (scope: SessionScope, signal?: AbortSignal) =>
+    call<{ sessionId: string; cwd: string; root: string; parent: string | null }>('session.cwd', scopePayload(scope, {}), signal),
+  fsTree: (scope: SessionScope, path: string, signal?: AbortSignal) =>
+    call<{ path: string; entries: FsEntry[]; truncated: boolean }>('fs.tree', scopePayload(scope, { path }), signal),
+  /** Global recursive file-name search rooted at the session cwd (the editor
+   *  side panel's search box); matches are cwd-relative '/'-separated paths. */
+  fsSearch: (scope: SessionScope, query: string, signal?: AbortSignal) =>
+    call<{ matches: string[]; truncated: boolean }>('fs.search', scopePayload(scope, { query }), signal),
+  fsRead: (scope: SessionScope, path: string, signal?: AbortSignal) =>
+    call<FsTextResult | FsBinaryResult>('fs.read', scopePayload(scope, { path }), signal),
+  fsWrite: (scope: SessionScope, path: string, content: string) =>
+    call<{ ok: true }>('fs.write', scopePayload(scope, { path, content })),
+  /** Upload one file's raw bytes into `dir` (keeps the folder tree via
+   *  `relativePath`); the host streams it under the session workspace. */
+  uploadFile: (scope: SessionScope, dir: string, relativePath: string, body: Blob, signal?: AbortSignal) =>
+    fetchUpload<{ path: string; size: number }>(scope, dir, relativePath, body, signal),
+  gitWorktrees: (scope: SessionScope, signal?: AbortSignal) =>
+    call<GitWorktree[]>('git.worktrees', scopePayload(scope, {}), signal),
+  gitStatus: (scope: SessionScope, worktree?: string, signal?: AbortSignal) =>
+    call<GitStatusResult>('git.status', gitPayload(scope, worktree, {}), signal),
+  gitDiff: (scope: SessionScope, path: string | undefined, staged: boolean, worktree?: string, signal?: AbortSignal) =>
+    call<{ diff: string }>('git.diff', gitPayload(scope, worktree, { ...(path !== undefined ? { path } : {}), staged }), signal),
+  gitStage: (scope: SessionScope, path?: string, worktree?: string) =>
+    call<{ ok: true }>('git.stage', gitPayload(scope, worktree, { ...(path !== undefined ? { path } : {}) })),
+  gitUnstage: (scope: SessionScope, path?: string, worktree?: string) =>
+    call<{ ok: true }>('git.unstage', gitPayload(scope, worktree, { ...(path !== undefined ? { path } : {}) })),
+  gitCommit: (scope: SessionScope, message: string, worktree?: string) =>
+    call<{ ok: true }>('git.commit', gitPayload(scope, worktree, { message })),
+  gitBranch: (scope: SessionScope, worktree?: string, signal?: AbortSignal) =>
+    call<{ current: string; names: string[] }>('git.branch', gitPayload(scope, worktree, {}), signal),
+  gitCheckout: (scope: SessionScope, branch: string, worktree?: string) =>
+    call<{ ok: true }>('git.checkout', gitPayload(scope, worktree, { branch })),
+  /** Recent commit history, lazily pageable (skip/count; defaults 0/30). */
+  gitLog: (scope: SessionScope, count?: number, skip?: number, worktree?: string, signal?: AbortSignal) =>
+    call<GitLogEntry[]>('git.log', gitPayload(scope, worktree, {
+      ...(count !== undefined ? { count } : {}),
+      ...(skip !== undefined ? { skip } : {}),
+    }), signal),
+  /** Full patch text of one commit (diff display for the history rows). */
+  gitCommitDiff: (scope: SessionScope, hash: string, worktree?: string, signal?: AbortSignal) =>
+    call<{ diff: string }>('git.commit-diff', gitPayload(scope, worktree, { hash }), signal),
+  /** Discard the worktree changes of one file (the index is untouched). */
+  gitDiscard: (scope: SessionScope, path: string, worktree?: string) =>
+    call<{ ok: true }>('git.discard', gitPayload(scope, worktree, { path })),
+  /** Revert one commit onto the current branch. */
+  gitRevert: (scope: SessionScope, hash: string, worktree?: string) =>
+    call<{ ok: true }>('git.revert', gitPayload(scope, worktree, { hash })),
+  /** Cherry-pick one commit onto the current branch. */
+  gitCherryPick: (scope: SessionScope, hash: string, worktree?: string) =>
+    call<{ ok: true }>('git.cherry-pick', gitPayload(scope, worktree, { hash })),
+  /** Release a terminal's process immediately (tab closed; the WS close frame
+   *  may be unreachable while the socket is down, so the host also accepts
+   *  this explicit route). */
+  ptyClose: (scope: SessionScope, tab: string) =>
+    call<{ ok: true }>('pty.close', scopePayload(scope, { tab })),
+  /** Release an agent terminal by uuid (tab closed while WS was down). */
+  agentPtyClose: (uuid: string) =>
+    call<{ ok: true }>('agent-pty.close', { uuid }),
+  /** Terminal dependency status (issue #140): after a WS close 1011 with
+   *  reason `pty-deps-missing` the view fetches the full repair details here
+   *  (the close reason itself is capped at 123 bytes). */
+  terminalDeps: () =>
+    call<TerminalDepsStatus>('terminal.deps', {}),
+  /** The effective terminal shell and its display name (plugin-global). */
+  shellGet: () =>
+    call<{ shell: string; name: string }>('shell.get', {}),
+  /** The local display name used by the bottom-left account menu. */
+  accountGet: () =>
+    call<{ userName: string }>('account.get', {}),
+  /** Read the host-cached CodingPlan model catalogue. */
+  codingPlanModels: () =>
+    call<CodingPlanCatalogue>('codingplan.models', {}),
+  /** Refresh the host-cached CodingPlan catalogue. */
+  codingPlanRefresh: () =>
+    call<CodingPlanCatalogue>('codingplan.refresh', {}),
+  /** Read the side card preferences (plugin-global, no session scope). */
+  settingsGet: () =>
+    call<{ value?: unknown; revision?: number; externalDisable?: boolean }>('settings.get', {}),
+  /** Merge a patch into the side card preferences (revision-guarded). */
+  settingsUpdate: (patch: Record<string, unknown>, expectedRevision?: number) =>
+    call<{ value?: unknown; revision?: number }>('settings.update', {
+      patch,
+      ...(expectedRevision !== undefined ? { expectedRevision } : {}),
+    }),
+  /** Probe a URL's response headers (the sidebar browser's embeddability
+   *  check; see the host's browser.probe route). */
+  browserProbe: (url: string, signal?: AbortSignal) =>
+    call<BrowserProbeResult>('browser.probe', { url }, signal),
+  /** External open for the file tree's "open with" menu: reveal a path in
+   *  the OS file manager, or hand a custom-scheme URL (vscode://, cursor://,
+   *  zed://, custom editors) to its registered handler. The host launches
+   *  the platform opener (argv, no shell). */
+  openExternal: (payload: { action: 'reveal'; path: string } | { action: 'url'; url: string }) =>
+    call<{ started: boolean }>('open.external', payload),
+}
+
+/** Absolute URL of the media route for one path (images only). */
+export function mediaUrl(scope: SessionScope, path: string): string {
+  return fileUrl(scope, path, false)
+}
+
+/** Absolute URL of the download route: serves raw bytes (binary-safe) with
+ *  `Content-Disposition: attachment`, so the browser saves the file. */
+export function downloadUrl(scope: SessionScope, path: string): string {
+  return fileUrl(scope, path, true)
+}
+
+/** Shared URL builder for the /sidebar/file route (media vs download). */
+function fileUrl(scope: SessionScope, path: string, download: boolean): string {
+  const params = new URLSearchParams({ sessionId: scope.sessionId, path })
+  if (scope.cwd !== undefined && scope.cwd !== '') params.set('cwd', scope.cwd)
+  if (download) params.set('download', '1')
+  return `/sidebar/file?${params.toString()}`
+}
+
+/**
+ * Absolute URL of the HTML preview route (see html-route.ts): the path is
+ * fully encoded so the previewed page's relative assets resolve back into
+ * the same route with the session scope intact. The UNC marker is
+ * platform-neutral — the host's requireAbsolute resolves the decoded
+ * forward-slash `//server/share/...` form on both win32 and POSIX — so no
+ * client-side platform signal is needed.
+ */
+export function htmlUrl(scope: SessionScope, path: string): string {
+  return encodeHtmlUrl(scope.sessionId, path)
+}

package/src/client/binary-download.tsx

@@ -0,0 +1,23 @@
+/**
+ * The "no preview — download instead" pane: shown by the editor host when no
+ * viewer can render a file (binary without a registered renderer, or the
+ * `binary-download` strategy) and registered as the `binary-download` viewer
+ * component so the declarative route and the host fallback share one UI.
+ */
+import type { ReactNode } from 'react'
+import type { SessionScope } from './api.ts'
+import { downloadUrl } from './api.ts'
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+export function BinaryDownload(props: { scope: SessionScope; path: string }): ReactNode {
+  const { scope, path } = props
+  return (
+    <div className={css.editorBinary}>
+      <span className={css.editorBinaryNotice}>{t('binaryNoPreview')}</span>
+      <a className={css.editorDownloadLink} href={downloadUrl(scope, path)} download>
+        {t('downloadToView')}
+      </a>
+    </div>
+  )
+}

package/src/client/breakpoints.ts

@@ -0,0 +1,61 @@
+/**
+ * Narrow-viewport ("mobile") breakpoint for the sidebar. Width-based, shared
+ * by the layout logic (JS) and the style gates (CSS). The CSS side pairs
+ * with this file via `@media (max-width: 767px)` rules (sidebar.module.css)
+ * — 767px ≡ widths below NARROW_MAX_WIDTH, documented at both ends.
+ *
+ * "Real narrow" on purpose: the mobile layout (one full-screen drawer, the
+ * bottom panel's tabs merged into the right sidebar) is a phone / portrait
+ * tablet experience. The value is deliberately NOT aligned to the DSH app
+ * shell's own 1024px breakpoint — 1024px windows (small laptops, split
+ * panes) keep the desktop two-panel layout.
+ */
+import { useEffect, useState } from 'react'
+
+/** Viewport widths strictly below this are "mobile" (paired CSS: max-width: 767px). */
+export const NARROW_MAX_WIDTH = 768
+
+/** Whether a viewport width is narrow (mobile). */
+export function isNarrowWidth(width: number): boolean {
+  return width < NARROW_MAX_WIDTH
+}
+
+export interface ViewportSize {
+  width: number
+  height: number
+}
+
+/**
+ * Live narrow-viewport flag for components. Reads `window.innerWidth` and
+ * re-measures on resize (rAF-throttled, the repo's existing drag pattern).
+ * Deliberately avoids `matchMedia` (jsdom does not implement it) — the
+ * resize listener is equally exact for a breakpoint that never changes
+ * while the page is open.
+ */
+export function useViewportSize(): ViewportSize {
+  const [size, setSize] = useState<ViewportSize>(() => ({
+    width: typeof window === 'undefined' ? 0 : window.innerWidth,
+    height: typeof window === 'undefined' ? 0 : window.innerHeight,
+  }))
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    let frame: number | null = null
+    const measure = (): void => {
+      frame = null
+      setSize({ width: window.innerWidth, height: window.innerHeight })
+    }
+    const onResize = (): void => {
+      if (frame === null) frame = requestAnimationFrame(measure)
+    }
+    window.addEventListener('resize', onResize)
+    return () => {
+      window.removeEventListener('resize', onResize)
+      if (frame !== null) cancelAnimationFrame(frame)
+    }
+  }, [])
+  return size
+}
+
+export function useNarrowViewport(): boolean {
+  return isNarrowWidth(useViewportSize().width)
+}

package/src/client/browser.ts

@@ -0,0 +1,167 @@
+/**
+ * Pure URL policy for the built-in browser tab: normalize user input into
+ * an http(s) URL, and refuse destinations that would be dangerous to embed
+ * in the sidebar iframe. Kept dependency-free so it is unit-testable.
+ *
+ * The iframe sandbox (opaque origin, no allow-same-origin / top-navigation)
+ * is the primary security boundary; this module is the address-bar gate on
+ * top of it: only http/https may be navigated, and loopback addresses are
+ * refused so a browsed page cannot probe local services by user action.
+ * The GUI's OWN origin is explicitly ALLOWED — the user may open the GUI
+ * itself in the sidebar (debugging, mirroring); the sandbox still renders
+ * it in an opaque origin with no same-origin privileges, exactly like any
+ * other site.
+ */
+
+/** Why a navigation attempt was refused. */
+export type BrowserBlockReason = 'scheme' | 'loopback'
+
+/** Result of normalizing one address-bar input. */
+export type BrowserNavigateResult =
+  | { kind: 'ok'; url: string }
+  | { kind: 'blocked'; reason: BrowserBlockReason }
+  | { kind: 'invalid' }
+
+/** One browser.probe wire result (host fetch of the target's headers). */
+export interface BrowserProbeResult {
+  reachable: boolean
+  /** The final (post-redirect) URL; present when reachable. */
+  url?: string
+  status?: number
+  xFrameOptions?: string
+  /** The CSP frame-ancestors source list; present when the directive exists. */
+  frameAncestors?: string[]
+}
+
+/** Embeddability verdict of one probe. */
+export type Embeddability = 'embeddable' | 'blocked' | 'unknown'
+
+/**
+ * Decide whether a site can render inside the sidebar iframe. The signals
+ * are exactly the ones the BROWSER enforces when it refuses an iframe load:
+ * X-Frame-Options DENY/SAMEORIGIN, or a frame-ancestors directive that does
+ * not allow `*` ('self' here means the SITE's own origin — never ours, so
+ * it also blocks the sidebar). A site we could not reach yields 'unknown'
+ * and the plain iframe stays.
+ */
+export function embeddabilityOf(probe: BrowserProbeResult): Embeddability {
+  if (probe.reachable !== true) return 'unknown'
+  const xfo = probe.xFrameOptions?.trim().toUpperCase()
+  if (xfo === 'DENY' || xfo === 'SAMEORIGIN') return 'blocked'
+  if (probe.frameAncestors !== undefined && !probe.frameAncestors.some(source => source === '*')) return 'blocked'
+  return 'embeddable'
+}
+
+/** A loopback hostname (localhost, IPv6 ::1, 127.0.0.0/8, 0.0.0.0). */
+export function isLoopbackHostname(hostname: string): boolean {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  if (host === 'localhost' || host === '::1' || host === '0.0.0.0') return true
+  const parts = host.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/**
+ * Normalize one address-bar input against the navigation policy.
+ * @param input - raw user text.
+ * @param selfOrigin - the GUI's own origin (window.location.origin). The GUI
+ * itself may be browsed in the sidebar (the sandbox keeps it opaque), so it
+ * is let through BEFORE the loopback check — its host is normally loopback.
+ * @param allowedLoopback - comma-separated loopback allowlist from the side
+ * card prefs (`browserAllowedLoopback`): bare hosts (`localhost`,
+ * `127.0.0.1`) allow every port, `host:port` entries allow exactly that
+ * authority. Entries are matched case-insensitively; portless entries match
+ * the host on any port. Empty allowlist keeps the default loopback block.
+ */
+/** Schemes that must never reach the iframe, even without `//` (javascript:,
+ *  data:, file:, ...). Host:port lookalikes (example.com:8080) are NOT here —
+ *  they parse as hosts below. */
+const FORBIDDEN_SCHEMES = new Set([
+  'javascript', 'data', 'file', 'about', 'vbscript', 'blob',
+  'mailto', 'tel', 'ftp', 'ftps', 'ws', 'wss', 'sftp', 'ssh',
+  'chrome', 'chrome-extension', 'moz-extension', 'edge', 'opera', 'resource', 'view-source',
+])
+
+/** Parse the loopback allowlist into a matcher predicate over host:port. */
+export function parseLoopbackAllowlist(allowlist: string): (host: string, port: string) => boolean {
+  const entries = allowlist.split(',').map(entry => entry.trim().toLowerCase()).filter(entry => entry !== '')
+  const exact = new Set(entries)
+  const hosts = new Set<string>()
+  for (const entry of entries) {
+    if (!entry.includes(':')) hosts.add(entry.replace(/^\[|\]$/g, ''))
+  }
+  return (host, port) => {
+    const key = `${host}:${port}`
+    if (exact.has(key) || exact.has(host)) return true
+    return port !== '' && hosts.has(host)
+  }
+}
+
+/**
+ * Whether a loopback URL is explicitly allowlisted by the side card prefs
+ * (`browserAllowedLoopback`). Only allowlisted local addresses may run with
+ * `allow-same-origin` in the sidebar iframe — needed for local dev servers
+ * (Vite etc.) whose module/HMR/fetch pipeline requires a real origin, while
+ * the page stays cross-origin to the GUI and to every other site.
+ */
+export function isAllowedLoopbackUrl(url: string, allowlist: string): boolean {
+  if (allowlist.trim() === '') return false
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(parsed.hostname)) return false
+  return parseLoopbackAllowlist(allowlist)(parsed.hostname, parsed.port)
+}
+
+export function normalizeBrowserUrl(input: string, selfOrigin: string, allowedLoopback = ''): BrowserNavigateResult {
+  const trimmed = input.trim()
+  if (trimmed === '') return { kind: 'invalid' }
+  // Distinguish an explicit scheme from a bare host:port. "example.com:8080"
+  // would match a naive scheme regex (dots are legal in schemes), so a
+  // scheme prefix is only honored when it is http(s) or a known-forbidden
+  // scheme; anything else is treated as a host and gets https://.
+  const schemeMatch = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(trimmed)
+  let withScheme: string
+  if (schemeMatch === null) {
+    withScheme = `https://${trimmed}`
+  } else {
+    const scheme = schemeMatch[1]!.toLowerCase()
+    if (scheme === 'http' || scheme === 'https') withScheme = trimmed
+    else if (FORBIDDEN_SCHEMES.has(scheme)) return { kind: 'blocked', reason: 'scheme' }
+    else withScheme = `https://${trimmed}`
+  }
+  let url: URL
+  try {
+    url = new URL(withScheme)
+  } catch {
+    return { kind: 'invalid' }
+  }
+  // The protocol backstop: any URL that still parses to a non-http(s)
+  // scheme (e.g. ftp://, ws:// — which carry `//` and skip the list) is
+  // refused here.
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return { kind: 'blocked', reason: 'scheme' }
+  // The GUI's own origin is ALLOWED (the user may browse the GUI itself in
+  // the sidebar; the sandbox renders it in an opaque origin like any other
+  // site). It must be checked before the loopback gate because its host is
+  // normally loopback.
+  try {
+    if (url.origin === new URL(selfOrigin).origin) return { kind: 'ok', url: url.href }
+  } catch {
+    // Unparsable selfOrigin (never in practice): fall through to the loopback gate.
+  }
+  if (isLoopbackHostname(url.hostname)) {
+    // An explicit user allowlist (browserAllowedLoopback) can lift the
+    // loopback block for trusted local dev servers. The sandbox still
+    // renders them in an opaque origin — no GUI access, exactly like any
+    // other browsed site.
+    if (allowedLoopback.trim() !== '' && parseLoopbackAllowlist(allowedLoopback)(url.hostname, url.port)) {
+      return { kind: 'ok', url: url.href }
+    }
+    return { kind: 'blocked', reason: 'loopback' }
+  }
+  return { kind: 'ok', url: url.href }
+}