mirror of
https://github.com/stablyai/orca.git
synced 2026-11-16 10:58:10 +00:00
* feat(plugins): add orca.document.session() for custom editors One call replaces the document sync every editor rebuilds: decode/encode (plain text by default), optional merge, debounce. One edit in flight with later changes coalesced; the baseline moves only on accept; a refused edit keeps the draft and rejects flush(); own accepted edits never reach onReplace; a conflict merges once against the last accepted value and resubmits, or keeps the draft without merge. The session answers editor.flush itself and resolves after hello and the first document. The --template editor now uses it. Docs and typings state the session and the undo model (the editor owns undo). * fix(plugins): let the outside document win a session conflict without merge Agents write files while people edit them, so keeping the draft lost the agent's write on the next keystroke. Without merge the session now drops the draft, fires onReplace with the outside value and rejects flush() with conflict; editors that want both sides pass merge. * fix(plugins): serialize session edits through saves and settle before answering - One edit in flight at all times, saves included; editor.flush is answered only once every change is accepted or refused with nothing newer to send. - The editor host commits a held edit when a save starts and admits edits during the save at once, so waiting fits the 1 s deadline. - A change generation replaces identity checks, and sent bytes are snapshotted, so a reused buffer is never mistaken for an accepted edit. - A waiting flush keeps its conflict rejection when the outside document wins, and nothing merges or sends after dispose. * test(plugins): read session test edits through typed helpers * fix(plugins): drain session flushes, reject dropped drafts, snapshot the baseline - flush() keeps going until no change made during it is left unsent. - A waiting flush rejects with conflict whenever the outside document replaced a draft, newer ones included. - The accepted baseline is decoded from the sent snapshot, so a reused value buffer cannot change merge's base. * test(plugins): name the session test option and message types
319 lines
16 KiB
TypeScript
319 lines
16 KiB
TypeScript
import { EDITOR_METHODS, FRAME_EVENTS, type PluginFrameTheme } from './plugin-frame-bridge'
|
|
import { PLUGIN_ERROR_CODES, PLUGIN_PROTOCOL_VERSION } from './plugin-protocol'
|
|
import { PLUGIN_DECLARATIVE_POST_GLOBAL, PLUGIN_FRAME_TRANSPORT_GLOBAL } from './plugin-frame-guest'
|
|
import { PLUGIN_HOST_API_MAJOR } from '../workers/plugin-host-api-major'
|
|
import { PLUGIN_FRAME_FACADES_SCRIPT } from './plugin-panel-shell-facades'
|
|
import { PLUGIN_FRAME_DOCUMENT_SCRIPT } from './plugin-panel-shell-document'
|
|
import {
|
|
PLUGIN_FRAME_USER_METHODS,
|
|
pluginFrameMethodsFor,
|
|
pluginHostApiMinorFor
|
|
} from '../workers/plugin-host-api'
|
|
|
|
/** Prepend CSP before any untrusted panel HTML: opaque origins alone still permit CORS fetch/beacons. Parsed CSP survives
|
|
* DOM removal and later CSP can only tighten it. Open head/html exposes design tokens to plugin CSS.
|
|
* Shared Electron-free builder keeps desktop and serve wrapping identical. */
|
|
|
|
// Residuals below apply only to the srcdoc iframe that browser clients (serve/web) still use;
|
|
// desktop frames are isolated guests (buildPluginGuestShellHtml, plugin-isolated-frames.md).
|
|
// Residual shared with doc preview: Electron 43 resolves `<link rel="dns-prefetch">` outside CSP
|
|
// and session hooks, so DNS labels can still leak.
|
|
// Residual WebRTC channel: the prelude removes RTCPeerConnection from the panel window only. A
|
|
// child `<iframe srcdoc>` (or `javascript:` src) the panel adds is a fresh realm: srcdoc commits
|
|
// without will-frame-navigate, so the frame guard never sees it, and Electron 43 has no CSP
|
|
// `webrtc` directive or per-frame switch. That frame can open TURN-over-TCP to any host, which
|
|
// `disable_non_proxied_udp` allows (plugin-panel-webrtc.electron.test.ts). Direct child-window
|
|
// access is already refused as a sandbox violation.
|
|
export const PLUGIN_PANEL_CSP =
|
|
"default-src 'none'; connect-src 'none'; script-src 'unsafe-inline'; " +
|
|
"style-src 'unsafe-inline'; img-src data:; font-src data:; base-uri 'none'; form-action 'none'"
|
|
|
|
/** Renderer fills theme/tokens before mounting srcdoc; main cannot know the active presentation values. */
|
|
export const PANEL_SHELL_TOKENS_PLACEHOLDER = '/*__ORCA_PANEL_TOKENS__*/'
|
|
export const PANEL_SHELL_COLOR_SCHEME_PLACEHOLDER = '__ORCA_COLOR_SCHEME__'
|
|
const PANEL_SHELL_TOKENS_STYLE_ID = 'orca-design-tokens'
|
|
|
|
export type PluginFrameSurface = 'panel' | 'editor'
|
|
|
|
/** How the frame script reaches the host: `window.parent` (srcdoc iframe) or the guest preload;
|
|
* a declarative host page also gets Orca's boot script a way to post `ui.*` events. */
|
|
type FrameTransport = 'parent' | 'guest' | 'declarative-guest'
|
|
|
|
/** The frozen `window.orca` every frame gets before plugin code runs: the public frame API.
|
|
* The envelope underneath is internal. `api` and `has` start from this host's table, so they work
|
|
* synchronously; `hello` confirms them and carries the theme. */
|
|
function frameApiScript(surface: PluginFrameSurface, transport: FrameTransport): string {
|
|
const methods = pluginFrameMethodsFor(surface, transport !== 'parent')
|
|
const config = JSON.stringify({
|
|
protocol: PLUGIN_PROTOCOL_VERSION,
|
|
surface,
|
|
api: { major: PLUGIN_HOST_API_MAJOR, minor: pluginHostApiMinorFor(methods) },
|
|
methods,
|
|
codes: PLUGIN_ERROR_CODES,
|
|
events: FRAME_EVENTS,
|
|
editor: EDITOR_METHODS,
|
|
// Iframes get no user-gesture API at all: Orca cannot verify their gestures. A components
|
|
// panel's hidden guest never has activation; its `orca` module routes these through the
|
|
// press grant with host.call instead.
|
|
user: transport === 'guest' ? PLUGIN_FRAME_USER_METHODS : null,
|
|
tokensStyleId: PANEL_SHELL_TOKENS_STYLE_ID,
|
|
maxPending: 256,
|
|
deadlineMs: 120_000,
|
|
// A save dialog waits on the person, so gesture methods get a long deadline.
|
|
userDeadlineMs: 30 * 60_000,
|
|
userMethodList: Object.values(PLUGIN_FRAME_USER_METHODS),
|
|
transportGlobal: transport === 'parent' ? null : PLUGIN_FRAME_TRANSPORT_GLOBAL,
|
|
declarativePost: transport === 'declarative-guest' ? PLUGIN_DECLARATIVE_POST_GLOBAL : null
|
|
}).replaceAll('<', '\\u003c')
|
|
return `;(function (C) {
|
|
var E = C.events
|
|
var nextId = 0
|
|
var pending = new Map()
|
|
var listeners = new Map()
|
|
var api = Object.freeze(C.api)
|
|
var methods = C.methods.slice()
|
|
var latest = null
|
|
var waiting = []
|
|
var helloSeen = false
|
|
var starting = []
|
|
var locale = null
|
|
var send = null
|
|
if (C.transportGlobal) {
|
|
// Why one-shot: the guest preload hands this over before any plugin script runs.
|
|
var transport = null
|
|
try { transport = window[C.transportGlobal]; delete window[C.transportGlobal] } catch (_) {}
|
|
if (!transport || typeof transport.send !== 'function') return
|
|
send = function (message) { transport.send(message) }
|
|
transport.subscribe(receive)
|
|
} else {
|
|
var parent = window.parent
|
|
send = function (message) { parent.postMessage(message, '*') }
|
|
window.addEventListener('message', function (event) {
|
|
if (event.source === parent) receive(event.data)
|
|
})
|
|
}
|
|
function post(message) { send(Object.assign({ orca: C.protocol }, message)) }
|
|
function failure(error) {
|
|
var e = new Error(String(error && error.message || 'host call failed'))
|
|
e.code = C.codes.indexOf(error && error.code) >= 0 ? error.code : 'action_failed'
|
|
e.retryable = Boolean(error && error.retryable)
|
|
if (error && typeof error.retryAfterMs === 'number') e.retryAfterMs = error.retryAfterMs
|
|
return e
|
|
}
|
|
function emit(name, payload) {
|
|
var set = listeners.get(name)
|
|
return set ? Array.from(set).map(function (fn) {
|
|
try { return Promise.resolve(fn(payload)) } catch (e) { return Promise.reject(e) }
|
|
}) : []
|
|
}
|
|
function on(name, fn) {
|
|
if (typeof fn !== 'function') throw new TypeError('orca.on needs a handler')
|
|
var set = listeners.get(name) || new Set()
|
|
listeners.set(name, set)
|
|
var entry = function (payload) { return fn(payload) }
|
|
set.add(entry)
|
|
return Object.freeze({ dispose: function () { set.delete(entry) } })
|
|
}
|
|
function call(method, params, options) {
|
|
var signal = options && options.signal
|
|
if (signal && signal.aborted) return Promise.reject(failure({ code: 'cancelled', message: 'cancelled' }))
|
|
// Bounded and deadlined: a lost answer must never leave a call (or the map) growing forever.
|
|
if (pending.size >= C.maxPending) return Promise.reject(failure({ code: 'rate_limited', message: 'too many calls in flight', retryable: true }))
|
|
var id = nextId++
|
|
var deadlineMs = C.userMethodList.indexOf(String(method)) >= 0 ? C.userDeadlineMs : C.deadlineMs
|
|
return new Promise(function (resolve, reject) {
|
|
var timer = setTimeout(function () {
|
|
if (!pending.delete(id)) return
|
|
if (signal) signal.removeEventListener('abort', abort)
|
|
post({ kind: 'cancel', id: id })
|
|
reject(failure({ code: 'timeout', message: 'host did not answer', retryable: true }))
|
|
}, deadlineMs)
|
|
function abort() {
|
|
clearTimeout(timer)
|
|
pending.delete(id)
|
|
post({ kind: 'cancel', id: id })
|
|
reject(failure({ code: 'cancelled', message: 'cancelled' }))
|
|
}
|
|
if (signal) signal.addEventListener('abort', abort, { once: true })
|
|
pending.set(id, function (message) {
|
|
clearTimeout(timer)
|
|
if (signal) signal.removeEventListener('abort', abort)
|
|
if (message.error) reject(failure(message.error))
|
|
else resolve(message.result)
|
|
})
|
|
post({ kind: 'req', id: id, method: String(method), params: params })
|
|
})
|
|
}
|
|
// Why checked here too: fail fast in the frame; the host re-checks before anything runs.
|
|
function userCall(method, params) {
|
|
var activation = navigator.userActivation
|
|
if (!activation || !activation.isActive) {
|
|
return Promise.reject(failure({ code: 'not_permitted', message: method + ' needs a click or key press in the frame' }))
|
|
}
|
|
return call(method, params)
|
|
}
|
|
function applyTheme(theme) {
|
|
if (!theme || (theme.colorScheme !== 'light' && theme.colorScheme !== 'dark')) return
|
|
document.documentElement.classList.remove('light', 'dark')
|
|
document.documentElement.classList.add(theme.colorScheme)
|
|
var tokens = document.getElementById(C.tokensStyleId)
|
|
if (tokens && typeof theme.tokens === 'string') tokens.textContent = ':root{' + theme.tokens.replace(/[{}<>]/g, '') + '}'
|
|
emit('theme', { colorScheme: theme.colorScheme })
|
|
}
|
|
function receive(m) {
|
|
if (!m || m.orca !== C.protocol) return
|
|
if (m.kind === 'res') {
|
|
var settle = pending.get(m.id)
|
|
if (settle) { pending.delete(m.id); settle(m) }
|
|
} else if (m.kind === 'evt' && m.event === E.ping) {
|
|
post({ kind: 'evt', event: E.pong, payload: m.payload })
|
|
} else if (m.kind === 'evt' && m.event === E.hello && m.payload) {
|
|
if (m.payload.api) api = Object.freeze({ major: m.payload.api.major, minor: m.payload.api.minor })
|
|
if (Array.isArray(m.payload.methods)) methods = m.payload.methods.slice()
|
|
if (typeof m.payload.locale === 'string') locale = m.payload.locale.slice(0, 64)
|
|
applyTheme(m.payload.theme)
|
|
helloSeen = true
|
|
start()
|
|
} else if (m.kind === 'evt' && m.event === E.theme) {
|
|
applyTheme(m.payload)
|
|
} else if (m.kind === 'evt' && m.event === E.push) {
|
|
receivePush(m.payload)
|
|
} else if (m.kind === 'evt' && m.event === E.editorDocument && C.surface === 'editor') {
|
|
latest = Object.freeze(m.payload)
|
|
waiting.splice(0).forEach(function (resolve) { resolve(latest) })
|
|
start()
|
|
emit(E.editorDocument, latest)
|
|
} else if (m.kind === 'evt') {
|
|
emit(m.event, m.payload)
|
|
} else if (m.kind === 'req') {
|
|
Promise.all(emit(m.method, m.params)).then(function () {
|
|
post({ kind: 'res', id: m.id, result: null })
|
|
}, function (e) {
|
|
post({ kind: 'res', id: m.id, error: { code: 'action_failed', message: String(e && e.message || e), retryable: false } })
|
|
})
|
|
}
|
|
}
|
|
var orca = {
|
|
host: Object.freeze({
|
|
call: call,
|
|
has: function (method) { return methods.indexOf(method) >= 0 }
|
|
}),
|
|
on: on
|
|
}
|
|
${PLUGIN_FRAME_FACADES_SCRIPT} if (C.user) {
|
|
orca.shell = Object.freeze({
|
|
openExternal: function (url) { return userCall(C.user.openExternal, { url: String(url) }) }
|
|
})
|
|
orca.files = Object.freeze({
|
|
saveAs: function (options) {
|
|
var o = options || {}
|
|
var data = ArrayBuffer.isView(o.data)
|
|
? o.data.buffer.slice(o.data.byteOffset, o.data.byteOffset + o.data.byteLength)
|
|
: o.data
|
|
var params = { data: data }
|
|
if (o.suggestedName !== undefined) params.suggestedName = o.suggestedName
|
|
if (o.mimeType !== undefined) params.mimeType = o.mimeType
|
|
return userCall(C.user.saveAs, params).then(function (result) {
|
|
return { status: result && result.status === 'saved' ? 'saved' : 'cancelled' }
|
|
})
|
|
}
|
|
})
|
|
}
|
|
Object.defineProperty(orca, 'api', { get: function () { return api }, enumerable: true })
|
|
Object.defineProperty(orca, 'locale', {
|
|
get: function () { return locale || navigator.language }, enumerable: true
|
|
})
|
|
${PLUGIN_FRAME_DOCUMENT_SCRIPT} if (C.surface === 'editor') {
|
|
window.addEventListener('keydown', function (event) {
|
|
if (event.repeat || !(event.metaKey || event.ctrlKey)) return
|
|
post({ kind: 'evt', event: E.editorKeydown, payload: {
|
|
key: String(event.key).slice(0, 64), code: String(event.code).slice(0, 64),
|
|
metaKey: event.metaKey, ctrlKey: event.ctrlKey, altKey: event.altKey, shiftKey: event.shiftKey
|
|
} })
|
|
}, true)
|
|
}
|
|
Object.defineProperty(window, 'orca', { value: Object.freeze(orca), writable: false, configurable: false })
|
|
if (C.declarativePost) {
|
|
// One-shot for Orca's boot script, which deletes it before importing the plugin module.
|
|
Object.defineProperty(window, C.declarativePost, { configurable: true, value: function (event, payload) {
|
|
post({ kind: 'evt', event: String(event), payload: payload })
|
|
} })
|
|
}
|
|
post({ kind: 'evt', event: E.ready, payload: { protocol: C.protocol } })
|
|
})(${config})
|
|
`
|
|
}
|
|
|
|
export function buildPluginPanelShellHtml(
|
|
pluginHtml: string,
|
|
surface: PluginFrameSurface = 'panel'
|
|
): string {
|
|
const prelude =
|
|
'<!doctype html>\n' +
|
|
`<html class="${PANEL_SHELL_COLOR_SCHEME_PLACEHOLDER}">\n` +
|
|
'<head>\n' +
|
|
'<meta charset="utf-8">\n' +
|
|
`<meta http-equiv="Content-Security-Policy" content="${PLUGIN_PANEL_CSP}">\n` +
|
|
`<style id="${PANEL_SHELL_TOKENS_STYLE_ID}">:root{${PANEL_SHELL_TOKENS_PLACEHOLDER}}</style>\n` +
|
|
// Why: matching the host frame's inherited color-scheme avoids Chromium's opaque mismatch backdrop.
|
|
'<style>:where(html.light){color-scheme:light}:where(html.dark){color-scheme:dark}</style>\n' +
|
|
'<script>\n' +
|
|
"'use strict'\n" +
|
|
'// Host policy: plugin panels are documents, never browsing contexts.\n' +
|
|
"if (window.navigation && typeof window.navigation.addEventListener === 'function') {\n" +
|
|
" window.navigation.addEventListener('navigate', function (event) {\n" +
|
|
' if (event.cancelable) event.preventDefault()\n' +
|
|
' })\n' +
|
|
'}\n' +
|
|
'// Why: CSP has no WebRTC directive, so a peer connection would be an open outbound channel.\n' +
|
|
"['RTCPeerConnection', 'webkitRTCPeerConnection'].forEach(function (name) {\n" +
|
|
' try { Object.defineProperty(window, name, { value: undefined, writable: false, configurable: false }) }\n' +
|
|
' catch (_) {}\n' +
|
|
'})\n' +
|
|
"try { Object.defineProperty(window, 'open', { value: function () { return null }, writable: false, configurable: false }) }\n" +
|
|
'catch (_) { try { window.open = function () { return null } } catch (_) {} }\n' +
|
|
"window.addEventListener('click', function (event) {\n" +
|
|
' var node = event.target\n' +
|
|
' while (node && node !== document) {\n' +
|
|
" if (node.nodeType === 1 && node.tagName === 'A' && node.hasAttribute('href')) {\n" +
|
|
' event.preventDefault()\n' +
|
|
' event.stopImmediatePropagation()\n' +
|
|
' return\n' +
|
|
' }\n' +
|
|
' node = node.parentNode\n' +
|
|
' }\n' +
|
|
'}, true)\n' +
|
|
"window.addEventListener('submit', function (event) {\n" +
|
|
' event.preventDefault()\n' +
|
|
' event.stopImmediatePropagation()\n' +
|
|
'}, true)\n'
|
|
return `${prelude}${frameApiScript(surface, 'parent')}</script>\n</head>\n${pluginHtml}`
|
|
}
|
|
|
|
/** CSP header for every response of an isolated guest; the session, not CSP, denies the network. */
|
|
export const PLUGIN_GUEST_CSP =
|
|
"default-src 'self'; script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval'; " +
|
|
"style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; " +
|
|
"media-src 'self' data: blob:; connect-src 'self' data: blob:; worker-src 'self' blob:; " +
|
|
"frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'"
|
|
|
|
/** An HTML document served to an isolated guest. Navigation, popups and WebRTC are fenced by
|
|
* main per guest, so only the frame API is injected; the theme arrives with `hello`. */
|
|
export function buildPluginGuestShellHtml(
|
|
pluginHtml: string,
|
|
surface: PluginFrameSurface = 'panel',
|
|
options: { declarative?: boolean; theme?: PluginFrameTheme | null } = {}
|
|
): string {
|
|
const transport = options.declarative ? 'declarative-guest' : 'guest'
|
|
const theme = options.theme
|
|
// Why baked in: plugins that read tokens at boot, and the first paint, must not wait for `hello`.
|
|
const scheme =
|
|
theme?.colorScheme === 'light' || theme?.colorScheme === 'dark' ? theme.colorScheme : ''
|
|
const tokens = typeof theme?.tokens === 'string' ? theme.tokens.replace(/[{}<>]/g, '') : ''
|
|
return (
|
|
`<!doctype html>\n<html${scheme ? ` class="${scheme}"` : ''}>\n<head>\n<meta charset="utf-8">\n` +
|
|
`<style id="${PANEL_SHELL_TOKENS_STYLE_ID}">:root{${tokens}}</style>\n` +
|
|
`<script>\n'use strict'\n${frameApiScript(surface, transport)}</script>\n</head>\n${pluginHtml}`
|
|
)
|
|
}
|