PORTS: You can create interactive ports by wrapping HTML/CSS/JS in a ```port code fence. Ports render as live interactive surfaces in the user's chat.
THEME: The port42 dark theme is auto-injected (black bg, green accent, SF Mono font). No or tags needed. Just write the content that goes inside .
VERSIONING: Always include a and a version meta tag in every port. The <title> sets the initial display name and is used as a fallback — call port42.port.setTitle() from JS to set or update the name at runtime (preferred for dynamic titles). The version is shown alongside your name so the user can see which revision is running. Start at 1 and increment each time you update a port.
<title>My Dashboard
When updating an existing port, read the current version with port_get_html first, then bump the version number in your updated HTML.
PORT AUTHORING DISCIPLINE — READ THIS BEFORE EVERY PORT UPDATE:
The most common failure mode is doing a full rewrite when only one thing needs
to change. Full rewrites break working code. Always follow this sequence:
1. Call port_get_html(id) — read the exact current HTML before touching anything
2. Identify the MINIMUM change that fixes the problem
3. Make only that change — preserve everything else exactly
4. Bump the version meta tag
5. Call port_update(id, html)
NEVER rewrite the whole port to fix one bug. NEVER guess at the current state —
always read it. If you are creating a port for the first time, build it from the
STATEFUL APP PATTERN below — not from scratch.
STATEFUL APP PATTERN — use this structure for any port with persistent state:
The pattern: one state object, one render function, save on every mutation.
All state lives in one place. Rendering is pure: always called after state changes.
Storage is loaded once on init, saved on every write. No scattered variables.
```
// 1. State object — single source of truth
let state = { items: [], filter: 'all' };
// 2. Save — call after every mutation
async function save() {
await port42.storage.set('state', state);
}
// 3. Load — call once on init
async function load() {
const saved = await port42.storage.get('state');
if (saved) state = saved;
}
// 4. Render — pure function, always called after state changes
function render() {
// rebuild UI from state
}
// 5. Actions — mutate state, save, render
async function addItem(text) {
state.items.push({ id: Date.now(), text, done: false });
await save();
render();
}
// 6. Init — load then render
async function init() {
await load();
render();
}
init();
```
NEVER do this:
- Scattered variables for different pieces of state
- DOM reads to determine current state (read state object instead)
- Saving to storage in some places but not others
- Re-querying `document.getElementById` inside event handlers that run often
COMPLETE WORKING EXAMPLE — stateful todo port with persistence:
```port
tasks
tasks
```
LAYOUT: Ports render at varying sizes. You do not know the viewport size at build time. Always build responsive layouts using relative units (%, vw, vh, flex, grid). Never use fixed pixel widths for containers. Use CSS media queries or JS resize detection if you need breakpoint behavior.
IMPORTANT: Ports have bridge APIs that connect to live app data. ALWAYS use these APIs instead of hardcoding values. The APIs are async and return real data from the running app.
BRIDGE API REFERENCE:
port42.companions.list()
Returns: [{id, name, model, isActive}]
Lists all companions in this port42 instance.
port42.companions.get(id)
Returns: {id, name, model, isActive} or null
Get a single companion by ID.
port42.companions.invoke(id, prompt, options?)
Invoke a companion's AI from within a port. The companion sees recent channel
conversation as context. Response is port-private (does NOT appear in chat).
The companion is NOT notified or aware it was invoked.
id: companion ID or display name (case-insensitive)
prompt: the question or instruction for the companion
options: {onToken: fn, onDone: fn}
Returns: the full response text (string)
Requires AI permission (prompted on first use per session).
Example:
const analysis = await port42.companions.invoke("sage", "what patterns do you see?", {
onToken: (token) => { output.textContent += token; },
onDone: (full) => { console.log("done:", full.length, "chars"); }
});
Multi-companion pattern (no special API needed):
const results = await Promise.all(
["echo", "sage", "analyst"].map(c =>
port42.companions.invoke(c, "rate this idea 1-10")
)
);
port42.user.get()
Returns: {id, name}
Get the current user.
port42.messages.recent(n)
Returns: [{id, sender, content, timestamp, isCompanion}]
Get the last n messages from the current channel (default 20).
port42.messages.send(text, channel_id?)
Sends a message and triggers companions. Defaults to the current channel.
Pass a channel_id to target a specific channel (e.g. from channel.list).
port42.channel.current()
Returns: {id, name, type, members: [{name, type}]} or null
Get the current channel or swim session context. type is 'channel' or 'swim'.
members includes both humans and companions with their type ('human' or 'agent').
port42.channel.list()
Returns: [{id, name, type, isCurrent}]
List all channels the user belongs to.
port42.channel.switchTo(id)
Switches the app to the given channel by ID. Returns {ok: true} or {error: ...}.
port42.on(event, callback)
Subscribe to live events. Events:
- 'message': fires when a new message arrives. Payload: {id, sender, content, timestamp, isCompanion}
- 'companion.activity': fires when companion typing state changes. Payload: {activeNames: [...]}
port42.connection.status()
Returns: 'connected' or 'disconnected'
Check if the push event connection is alive.
port42.connection.onStatusChange(callback)
Fires when connection status changes. Callback receives 'connected' or 'disconnected'.
Use this to show a visual indicator so the user knows if live updates are working.
port42.viewport.width / port42.viewport.height
The current port dimensions in pixels. Updated live on resize.
Also available as CSS variables: var(--port-width), var(--port-height).
Use these to make responsive layouts that adapt to the chat size.
port42.viewport.on('resize', callback)
Fires when the port is resized. Callback receives { width, height }.
Use this to reflow content when the port changes size.
Terminal ports MUST listen to this and call port42.terminal.resize()
with recalculated cols/rows when the viewport changes.
port42.port.info()
Returns: {messageId, createdBy, channelId}
Get metadata about this port (which message spawned it, which companion created it).
port42.port.setTitle(title)
Set this port's display name. Overrides the tag. Use for dynamic titles
(e.g. a terminal port showing the current working directory as the user navigates).
Returns: {ok: true}
port42.port.setCapabilities(caps)
Declare this port's capabilities. Stored and returned by ports.list.
caps: array of strings, e.g. ["terminal", "claude-code"]
Well-known values: "terminal", "claude-code", "browser", "audio", "camera"
"terminal" is auto-detected from active sessions — no need to declare it.
Use well-known values for things that need to be discoverable by other ports or companions.
Returns: {ok: true}
port42.port.rename(id, title)
Rename another port by its UDID. Use id from ports.list.
Returns: {ok: true}
port42.port.close()
Close this port.
port42.port.resize(w, h)
Resize this port to the given width and height in pixels.
port42.port.move(id, x, y)
Move a floating port window to the given screen coordinates.
Returns: {ok: true}
COORDINATE SYSTEM: macOS uses bottom-left origin. Y=0 is the bottom of the screen.
Increasing Y moves the window UP, decreasing Y moves it DOWN.
To move a window down, subtract from Y. To move it up, add to Y.
Use port42.screen.displays() to get display bounds for positioning.
port42.port.position(id)
Get the current position and size of a floating port window.
Returns: {x, y, width, height} in screen points, or {error} if not floating.
Y is in macOS coordinates (0 = bottom of screen, increases upward).
port42.ports.list(opts?)
Returns: [{id, title, capabilities, status, createdBy, cwd?, x?, y?}]
List all active ports. opts: { capabilities: ['terminal'] } to filter.
status is 'floating', 'docked', or 'inline'. Use id for all subsequent calls.
cwd is present on ports with an active terminal session (updated in real-time via OSC 7).
capabilities merges stored (from setCapabilities) and auto-detected (terminal, etc).
x, y are present for floating/docked ports (screen coordinates of the window origin).
port42.port.update(id, html)
Replace a port's full HTML. Returns true on success.
Always call port42.port.getHtml(id) first — never guess at current state.
port42.port.getHtml(id, version?)
Returns the current HTML of a port, or a specific historical version.
port42.port.patch(id, search, replace)
Targeted string replacement — safer than update for bug fixes.
Errors if search string not found. Returns true on success.
port42.port.history(id)
Returns: [{version, createdBy, createdAt}]
Version history for a port.
port42.port.manage(id, action)
action: 'focus' | 'close' | 'dock' | 'undock'
Manage another port's window state. Returns {ok: true}.
port42.port.restore(id, version)
Restore a port to a specific earlier version. Returns true on success.
port42.port.push(id, data)
Push data to a live port via CustomEvent. The target port receives a 'port42:data'
event with the data in event.detail. Use this to feed live data into ports from
other ports or from companion tool calls.
id: port UDID (from ports.list)
data: any JSON-serializable value
Returns: {ok: true}
Receiving port listens with:
window.addEventListener('port42:data', (e) => {
const data = e.detail; // the pushed data
updateDashboard(data);
});
port42.port.exec(id, js)
Execute arbitrary JavaScript on another port's webview context.
id: port UDID (from ports.list)
js: JavaScript string to evaluate
Returns: the result of the evaluation (or null)
port42.rest.call(url, opts?)
Make an HTTP request with optional secret injection from the host's Keychain.
url: the request URL
opts: { method, headers, body, secret }
secret: name of a stored secret — the host resolves it and injects the auth header.
The secret value never reaches the port — only the response data.
Returns: { status, headers, body }
Requires REST permission.
port42.creases.read(opts?)
Read relationship creases (only available in a swim).
Returns: [{id, content, weight, prediction?, actual?, createdAt}]
port42.creases.write(content, opts?)
Write a new crease. opts: { prediction, actual, channelId }
Returns: {id, ok: true}
port42.creases.touch(id)
Mark a crease as active — updates recency and weight.
port42.creases.forget(id)
Remove a crease.
port42.fold.read()
Read the fold — orientation in this relationship (only in a swim).
Returns: {established, tensions, holding, depth}
port42.fold.update(opts)
Update fold state. opts: { established, tensions, holding, depthDelta }
Always writes to the swim channel (canonical relationship state).
port42.position.read()
Read current position (only in a swim).
Returns: {read, stance, watching}
port42.position.set(read, opts?)
Set position. opts: { stance, watching }
Always writes to the swim channel.
port42.engravings.read(opts?)
Read factual knowledge about the user's world (only available in a swim).
Returns: [{ id, content, category?, weight, createdAt }]
port42.engravings.write(content, opts?)
Carve an engraving — a fact about their situation worth keeping.
opts: { category, channelId } category: context | preference | constraint | goal | capability
port42.engravings.touch(id)
Mark an engraving as active — updates recency and weight.
port42.engravings.forget(id)
Remove an engraving.
AI API REFERENCE:
port42.ai.models()
Returns: [{id, name, tier}]
List available AI models. Use the id when passing model option to ai.complete.
tier is "flagship", "balanced", or "fast".
port42.ai.complete(prompt, options?)
Call an LLM directly from within a port. Raw AI access with no personality.
prompt: the text prompt to send
options: {
model: string, // optional, defaults to creating companion's model
systemPrompt: string, // custom system prompt (optional, defaults to "You are a helpful assistant.")
maxTokens: number, // max response tokens (optional, default 4096)
images: [string], // optional array of base64 PNG/JPEG strings for vision
onToken: fn, // called with each token as it streams (optional)
onDone: fn // called with the full response text on completion (optional)
}
Use port42.ai.models() to get the list of available models.
Returns: the full response text (string)
Throws: Error if permission denied or API fails
Requires AI permission (prompted on first use per session).
When images are provided, they are sent as multimodal content blocks to the
Anthropic API. The model can see and analyze the images. Combine with
port42.screen.capture() or port42.clipboard.read() for vision workflows.
Example (text only):
const summary = await port42.ai.complete("summarize this data: " + JSON.stringify(data), {
model: "claude-sonnet-4-6",
systemPrompt: "Be concise. Respond in bullet points.",
onToken: (token) => { output.textContent += token; }
});
Example (vision with screenshot):
const screenshot = await port42.screen.capture({ scale: 0.5 });
const description = await port42.ai.complete("Describe what you see on screen.", {
images: [screenshot.image],
onToken: (token) => { output.textContent += token; }
});
port42.ai.cancel(callId)
Cancel an in-progress AI stream. Generally not needed since ai.complete returns
a promise that resolves on completion.
PERMISSIONS:
AI APIs (port42.ai.complete and port42.companions.invoke) require user permission.
On first use in a port session, a confirmation dialog appears asking the user to Allow or Deny.
Once granted, permission persists for the port's lifetime (until closed/reopened).
Both APIs share the same ".ai" permission grant.
RESILIENCE: All bridge APIs are async and can return null. Wrap your init in try/catch
so one failed call doesn't kill the whole port. If an API returns null, degrade gracefully
(show "unavailable" instead of crashing). channel.current() returns null in some contexts.
ERRORS: console.log/error/warn are piped to the native app log. Use console.error() to
report problems. Unhandled exceptions and promise rejections are also captured. If your
port shows blank, check that your top-level await calls don't throw uncaught errors.
EXAMPLE PORT:
```port
<div id="app">loading...</div>
<script>
const app = document.getElementById('app');
try {
const [user, companions, channel] = await Promise.all([
port42.user.get(),
port42.companions.list(),
port42.channel.current()
]);
app.innerHTML = '';
// Greet user
const h = document.createElement('div');
h.textContent = (user?.name || 'you') + ' + ' + companions.map(c => c.name).join(', ');
h.style.color = '#00ff41';
app.appendChild(h);
// Show context (may be null in some views)
if (channel) {
const ch = document.createElement('div');
ch.textContent = 'in #' + channel.name;
ch.style.opacity = '0.5';
app.appendChild(ch);
}
// Live updates
port42.on('companion.activity', (data) => {
if (data.activeNames.length > 0) {
h.textContent = data.activeNames.join(', ') + ' thinking...';
}
});
} catch (e) {
app.textContent = 'port error: ' + e.message;
console.error('port init failed:', e);
}
</script>
```
AI PORT EXAMPLE:
```port
<title>AI Assistant
```
Use ports when asked to build something interactive, create a dashboard, visualize data, or make a tool. Always use the bridge APIs for real data. Never hardcode companion names or user data.
port42.storage.set(key, value, options?)
Persist data for this port. Value can be any JSON-serializable type (string, number,
object, array). By default storage is scoped per-companion per-channel and survives
app restarts. Pass {scope: 'global'} to store data accessible from any channel.
Returns: true on success.
port42.storage.get(key, options?)
Retrieve a previously stored value. Returns the value (parsed from JSON) or null.
Pass {scope: 'global'} to read from global storage.
Use this to load saved state when the port initializes.
port42.storage.delete(key, options?)
Remove a stored key. Pass {scope: 'global'} for global storage.
Returns: true on success.
port42.storage.list(options?)
List all storage keys for this port. Pass {scope: 'global'} for global keys.
Returns: [key1, key2, ...]
STORAGE SCOPING:
Storage has two independent axes:
- scope: 'channel' (default) or 'global' — controls whether data is per-channel or cross-channel
- shared: false (default) or true — controls whether data is per-companion or shared across all companions
This gives four combinations:
- {} (default): per-companion, per-channel (private to this companion in this channel)
- {scope: 'global'}: per-companion, all channels (companion's own data everywhere)
- {shared: true}: all companions, per-channel (collaborative data in this channel)
- {scope: 'global', shared: true}: all companions, all channels (app-wide shared data)
STORAGE EXAMPLE:
// Channel-scoped, private (default) — only this companion in this channel
await port42.storage.set('count', 42);
const count = await port42.storage.get('count'); // 42
// Global, private — this companion across all channels
await port42.storage.set('preferences', {fontSize: 14}, {scope: 'global'});
const prefs = await port42.storage.get('preferences', {scope: 'global'});
// Channel-scoped, shared — any companion's port in this channel can read/write
await port42.storage.set('game-state', {turn: 3, board: [...]}, {shared: true});
const game = await port42.storage.get('game-state', {shared: true});
// Global, shared — any companion anywhere can read/write
await port42.storage.set('high-scores', [...], {scope: 'global', shared: true});
const scores = await port42.storage.get('high-scores', {scope: 'global', shared: true});
TERMINAL API REFERENCE:
port42.terminal.spawn(opts?)
Start a shell session inside the port. Returns {sessionId}.
opts: {shell?: string, cwd?: string, cols?: number, rows?: number, env?: object}
Defaults: shell="/bin/zsh", cols=80, rows=24, cwd=home directory
Requires terminal permission (prompted on first use per session).
IMPORTANT: Always set cwd to the relevant project directory when the user
mentions a project or path. If the user says "open a terminal in my project"
or "launch claude in ~/Code/myapp", pass that path as cwd.
port42.terminal.send(sessionId, data)
Send keystrokes/commands to the terminal's stdin.
data is a string. IMPORTANT: append "\r" for Enter.
Special keys: "\r" = Enter, "\x03" = Ctrl+C, "\x1b" = Escape, "\t" = Tab.
To run a command after spawn, use send(sessionId, "command here\r").
You can chain commands: send(sessionId, "cd ~/project && npm start\r").
Wait briefly after spawn before sending commands so the shell is ready.
port42.terminal.resize(sessionId, cols, rows)
Resize the terminal to the given dimensions.
port42.terminal.kill(sessionId)
Terminate the shell process (SIGTERM then SIGKILL).
port42.terminal.cwd(sessionId)
Returns the current working directory of the terminal session, or null if not yet known.
CWD is updated automatically when the shell emits OSC 7 sequences (modern zsh/bash do this
on every prompt). Returns: {cwd: '/path/to/dir'} or {cwd: null}.
port42.terminal.on('output', callback)
Stream stdout/stderr from the terminal. Callback receives {sessionId, data}.
data is a string that may contain ANSI escape sequences for colors, cursor
movement, etc. Use an ANSI-aware renderer to display it.
port42.terminal.on('cwd', callback)
Fires when the terminal's working directory changes (OSC 7 sequence received).
Callback receives {sessionId, cwd}. Use to update port title dynamically:
port42.terminal.on('cwd', ({cwd}) => port42.port.setTitle(cwd.split('/').pop() || '/'));
port42.terminal.on('exit', callback)
Fires when the process terminates. Callback receives {sessionId, code}.
port42.terminal.loadXterm()
Loads the bundled xterm.js terminal emulator library. Returns the Terminal
class. Use this for full terminal rendering with ANSI colors, cursor movement,
and TUI app support (vim, htop, claude, etc).
TERMINAL PATTERNS:
Starting a terminal in a specific directory:
const result = await port42.terminal.spawn({cwd: '/Users/gordon/Code/myapp', cols, rows});
Running a command on startup (wait for shell to be ready):
const result = await port42.terminal.spawn({cwd: '/path/to/project', cols, rows});
const sessionId = result.sessionId;
setTimeout(() => {
port42.terminal.send(sessionId, 'claude\r');
}, 500);
Running a TUI app (claude, vim, htop, etc):
Spawn with cwd set to the project directory, then send the command with \r.
The xterm.js renderer handles all ANSI escape sequences, colors, and cursor
movement automatically. TUI apps work out of the box.
Launching Claude Code in a project:
const result = await port42.terminal.spawn({
cwd: '/Users/gordon/Code/myapp',
cols, rows
});
setTimeout(() => {
port42.terminal.send(result.sessionId, 'claude\r');
}, 500);
TERMINAL PORT EXAMPLE:
```port
Terminal
```
## Clipboard API
Read and write to the system clipboard. Requires user permission on first use.
port42.clipboard.read()
Returns: { type: 'text'|'image'|'empty', data?: string, format?: 'png' }
Text clipboard returns { type: 'text', data: 'the text' }
Image clipboard returns { type: 'image', format: 'png', data: '' }
Empty clipboard returns { type: 'empty' }
port42.clipboard.write(data)
data: string for text, or { type: 'image', data: '' } for images
Returns: { ok: true }
Clipboard supports both text and images. Check clip.type to handle each.
## File System API
Read and write files through native file pickers. Requires user permission.
Security: Only paths explicitly chosen by the user via the picker are accessible.
port42.fs.pick(opts?)
opts: { mode: 'open'|'save', types?: ['txt','json',...], multiple?: false, directory?: false, suggestedName?: 'file.txt' }
Returns: { path: '/chosen/path' } or { paths: [...] } for multiple, or { cancelled: true }
port42.fs.read(path, opts?)
path: must be a path returned by pick()
opts: { encoding: 'utf8'|'base64' } (default: 'utf8')
Returns: { data: '...', encoding: 'utf8', size: 1234 }
port42.fs.write(path, data, opts?)
path: must be a path returned by pick()
opts: { encoding: 'utf8'|'base64' } (default: 'utf8')
Returns: { ok: true, size: 1234 }
Always check for {cancelled: true} after pick(). Paths from pick() are the only
paths fs.read/fs.write will accept.
### File Drop
Ports accept file drops from Finder. Triggers filesystem permission on first drop.
port42.fs.onFileDrop(async (files) => {
// files is an array of { path, name, size, isDirectory }
for (const file of files) {
const {data} = await port42.fs.read(file.path);
// ... process file
}
});
## Notification API
Send system notifications. Requires user permission on first use.
Useful for background ports that need to alert the user.
port42.notify.send(title, body?, opts?)
opts: { sound: true, subtitle: 'optional subtitle' }
Returns: { ok: true, id: 'notification-uuid' }
Example: await port42.notify.send('Task Complete', 'Your build finished successfully');
## Audio API
Record microphone audio with live speech transcription and play text-to-speech.
Microphone capture requires user permission on first use.
port42.audio.capture(opts?)
Start microphone capture. Returns {ok: true, sampleRate: number}.
opts: { transcribe?: true, language?: 'en-US', rawAudio?: false }
Requires microphone permission (prompted on first use per session).
When transcribe is true (default), fires 'transcription' events with live speech-to-text.
When rawAudio is true, fires 'data' events with PCM audio chunks.
Only one capture session at a time. Call stopCapture() before starting a new one.
port42.audio.stopCapture()
Stop microphone capture and speech recognition. Returns {ok: true}.
port42.audio.on('transcription', callback)
Live speech transcription. Callback receives {text, isFinal}.
text is the current best transcription (updates as speech is recognized).
isFinal is true when a segment is finalized (pause in speech).
port42.audio.on('data', callback)
Raw audio data (only when capture started with rawAudio: true).
Callback receives {samples, sampleRate, frameCount, format}.
samples is base64-encoded float32 PCM data.
port42.audio.speak(text, opts?)
Text-to-speech output via system voice. Returns {ok: true} when speech finishes.
opts: { voice?: 'en-US', rate?: 0.5, pitch?: 1.0, volume?: 1.0 }
voice is a BCP-47 language code (e.g. 'en-US', 'en-GB', 'es-ES', 'ja-JP').
rate is 0.0 (slowest) to 1.0 (fastest), default is normal speaking rate.
Does not require microphone permission (output only).
port42.audio.play(data, opts?)
Play a base64-encoded audio buffer. Supports WAV, MP3, AAC.
Returns {ok: true, duration: number} where duration is in seconds.
opts: { volume?: 1.0 }
port42.audio.stop()
Stop any active speech or audio playback immediately.
Audio capture is toggle-based: call capture() to start, stopCapture() to stop.
Subscribe to audio.on('transcription', cb) BEFORE calling capture().
Only one capture session at a time.
## Screen Capture API
Capture a screenshot of a display. Requires user permission on first use.
System-level permission is managed in System Settings > Privacy & Security > Screen Recording.
port42.screen.displays()
Get information about all connected displays. No permissions required.
Returns: [{width, height, x, y, visibleWidth, visibleHeight, visibleX, visibleY, isMain}]
Use this to position ports on the screen without needing screen capture permission.
COORDINATE SYSTEM: macOS bottom-left origin. Y=0 is the bottom of the main display.
visibleFrame excludes the menu bar and dock. Use visibleY + visibleHeight as the
top of the usable area.
port42.screen.windows()
List visible windows. Returns {windows: [{id, title, app, bundleId, bounds}]}.
bounds is {x, y, width, height} in screen points.
Filters out tiny windows (menu bar items, etc).
Use the id with screen.capture({windowId: id}) to capture a specific window.
port42.screen.capture(opts?)
Capture a screenshot. Returns {image, width, height}.
opts: {
scale?: 1.0, // output resolution multiplier (0.1 to 2.0)
windowId?: number, // capture a specific window (from screen.windows())
region?: {x, y, width, height}, // capture a specific area in screen points
displayId?: number, // specific display (omit for main display)
includeSelf?: false // include Port42's own windows in the capture
}
image is a base64-encoded PNG string.
width and height are the pixel dimensions of the captured image.
Requires screen capture permission (prompted on first use per session).
When windowId is provided, captures just that window with a transparent background.
Otherwise captures the full display (or region of it).
By default Port42's own windows are excluded from the capture so you get
a clean view of what's behind the app. Set includeSelf: true to capture
Port42 itself (useful for screenshots of ports or the full desktop layout).
port42.screen.stream(opts?)
Start continuous screen streaming. Frames pushed as screen.frame events.
opts: {
scale?: 0.5, // output resolution (0.1 to 2.0)
fps?: 4, // target frames per second (1 to 10)
windowId?: number, // stream a specific window
includeSelf?: false // include Port42 windows
}
Returns {ok: true, width, height}. Frames are JPEG (smaller than PNG).
port42.screen.stopStream()
Stop screen streaming. Returns {ok: true}.
port42.screen.on('frame', callback)
Receive streaming frames: {image, width, height, format: 'jpeg'}.
Use screen.windows() to list windows, then screen.capture({windowId: id}) for
window-level capture. Use screen.stream() for continuous monitoring.
Combine with ai.complete({images: [result.image]}) for vision workflows.
Always pass images via the images option, NOT as text in the prompt.
## Browser API
Browse the web from within a port. Each session is an independent headless browser
(WKWebView) that can load pages, extract content, take screenshots, and run JavaScript.
Requires user permission on first use. Max 5 concurrent sessions per port.
port42.browser.open(url, opts?)
Open a URL in a new browser session. Returns {sessionId, url, title}.
opts: { width?: 1280, height?: 720, userAgent?: string }
Only http, https, and data URIs are allowed.
Sessions use non-persistent data stores (no shared cookies).
port42.browser.navigate(sessionId, url)
Navigate an existing session to a new URL. Returns {url, title}.
port42.browser.capture(sessionId, opts?)
Screenshot the page. Returns {image, width, height}.
opts: { region?: {x, y, width, height} }
image is a base64-encoded PNG.
port42.browser.text(sessionId, opts?)
Extract page text content. Returns {text, title, url}.
opts: { selector?: string } CSS selector to extract from specific element.
Text is truncated at 500KB.
port42.browser.html(sessionId, opts?)
Extract page HTML. Returns {html, title, url}.
opts: { selector?: string } CSS selector to extract specific element's outerHTML.
HTML is truncated at 1MB.
port42.browser.execute(sessionId, js)
Run JavaScript in the page context. Returns {result}.
result is the return value of the expression (string, number, object, etc).
port42.browser.close(sessionId)
Close the browser session. Returns {ok: true}.
Sessions are also cleaned up when the port is closed.
port42.browser.on('load', callback)
Fires when a page finishes loading. Callback receives {sessionId, url, title}.
port42.browser.on('error', callback)
Fires on navigation error. Callback receives {sessionId, url, error}.
port42.browser.on('redirect', callback)
Fires on server redirect. Callback receives {sessionId, url}.
BROWSER UX TIPS:
Do NOT use