mirror of
https://github.com/stablyai/orca.git
synced 2026-11-19 04:23:57 +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
84 lines
3.3 KiB
TypeScript
84 lines
3.3 KiB
TypeScript
import { afterEach, vi, type Mock } from 'vitest'
|
|
import { buildPluginPanelShellHtml, type PluginFrameSurface } from './plugin-panel-shell'
|
|
|
|
/** The injected `window.orca` is the public frame API; the envelope under it stays internal. */
|
|
export type FrameOrca = {
|
|
api: { major: number; minor: number }
|
|
host: {
|
|
call: (method: string, params?: unknown, options?: { signal?: AbortSignal }) => Promise<unknown>
|
|
has: (method: string) => boolean
|
|
}
|
|
on: (event: string, handler: (payload: unknown) => unknown) => { dispose: () => void }
|
|
locale: string
|
|
plugin: object
|
|
storage: object
|
|
shell?: { openExternal: (url: string) => Promise<unknown> }
|
|
files?: {
|
|
saveAs: (options: {
|
|
suggestedName?: string
|
|
mimeType?: string
|
|
data: unknown
|
|
}) => Promise<unknown>
|
|
}
|
|
document?: {
|
|
get: () => Promise<unknown>
|
|
onDidChange: (handler: (document: unknown) => void) => { dispose: () => void }
|
|
applyEdit: (edit: unknown) => Promise<unknown>
|
|
session: (options?: FrameDocumentSessionOptions) => Promise<FrameDocumentSession>
|
|
}
|
|
}
|
|
|
|
// Method syntax: a test passes typed callbacks, which method parameters accept bivariantly.
|
|
export type FrameDocumentSessionOptions = {
|
|
debounceMs?: number
|
|
decode?(content: unknown): unknown
|
|
encode?(value: unknown): unknown
|
|
merge?(base: unknown, outside: unknown, mine: unknown): unknown
|
|
}
|
|
|
|
/** A host → frame envelope, as tests deliver it. */
|
|
export type FrameHostMessage = { orca: number; kind: string } & Record<string, unknown>
|
|
|
|
export type FrameDocumentSession = {
|
|
readonly value: unknown
|
|
readonly readOnly: boolean
|
|
change: (next: unknown) => void
|
|
flush: () => Promise<void>
|
|
onReplace: (handler: (value: unknown) => void) => { dispose: () => void }
|
|
dispose: () => void
|
|
}
|
|
|
|
const realParent = window.parent
|
|
|
|
// Registered by importing: each test gets the real `window.parent` back.
|
|
afterEach(() => {
|
|
Object.defineProperty(window, 'parent', { value: realParent, configurable: true })
|
|
})
|
|
|
|
export type MountedShell = {
|
|
orca: FrameOrca
|
|
parent: { postMessage: Mock<(message: Record<string, unknown>) => void> }
|
|
fromHost: (data: unknown, source?: unknown) => boolean
|
|
posted: () => Record<string, unknown>[]
|
|
}
|
|
|
|
export function mountShell(surface: PluginFrameSurface = 'panel'): MountedShell {
|
|
const parent = { postMessage: vi.fn<(message: Record<string, unknown>) => void>() }
|
|
Object.defineProperty(window, 'parent', { value: parent, configurable: true })
|
|
const script = buildPluginPanelShellHtml('<main></main>', surface).match(
|
|
/<script>\n([\s\S]*?)<\/script>/
|
|
)?.[1]
|
|
// Configurable only so happy-dom can tear down; the frame's copy stays locked.
|
|
window.eval(script!.replaceAll('configurable: false', 'configurable: true'))
|
|
const orca: FrameOrca = Object.getOwnPropertyDescriptor(window, 'orca')?.value
|
|
const fromHost = (data: unknown, source: unknown = parent) =>
|
|
window.dispatchEvent(
|
|
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the shim only compares source identity.
|
|
new MessageEvent('message', { data, source: source as Window })
|
|
)
|
|
const posted = () => parent.postMessage.mock.calls.map(([message]) => message)
|
|
return { orca, parent, fromHost, posted }
|
|
}
|
|
|
|
export const flush = (): Promise<unknown> => new Promise((resolve) => setTimeout(resolve, 0))
|