diff --git a/README.md b/README.md index 1afec16..7009984 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ - [What is BrowserCode?](#about) - [Quickstart](#quickstart) - [Make it your own](#make-it-your-own) +- [Embedding](#embedding) - [Breaking BrowserCode](#breaking-browsercode) - [Roadmap](#roadmap) @@ -88,6 +89,22 @@ Other useful scripts: CLI availability and behavior are configured in [`src/lib/config/tools.ts`](src/lib/config/tools.ts) — this is the place to start if you want to add or tweak a CLI. +

Embedding

+ +BrowserCode can run inside another site's page through `/embed`, composed entirely from the query string. + +```html + +``` + +BrowserPod needs `SharedArrayBuffer`, so the embedding page must send `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`, and the iframe must carry `allow="cross-origin-isolated"`. + +Parameters, panes and further detail are in [`docs/embedding.md`](docs/embedding.md). +

Breaking BrowserCode

This is BrowserCode beta. Don't be kind to it. Stretch it, bend it, find out what breaks. Here are a few walls you might hit: diff --git a/docs/embedding.md b/docs/embedding.md new file mode 100644 index 0000000..09557fb --- /dev/null +++ b/docs/embedding.md @@ -0,0 +1,53 @@ +# Embedding BrowserCode + +BrowserCode runs entirely in the browser. An embed is our page inside your iframe. + +```html + +``` + +## Required headers + +BrowserPod needs `SharedArrayBuffer`, which browsers expose only on cross-origin isolated pages. Isolation is inherited from the top-level document, so the embedding page must send both headers itself: + +``` +Cross-Origin-Opener-Policy: same-origin +Cross-Origin-Embedder-Policy: require-corp +``` + +The iframe must carry `allow="cross-origin-isolated"`. Without all three the embed reports that the headers are missing. + +`require-corp` blocks cross-origin resources on your page that do not send `Cross-Origin-Resource-Policy` or use CORS. + +## Parameters + +| Parameter | Value | +| ----------- | ----------------------------------------------------------------------------- | +| `repo` | Any GitHub URL or `owner/repo`, optionally `.../tree//` | +| `framework` | A template id (`vite`, `react`, `svelte`, `vue`, `nextjs`, `nuxt`, `express`) | +| `agent` | A CLI agent id (`claude`, `codex`) | +| `view` | Comma separated: `files`, `search`, `editor`, `terminal`, `preview` | + +## Behaviour + +- Pass one of `agent`, `repo` or `framework`. With none, the default template boots. +- `view` defaults to every pane. +- Agents are terminal first, so `view` only decides whether the preview pane comes with it. +- One agent session per browser. A second embed of the same agent, or the same agent open in another tab, shows the duplicate session dialog. +- `codex` asks for an OpenAI API key inside the frame. +- `claude` opens a new tab for OAuth sign-in. +- Controls without meaning are omitted: a preview-only embed has no hide button and no port badge. + +## Examples + +``` +/embed?repo=https://github.com/user/repo/tree/main/examples/demo +/embed?framework=vite&view=preview +/embed?framework=nextjs&view=files,editor,terminal +/embed?agent=claude +/embed?agent=codex&view=terminal +``` diff --git a/src/hooks.server.ts b/src/hooks.server.ts index 8006769..3279dbb 100644 --- a/src/hooks.server.ts +++ b/src/hooks.server.ts @@ -1,13 +1,21 @@ import type { Handle } from '@sveltejs/kit'; +const AGENTS_CSP = + "frame-ancestors 'self' https://browserpod.io https://*.browserpod.io https://*.browserpod.pages.dev"; + +/** Dev mirror of `static/_headers`; the static build has no server, so keep the two in step. */ export const handle: Handle = async ({ event, resolve }) => { const response = await resolve(event); response.headers.set('Cross-Origin-Opener-Policy', 'same-origin'); response.headers.set('Cross-Origin-Embedder-Policy', 'require-corp'); response.headers.set('Cross-Origin-Resource-Policy', 'cross-origin'); - response.headers.set( - 'Content-Security-Policy', - "frame-ancestors 'self' https://browserpod.io https://*.browserpod.io https://*.browserpod.pages.dev" - ); + + // Clears the blanket frame-ancestors vite.config.ts sets, so only /agents stays unframable. + if (event.url.pathname.startsWith('/agents')) { + response.headers.set('Content-Security-Policy', AGENTS_CSP); + } else { + response.headers.delete('Content-Security-Policy'); + } + return response; }; diff --git a/src/lib/agents/codex.ts b/src/lib/agents/codex.ts index 58118f8..1ad3c6c 100644 --- a/src/lib/agents/codex.ts +++ b/src/lib/agents/codex.ts @@ -22,12 +22,22 @@ code_mode = false code_mode_only = false `; +/** Embedded in a third-party frame the browser may partition storage away, or refuse it outright. */ export function getCodexApiKey(): string | null { - return localStorage.getItem(API_KEY_STORAGE); + try { + return localStorage.getItem(API_KEY_STORAGE); + } catch (error) { + console.warn('Could not read the stored API key:', error); + return null; + } } export function setCodexApiKey(key: string): void { - localStorage.setItem(API_KEY_STORAGE, key); + try { + localStorage.setItem(API_KEY_STORAGE, key); + } catch (error) { + console.warn('Could not persist the API key:', error); + } } /** Codex reads the key from its environment, so it is only injectable at launch. */ diff --git a/src/lib/agents/session.svelte.ts b/src/lib/agents/session.svelte.ts index 035ddd8..0ad49ac 100644 --- a/src/lib/agents/session.svelte.ts +++ b/src/lib/agents/session.svelte.ts @@ -33,7 +33,10 @@ export class AgentSession { private releaseLock: () => void = () => {}; private disposeLeaveGuard: () => void = () => {}; - constructor(requestedTool: string | undefined) { + private readonly leaveGuard: boolean; + + constructor(requestedTool: string | undefined, options: { leaveGuard?: boolean } = {}) { + this.leaveGuard = options.leaveGuard ?? true; this.id = resolveToolId(requestedTool); // resolveToolId only ever returns an id that is in toolItems, so this always resolves. this.tool = toolItems.find((item) => item.id === this.id)!; @@ -58,7 +61,7 @@ export class AgentSession { this.lock = 'held'; // Only warn on tab close/refresh/back-button once there is work here to lose. - this.disposeLeaveGuard = installLeaveGuard(); + if (this.leaveGuard) this.disposeLeaveGuard = installLeaveGuard(); // Covers pod boot, the image streaming in, and any warm-up probe. this.gate?.begin(); diff --git a/src/lib/components/PodBlockerOverlay.svelte b/src/lib/components/PodBlockerOverlay.svelte new file mode 100644 index 0000000..3cfbd7d --- /dev/null +++ b/src/lib/components/PodBlockerOverlay.svelte @@ -0,0 +1,43 @@ + + +
+
+
+ +
+ {#if blocker === 'not-isolated'} +

Isolation headers missing

+

+ The page embedding this frame must send + Cross-Origin-Opener-Policy: same-origin + and + Cross-Origin-Embedder-Policy: require-corp, and set + allow="cross-origin-isolated" on the iframe. +

+ Learn more + {:else} +

Incompatible Browser

+

+ Requires Atomics.waitAsync (Chrome, Edge, Safari 16.4+). +

+ {/if} +
+
diff --git a/src/lib/components/Portal.svelte b/src/lib/components/Portal.svelte index 334f14f..f8b14f5 100644 --- a/src/lib/components/Portal.svelte +++ b/src/lib/components/Portal.svelte @@ -10,9 +10,11 @@ onBeforeReload?: () => Promise; /** Collapses the pane; omitted by hosts with nowhere to collapse to. */ onCollapse?: () => void; + /** Which server the frame shows. A lone preview has nothing to choose between. */ + showPort?: boolean; }; - let { portal, onBeforeReload, onCollapse }: Props = $props(); + let { portal, onBeforeReload, onCollapse, showPort = true }: Props = $props(); /** Matches the sweep animation below. */ const SWEEP_MS = 620; @@ -112,7 +114,7 @@ {/if} - {#if portal.url} + {#if portal.url && showPort}
+ {#if onCancel} + + {/if} + {#if onCancel} + + {/if}
diff --git a/src/lib/components/agents/AgentShell.svelte b/src/lib/components/agents/AgentShell.svelte index cab14bb..e592c2b 100644 --- a/src/lib/components/agents/AgentShell.svelte +++ b/src/lib/components/agents/AgentShell.svelte @@ -9,12 +9,17 @@ import { PortalState } from '$lib/stores/portals.svelte'; import { zenState } from '$lib/stores/zen.svelte'; import { startDrag } from '$lib/utils/drag'; + import { podBlocker, type PodBlocker } from '$lib/utils/platform'; + import PodBlockerOverlay from '$lib/components/PodBlockerOverlay.svelte'; + import { FULL_SHELL, type ShellOptions } from '$lib/ide/shell-options'; import { watchIsMobile } from '$lib/utils/viewport'; import CredentialGateOverlay from './CredentialGateOverlay.svelte'; import TerminalTip from './TerminalTip.svelte'; import ToolMenuSheet from './ToolMenuSheet.svelte'; - let { session }: { session: AgentSession } = $props(); + // `shell` narrows what renders; the agents page omits it and gets the lot. Agents read the + // preview and tools fields only, the terminal being the session itself. + let { session, shell = FULL_SHELL }: { session: AgentSession; shell?: ShellOptions } = $props(); /** The div the pod's terminal attaches to, rendered by Terminal.svelte. */ let consoleEl = $state(null); @@ -24,6 +29,8 @@ let portalFraction = $state(0.5); let isDragging = $state(false); + let blocker = $state(null); + let isMobile = $state(false); let activeMobileView = $state<'terminal' | 'preview'>('terminal'); @@ -72,8 +79,12 @@ onMount(() => { const unwatchIsMobile = watchIsMobile((mobile) => (isMobile = mobile)); - if (consoleEl) session.boot(consoleEl, portal.apply); - else console.error('Terminal container is not ready yet'); + // Booting without SharedArrayBuffer fails deep inside the pod, leaving a blank terminal. + blocker = podBlocker(); + if (!blocker) { + if (consoleEl) session.boot(consoleEl, portal.apply); + else console.error('Terminal container is not ready yet'); + } return () => { // Never leave the global chrome hidden after navigating away from an agent session. @@ -88,6 +99,10 @@
+ {#if blocker} + + {/if} +
@@ -95,7 +110,7 @@ - {#if !isMobile} + {#if !isMobile && shell.tools} {/if} {/if} @@ -132,7 +147,7 @@ {/if} - {#if !isMobile && portal.portals.length > 0 && isPortalVisible} + {#if !isMobile && shell.preview && portal.portals.length > 0 && isPortalVisible}
- {:else if isMobile && portal.portals.length > 0 && activeMobileView === 'preview'} + {:else if isMobile && shell.preview && portal.portals.length > 0 && activeMobileView === 'preview'}
@@ -162,7 +177,7 @@
{#if isMobile} - {#if showToolMenu} + {#if showToolMenu && shell.tools} - + {#if shell.tools} + + {/if} - {#if portal.portals.length > 0} + {#if shell.preview && portal.portals.length > 0} {/if} - + {#if shell.tools} + + {/if} {/if} diff --git a/src/lib/components/agents/CredentialGateOverlay.svelte b/src/lib/components/agents/CredentialGateOverlay.svelte index 9017d04..2ab5c8e 100644 --- a/src/lib/components/agents/CredentialGateOverlay.svelte +++ b/src/lib/components/agents/CredentialGateOverlay.svelte @@ -12,7 +12,7 @@ /** Relaunches the CLI, which is the only way a retry or a new secret takes effect. */ onRestart: () => void; /** Abandons the boot; every stage here is reached before the CLI has started. */ - onCancel: () => void; + onCancel?: () => void; }; let { gate, tool, credential, onRestart, onCancel }: Props = $props(); diff --git a/src/lib/components/ide/IdeShell.svelte b/src/lib/components/ide/IdeShell.svelte index 34b8c0e..1e91725 100644 --- a/src/lib/components/ide/IdeShell.svelte +++ b/src/lib/components/ide/IdeShell.svelte @@ -1,5 +1,5 @@ -
+
+ + {#if blocker} + + {/if} + -
-
- - {session.source.label} - {#if session.selectedFile} - / - {session.selectedFile} - {/if} - {#if session.isSaving} - saving… - {/if} -
-
+ {#if shell.header} +
+
+ + {session.source.label} + {#if session.selectedFile} + / + {session.selectedFile} + {/if} + {#if session.isSaving} + saving… + {/if} +
+
+ {/if}
- + {#if hasRail} + + {/if} {#if isMobile && activePanel} @@ -349,25 +392,24 @@
- {#if !isMobile} + {#if !isMobile && shell.editor && shell.terminal}
- {#if !isMobile && isPreviewVisible} + {#if !isMobile && isPreviewVisible && collapsiblePreview} - {/if} - -
- {#if !isCompatibleBrowser} -
+ {#if previewCollapsed} +
- {:else} + {/if} + + {/if} + +
{#if portal.portals.length > 0} session.saveAll()} - onCollapse={isMobile ? undefined : togglePreview} + onCollapse={isMobile || !collapsiblePreview ? undefined : togglePreview} + showPort={hasLeftColumn} /> {/if} @@ -469,42 +496,28 @@ />
{/if} - {/if} +
-
+ {/if}
- {#if isMobile} + {#if isMobile && mobileTabs.length > 1} {/if} diff --git a/src/lib/embed/options.ts b/src/lib/embed/options.ts new file mode 100644 index 0000000..d2b2454 --- /dev/null +++ b/src/lib/embed/options.ts @@ -0,0 +1,62 @@ +/** Parses the `/embed` query string, so a host page composes an embed entirely from the URL. */ +import { defaultFrameworkId, isFrameworkId, type FrameworkId } from '$lib/config/frameworks'; +import { isEnabledTool, type ToolId } from '$lib/config/tools'; +import { parseGitHubUrl, type ParsedRepo } from '$lib/github/parse'; +import type { ShellOptions } from '$lib/ide/shell-options'; + +export type EmbedSource = + | { kind: 'framework'; id: FrameworkId } + | { kind: 'repo'; ref: ParsedRepo } + | { kind: 'agent'; id: ToolId }; + +export type EmbedOptions = { source: EmbedSource; shell: ShellOptions }; + +const VIEWS = ['files', 'search', 'editor', 'terminal', 'preview'] as const; +type View = (typeof VIEWS)[number]; + +/** Narrows a raw `view=` entry, so unknown names fall out of the list rather than throwing. */ +function isView(value: string): value is View { + return (VIEWS as readonly string[]).includes(value); +} + +/** Null when the URL names a project we cannot boot, so the route can report the bad parameter. */ +export function parseEmbedOptions(url: URL): EmbedOptions | null { + const source = parseSource(url); + return source && { source, shell: parseShell(url) }; +} + +/** `agent` then `repo` then `framework`; a bad value of any is an error, not a silent fallback. */ +function parseSource(url: URL): EmbedSource | null { + const agent = url.searchParams.get('agent'); + if (agent !== null) return isEnabledTool(agent) ? { kind: 'agent', id: agent } : null; + + const repo = url.searchParams.get('repo'); + if (repo) { + const ref = parseGitHubUrl(repo); + return ref && { kind: 'repo', ref }; + } + const framework = url.searchParams.get('framework'); + if (framework === null) return { kind: 'framework', id: defaultFrameworkId }; + return isFrameworkId(framework) ? { kind: 'framework', id: framework } : null; +} + +/** Turns `view=` into the shell's panes, leaving the playground-only chrome off throughout. */ +function parseShell(url: URL): ShellOptions { + const requested = url.searchParams.get('view'); + const views = requested ? requested.split(',').map((view) => view.trim()) : [...VIEWS]; + const shown = new Set(views.filter(isView)); + // An unrecognised `view` would otherwise render an empty shell. + if (shown.size === 0) VIEWS.forEach((view) => shown.add(view)); + + return { + // Names the project and open file, which is chrome without an editor. + header: shown.has('editor'), + fileTree: shown.has('files'), + search: shown.has('search'), + editor: shown.has('editor'), + terminal: shown.has('terminal'), + preview: shown.has('preview'), + tools: false, + leaveGuard: false + }; +} diff --git a/src/lib/ide/shell-options.ts b/src/lib/ide/shell-options.ts new file mode 100644 index 0000000..c776fc2 --- /dev/null +++ b/src/lib/ide/shell-options.ts @@ -0,0 +1,24 @@ +/** Which parts of the IDE shell render. Embeds narrow this; the playground takes `FULL_SHELL`. */ +export type ShellOptions = { + header: boolean; + fileTree: boolean; + search: boolean; + editor: boolean; + terminal: boolean; + preview: boolean; + /** Settings, bug report and zen toggle. */ + tools: boolean; + /** The beforeunload prompt, which an embed would fire inside the host's page. */ + leaveGuard: boolean; +}; + +export const FULL_SHELL: ShellOptions = { + header: true, + fileTree: true, + search: true, + editor: true, + terminal: true, + preview: true, + tools: true, + leaveGuard: true +}; diff --git a/src/lib/utils/platform.ts b/src/lib/utils/platform.ts index 8c2a34c..9f576e3 100644 --- a/src/lib/utils/platform.ts +++ b/src/lib/utils/platform.ts @@ -9,3 +9,16 @@ export function isIos(): boolean { (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1) ); } + +/** Why BrowserPod cannot run here, or null when it can. */ +export type PodBlocker = 'unsupported-browser' | 'not-isolated'; + +/** + * SharedArrayBuffer is only exposed on cross-origin isolated pages, and isolation is inherited + * from the top-level document, so an embed fails here when its host page omits the headers. + */ +export function podBlocker(): PodBlocker | null { + if (typeof Atomics?.waitAsync !== 'function') return 'unsupported-browser'; + if (!globalThis.crossOriginIsolated) return 'not-isolated'; + return null; +} diff --git a/src/routes/+layout.svelte b/src/routes/+layout.svelte index 8dd76a9..9550717 100644 --- a/src/routes/+layout.svelte +++ b/src/routes/+layout.svelte @@ -19,9 +19,13 @@ // flyouts) the rest of the time. let ribbonAboveTour = $derived(stepperState.open && stepperState.step === 6); + // Embeds render inside a host page, where none of the app chrome belongs. + let isEmbed = $derived($page.route.id?.startsWith('/embed') ?? false); + // Show on the landing surfaces (Home, /agents, bare /ide) and during tour step 6. let showRibbon = $derived( !zenState.on && + !isEmbed && (ribbonAboveTour || $page.route.id === '/' || $page.route.id === '/agents' || @@ -85,9 +89,11 @@
- - - {#if !zenState.on} + {#if !isEmbed} + + + {/if} + {#if !zenState.on && !isEmbed} {/if} @@ -121,7 +127,7 @@
- {#if !zenState.on} + {#if !zenState.on && !isEmbed} {/if} diff --git a/src/routes/embed/+page.svelte b/src/routes/embed/+page.svelte new file mode 100644 index 0000000..8346790 --- /dev/null +++ b/src/routes/embed/+page.svelte @@ -0,0 +1,61 @@ + + +{#if options && agentSession} +
+ {#if agentSession.lock === 'taken'} + + {/if} + +
+{:else if options && ideSession} + +{:else} +
+
+
+ +
+

Nothing to boot

+

Pass one of

+
    +
  • ?repo=<github url>
    • +
  • ?framework=<id>
    • +
  • ?agent=<id>
    • +
+

+ optionally with &view=files,editor,terminal,preview. +

+
+
+{/if} diff --git a/static/_headers b/static/_headers index 90cb508..32b99a2 100644 --- a/static/_headers +++ b/static/_headers @@ -1,6 +1,10 @@ -# Enable Cross-Origin Isolation and allow embedding from browserpod.io (and CI previews) +# Cross-origin isolation for SharedArrayBuffer. Do not remove. /* Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp Cross-Origin-Resource-Policy: cross-origin + +# Takes an API key, so it stays unframable. Every other route carries no frame-ancestors, which +# is what lets a host page embed /embed. +/agents* Content-Security-Policy: frame-ancestors 'self' https://browserpod.io https://*.browserpod.io https://*.browserpod.pages.dev