@keith9681/dsh-sidebar 0.15.2

package/src/client/api.ts

@@ -0,0 +1,335 @@
+/**
+ * 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 { LastActivity } from '../subagent-activity.ts'
+import type { SidechatThreadInfo } from '../sidechat-core.ts'
+import type { BrowserProbeResult } from './browser.ts'
+
+/** One wire failure. */
+export class SidebarApiError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** 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[]
+}
+
+/** 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 }
+
+/**
+ * One jobs.output response: the output the MODEL has read so far for the
+ * job (replayed from the owner session's event log — the model's
+ * job_output cursor is never touched, so the pane can never steal the
+ * agent's bytes). `read` is false until the model actually called
+ * job_output for the job.
+ */
+export interface JobOutputResult {
+  text: string
+  /** True when the host capped the text at its output limit. */
+  truncated: boolean
+  /** Whether the model has read the job at least once. */
+  read: boolean
+}
+
+/** The `subagents.live` response: running child id → latest activity. */
+export type SubagentLiveResult = { live: Record<string, LastActivity> }
+
+/** 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
+  }
+
+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
+}
+
+/** 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 } : {}), ...extra }
+}
+
+/** The sidebar API surface (session scope threaded through every call). */
+export const api = {
+  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),
+  gitStatus: (scope: SessionScope, signal?: AbortSignal) =>
+    call<GitStatusResult>('git.status', scopePayload(scope, {}), signal),
+  gitDiff: (scope: SessionScope, path: string | undefined, staged: boolean, signal?: AbortSignal) =>
+    call<{ diff: string }>('git.diff', scopePayload(scope, { ...(path !== undefined ? { path } : {}), staged }), signal),
+  gitStage: (scope: SessionScope, path?: string) =>
+    call<{ ok: true }>('git.stage', scopePayload(scope, { ...(path !== undefined ? { path } : {}) })),
+  gitUnstage: (scope: SessionScope, path?: string) =>
+    call<{ ok: true }>('git.unstage', scopePayload(scope, { ...(path !== undefined ? { path } : {}) })),
+  gitCommit: (scope: SessionScope, message: string) =>
+    call<{ ok: true }>('git.commit', scopePayload(scope, { message })),
+  gitBranch: (scope: SessionScope, signal?: AbortSignal) =>
+    call<{ current: string; names: string[] }>('git.branch', scopePayload(scope, {}), signal),
+  gitCheckout: (scope: SessionScope, branch: string) =>
+    call<{ ok: true }>('git.checkout', scopePayload(scope, { branch })),
+  /** Recent commit history, lazily pageable (skip/count; defaults 0/30). */
+  gitLog: (scope: SessionScope, count?: number, skip?: number, signal?: AbortSignal) =>
+    call<GitLogEntry[]>('git.log', scopePayload(scope, {
+      ...(count !== undefined ? { count } : {}),
+      ...(skip !== undefined ? { skip } : {}),
+    }), signal),
+  /** Full patch text of one commit (diff display for the history rows). */
+  gitCommitDiff: (scope: SessionScope, hash: string, signal?: AbortSignal) =>
+    call<{ diff: string }>('git.commit-diff', scopePayload(scope, { hash }), signal),
+  /** Discard the worktree changes of one file (the index is untouched). */
+  gitDiscard: (scope: SessionScope, path: string) =>
+    call<{ ok: true }>('git.discard', scopePayload(scope, { path })),
+  /** Revert one commit onto the current branch. */
+  gitRevert: (scope: SessionScope, hash: string) =>
+    call<{ ok: true }>('git.revert', scopePayload(scope, { hash })),
+  /** Cherry-pick one commit onto the current branch. */
+  gitCherryPick: (scope: SessionScope, hash: string) =>
+    call<{ ok: true }>('git.cherry-pick', scopePayload(scope, { 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 output the model has read so far for one background job (replayed
+   * from the owner session's event log — never the model's job_output
+   * cursor). The scope MUST be the job's OWNER session.
+   */
+  jobOutput: (scope: SessionScope, id: string, signal?: AbortSignal) =>
+    call<JobOutputResult>('jobs.output', scopePayload(scope, { id }), signal),
+  /** Request cancellation of one background job (live jobs flip to stopping). */
+  jobKill: (scope: SessionScope, id: string, reason?: string) =>
+    call<{ ok: true; outcome: 'requested' | 'already-finished' }>('jobs.kill', scopePayload(scope, {
+      id,
+      ...(reason !== undefined ? { reason } : {}),
+    })),
+  /**
+   * One batch live-preview fetch for the whole Subagent tree. The payload is
+   * the already-resolved topology ROOT (not a session scope); the host
+   * enumerates descendants once and folds running children's activity.
+   */
+  subagentsLive: (rootSessionId: string, signal?: AbortSignal) =>
+    call<SubagentLiveResult>('subagents.live', { rootSessionId }, signal),
+  /** Create a Side Chat thread: a child session seeded with the parent's
+   *  full log up to now. Empty question = immediate create (Codex-style):
+   *  the thread opens empty, the first prompt carries the boundary. */
+  sidechatStart: (sessionId: string, question?: string) =>
+    call<{ childId: string }>('sidechat.start', { sessionId, question: question ?? '' }),
+  /** Deliver one follow-up message to a Side Chat thread. */
+  sidechatPrompt: (childId: string, text: string) =>
+    call<{ accepted: true }>('sidechat.prompt', { childId, text }),
+  /** Abort a Side Chat thread's running turn (queued work is preserved). */
+  sidechatCancel: (childId: string) =>
+    call<{ accepted: true }>('sidechat.cancel', { childId }),
+  /** Release a Side Chat thread's live agent (history stays persisted). */
+  sidechatDispose: (childId: string) =>
+    call<{ accepted: true }>('sidechat.dispose', { childId }),
+  /** Live state + agent identity (provider/model/preset) of a thread. */
+  sidechatInfo: (childId: string) =>
+    call<SidechatThreadInfo>('sidechat.info', { childId }),
+  /** The effective terminal shell and its display name (plugin-global). */
+  shellGet: () =>
+    call<{ shell: string; name: string }>('shell.get', {}),
+  /** Whether the session may write files (host truth; default false = read-only). */
+  configGet: (scope: SessionScope) =>
+    call<{ editable: boolean }>('config.get', scopePayload(scope, {})),
+  /** Switch the session's write permission (the editor toolbar toggle). */
+  configSetEditable: (scope: SessionScope, editable: boolean) =>
+    call<{ ok: true }>('config.set-editable', scopePayload(scope, { editable })),
+  /** 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,51 @@
+/**
+ * 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
+}
+
+/**
+ * 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 useNarrowViewport(): boolean {
+  const [narrow, setNarrow] = useState(
+    () => typeof window !== 'undefined' && isNarrowWidth(window.innerWidth),
+  )
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    let frame: number | null = null
+    const measure = (): void => {
+      frame = null
+      setNarrow(isNarrowWidth(window.innerWidth))
+    }
+    const onResize = (): void => {
+      if (frame === null) frame = requestAnimationFrame(measure)
+    }
+    window.addEventListener('resize', onResize)
+    return () => {
+      window.removeEventListener('resize', onResize)
+      if (frame !== null) cancelAnimationFrame(frame)
+    }
+  }, [])
+  return narrow
+}

package/src/client/browser.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+/** 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',
+])
+
+export function normalizeBrowserUrl(input: string, selfOrigin: string): 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)) return { kind: 'blocked', reason: 'loopback' }
+  return { kind: 'ok', url: url.href }
+}

package/src/client/builtins/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Built-in registration: the plugin registers its own tab pages and file
+ * previewers through the same {@link BetterSidebarService} external plugins
+ * use — eating its own dogfood. The descriptors live next to their feature
+ * modules (tabs.tsx / viewers.tsx); this module only aggregates them and
+ * owns the disposer lifecycle (cordis auto-invokes it on fiber disposal,
+ * HMR-safe).
+ */
+import type { Context } from '../../context-types.ts'
+import type { BetterSidebarService } from '../service.ts'
+import { builtinTabs, type BuiltinTabOptions } from './tabs.tsx'
+import { builtinViewers } from './viewers.tsx'
+
+/**
+ * Register all built-in tabs and viewers with the service. Returns a
+ * disposer that unregisters everything (cordis auto-invokes it on fiber
+ * disposal). The `ctx` is threaded into tab descriptors that need it
+ * (EditorHost reads `ctx.betterSidebar` for file-viewer matching).
+ */
+export function registerBuiltins(
+  ctx: Context,
+  service: BetterSidebarService,
+  options: BuiltinTabOptions = {},
+): () => void {
+  const disposers: (() => void)[] = []
+  for (const tab of builtinTabs(ctx, options)) {
+    disposers.push(service.registerTab(tab))
+  }
+  for (const viewer of builtinViewers()) {
+    disposers.push(service.registerFileViewer(viewer))
+  }
+  return () => {
+    for (const d of disposers) {
+      try { d() } catch { /* already disposed */ }
+    }
+  }
+}