Files
archived-orca/src/shared/plugins/frames/plugin-frame-shell-mount.test-fixture.ts
T
Neil 4a0ee07bd2 feat(plugins): orca.document.session() for custom editors (#37285)
* 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
2026-11-02 04:20:01 +00:00

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))