diff --git a/packages/gui-plugins/src/microsoft-office/document.tsx b/packages/gui-plugins/src/microsoft-office/document.tsx index 7335930c7f6..251b3225f96 100644 --- a/packages/gui-plugins/src/microsoft-office/document.tsx +++ b/packages/gui-plugins/src/microsoft-office/document.tsx @@ -1,9 +1,19 @@ -import { For, onCleanup, Show, type Accessor } from "solid-js" -import { createStore } from "solid-js/store" +import { createMemo, createSignal, For, onCleanup, Show, untrack } from "solid-js" +import { Button } from "@opencode/ui/button" import { Loader } from "@opencode/ui/loader" import { createLatest, usePlugin } from "@opencode/plugin/gui" import { createOfficeWorker, type WorkerClient } from "./office-worker" import { OfficePages, type PaintPage, type ScrollToPage } from "./pages" +import { + createWordLayoutState, + transitionWordLayout, + wordLayoutFailed, + wordLayoutIncomplete, + wordLayoutLoading, + wordLayoutPages, + type WordLayoutEffect, + type WordLayoutEvent, +} from "./word-layout-machine" import { layerFont, lineHeight, @@ -12,29 +22,21 @@ import { type WordPageSize, type WordSpan, } from "./word-protocol" -import { WorkerClosedError } from "./worker-rpc" import type { FileViewerProps } from "@opencode/plugin/gui/file" -type Opened = { - readonly pages: Accessor - /** The pages shown so far are the document's first; the rest are still being laid out. */ - readonly loading: Accessor - readonly paint: PaintPage - /** The page's text layer. */ - readonly text: (index: number, signal: AbortSignal) => Promise - /** Where a bookmark sits: its page and the height on it, in page pixels. Waits for the layout when it needs to. */ - readonly bookmark: (name: string) => Promise<{ readonly index: number; readonly y: number } | undefined> - /** Lays the rest of the document out, a step at a time between paints; resolves with its page count. */ - readonly finish: () => Promise -} - type Client = WorkerClient +/** An opened document: its worker, and the first pages it laid out with whether more follow. */ +type Opened = { + readonly client: Client + readonly first: { readonly pages: readonly WordPageSize[]; readonly loading: boolean } +} + /** Scrolls the page column; set once the column mounts. */ type Scroll = { to: ScrollToPage | undefined } -/** A value built on first use. */ -type Lazy = { value: T | undefined } +/** The layout step the worker runs, withdrawn when the document closes. */ +type Step = { current: AbortController | undefined } /** * A read-only, paginated Word document. Its engine runs in a worker of its own (`document.worker.ts`), which opens the @@ -45,11 +47,21 @@ type Lazy = { value: T | undefined } * each page makes its text selectable, findable and readable, and its links followable. */ export default function OfficeDocument(props: FileViewerProps) { + const ctx = usePlugin() + // A worker that dies after the pages showed takes them with it. const viewer = createOfficeWorker({ bytes: () => props.bytes, createWorker: () => new Worker(new URL("./document.worker.ts", import.meta.url), { type: "module" }), - open: async (client, buffer, signal) => ({ value: await open(client, buffer, signal) }), + open: async (client, buffer, signal) => { + const first = await client.call("open", { bytes: buffer }, { transfer: [buffer], signal }) + + // A longer document reports its page count once the rest is laid out. + return { + value: { client, first }, + details: first.loading ? undefined : [ctx.plural("pages", first.pages.length)], + } + }, onDetails: (details) => props.onDetails(details), onError: () => props.onError(), }) @@ -66,47 +78,132 @@ export default function OfficeDocument(props: FileViewerProps) { } > - {(opened) => ( - props.onDetails(details)} - onError={() => props.onError()} - /> - )} + {(opened) => props.onDetails(details)} />} ) } -/** One opened document's pages. A reloaded file mounts a new one. */ -function DocumentContent(props: { - opened: Opened - onDetails: (details: readonly string[]) => void - onError: () => void -}) { +/** + * One opened document's pages. A long document lays out the rest of its pages a step at a time once its first pages + * asked for their paints, which the worker then runs first; a bookmark past the pages laid out starts it sooner. + */ +function DocumentContent(props: { opened: Opened; onDetails: (details: readonly string[]) => void }) { const ctx = usePlugin() + const client = props.opened.client const scroll: Scroll = { to: undefined } - const controller = new AbortController() + const [layout, setLayout] = createSignal(createWordLayoutState(props.opened.first)) + const step: Step = { current: undefined } + // Bookmarks that wait for the rest of the layout. + const waiters: ((completed: boolean) => void)[] = [] + // Each page's text layer, kept for its page object: a page that scrolls back into view shows it without asking the + // worker. A page the full layout changed gets a new object, and asks again. + const texts = new WeakMap() + const pages = createMemo(() => wordLayoutPages(layout())) + const loading = createMemo(() => wordLayoutLoading(layout())) + const failed = createMemo(() => wordLayoutFailed(layout())) + // Every paint dispatches it, so it is built once. + const queued: WordLayoutEvent = { type: "paint.queued" } - onCleanup(() => controller.abort()) + const dispatch = (event: WordLayoutEvent) => { + const next = transitionWordLayout(untrack(layout), event) - // The worker runs calls in order, so the full layout waits until the first pages have asked for their paints: they - // do once the column is laid out and its observer reports them, which takes up to two frames. - void new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve))) - .then(() => (controller.signal.aborted ? undefined : props.opened.finish())) - .then( - (count) => { - if (count !== undefined && !controller.signal.aborted) props.onDetails([ctx.plural("pages", count)]) - }, - (error: Error) => { - // A worker that stopped reports itself through the viewer's worker. - if (!controller.signal.aborted && !(error instanceof WorkerClosedError)) props.onError() - }, + setLayout(() => next.state) + next.effects.forEach(run) + } + + const run = (effect: WordLayoutEffect) => { + if (effect.type === "start-step") return startStep(effect.attempt, effect.defer) + + if (effect.type === "end-step") return step.current?.abort() + + if (effect.type === "report-details") return props.onDetails([ctx.plural("pages", effect.pageCount)]) + + waiters.splice(0).forEach((resolve) => resolve(effect.completed)) + } + + const startStep = (attempt: number, defer: boolean) => { + const controller = new AbortController() + + step.current = controller + + const call = () => + void client.call("layout", undefined, { signal: controller.signal }).then( + (reply) => + dispatch( + reply.done + ? { type: "step.completed", attempt, pages: reply.pages, kept: reply.kept } + : { type: "step.progressed", attempt }, + ), + () => dispatch({ type: "step.failed", attempt }), + ) + + if (defer) return queueMicrotask(call) + + call() + } + + onCleanup(() => dispatch({ type: "disposed" })) + + const paint: PaintPage = async (index, canvas, scale, signal) => { + const painted = client.call( + "paint", + { index, scale, ratio: window.devicePixelRatio || 1 }, + // A newer paint of the page, such as at another scale, replaces this one while it waits, and a page that + // scrolled away withdraws it. + { key: `paint:${index}`, signal }, ) + // Builds the next page after the paints waiting, so scrolling on rarely waits for it. Pages stay unbuilt beyond + // that, and a paint releases the pages far from its own: each built page holds megabytes in the engine. + void client.call("build", { index: index + 1 }, { key: "build" }).catch(() => undefined) + + // The worker runs calls in order, so the rest of the layout queues behind the first pages' paints. + dispatch(queued) + + // A withdrawn paint rejects here, and the worker closes any bitmap it made for it. + const bitmap = await painted + + if (!bitmap) return + + const context = canvas.getContext("bitmaprenderer") + + if (!context) return bitmap.close() + + canvas.width = bitmap.width + canvas.height = bitmap.height + context.transferFromImageBitmap(bitmap) + } + + const text = async (index: number, signal: AbortSignal) => { + const page = pages()[index] + const cached = page && texts.get(page) + + if (cached) return cached + + const spans = await client.call("text", { index }, { signal }) + + if (page) texts.set(page, spans) + + return spans + } + + // Where a bookmark sits: its page and the height on it, in page pixels. Waits for the layout when it needs to. + const bookmark = async (name: string) => { + const found = await client.call("bookmark", { name }) + + if (found || !wordLayoutIncomplete(untrack(layout))) return found + + const completed = new Promise((resolve) => waiters.push(resolve)) + + dispatch({ type: "layout.requested" }) + + return (await completed) ? client.call("bookmark", { name }) : undefined + } + const follow = (link: WordLink) => { if (link.kind === "external") return ctx.system.openExternal(link.url) - void props.opened.bookmark(link.bookmark).then( + void bookmark(link.bookmark).then( (target) => { if (target) scroll.to?.(target.index, target.y) }, @@ -116,21 +213,24 @@ function DocumentContent(props: { return ( ctx.t("page", { number: index + 1 })} - overlay={(input) => ( - - )} + overlay={(input) => } text footer={(index) => ( - - + + + + + +
+ {ctx.t("document.layoutFailed")} + +
+
)} onScrollTo={(scrollTo) => { @@ -216,95 +316,3 @@ function place(span: WordSpan) { transform: span.transform, } } - -/** Opens the bytes in the worker and returns as soon as the document's first pages can show. */ -async function open(client: Client, buffer: ArrayBuffer, signal: AbortSignal): Promise { - const first = await client.call("open", { bytes: buffer }, { transfer: [buffer], signal }) - const [layout, setLayout] = createStore({ pages: first.pages, loading: first.loading }) - - const layOut = async (): Promise => { - const step = await client.call("layout", undefined) - - if (!step.done) return layOut() - - // A page keeps its object, and so its bitmap and text layer, unless the full layout changed it. A changed page - // keeps its row and paints again over its old bitmap. - const sizes = step.pages.map((page, index) => { - const size = layout.pages[index] - - return size && step.kept[index] && sameSize(size, page) ? size : page - }) - - // The column mounts the new rows a slice at a time. - setLayout({ pages: sizes, loading: false }) - - return sizes.length - } - - const rest: Lazy> = { value: undefined } - // Each page's text layer, kept for its page object: a page that scrolls back into view shows it without asking the - // worker. A page the full layout changed gets a new object, and asks again. - const texts = new WeakMap() - const pages = () => layout.pages - const loading = () => layout.loading - - const finish = () => (rest.value ??= loading() ? layOut() : Promise.resolve(pages().length)) - - return { - pages, - loading, - finish, - paint: async (index, canvas, scale, signal) => { - const painted = client.call( - "paint", - { index, scale, ratio: window.devicePixelRatio || 1 }, - // A newer paint of the page, such as at another scale, replaces this one while it waits, and a page that - // scrolled away withdraws it. - { key: `paint:${index}`, signal }, - ) - - // Builds the next page after the paints waiting, so scrolling on rarely waits for it. Pages stay unbuilt beyond - // that, and a paint releases the pages far from its own: each built page holds megabytes in the engine. - void client.call("build", { index: index + 1 }, { key: "build" }).catch(() => undefined) - - // A withdrawn paint rejects here, and the worker closes any bitmap it made for it. - const bitmap = await painted - - if (!bitmap) return - - const context = canvas.getContext("bitmaprenderer") - - if (!context) return bitmap.close() - - canvas.width = bitmap.width - canvas.height = bitmap.height - context.transferFromImageBitmap(bitmap) - }, - text: async (index, signal) => { - const page = pages()[index] - const cached = page && texts.get(page) - - if (cached) return cached - - const spans = await client.call("text", { index }, { signal }) - - if (page) texts.set(page, spans) - - return spans - }, - bookmark: async (name) => { - const found = await client.call("bookmark", { name }) - - // The bookmark may sit past the pages laid out so far. - if (found || !loading()) return found - - await finish() - - return client.call("bookmark", { name }) - }, - } -} - -function sameSize(size: WordPageSize, page: WordPageSize) { - return size.width === page.width && size.height === page.height && size.background === page.background -} diff --git a/packages/gui-plugins/src/microsoft-office/document.worker.ts b/packages/gui-plugins/src/microsoft-office/document.worker.ts index e32bc6622c8..6e5b632f7fa 100644 --- a/packages/gui-plugins/src/microsoft-office/document.worker.ts +++ b/packages/gui-plugins/src/microsoft-office/document.worker.ts @@ -18,6 +18,13 @@ import { createYrsPositionProjection, createYrsSession, type YrsPositionProjecti import { wordFonts } from "./fonts" import { createBitmapImageResolver } from "./word-images" import { layerFont, type WordMethods, type WordPageSize, type WordSpan } from "./word-protocol" +import { + createWorkerLayoutState, + stepBlocks, + transitionWorkerLayout, + workerLayoutComplete, + type WorkerLayoutState, +} from "./word-layout-machine" import { pageText, positionTarget, type TextMeasure } from "./word-text" import { serveWorker, Transfer } from "./worker-rpc" @@ -48,9 +55,6 @@ const decodeLayoutReply = Schema.decodeUnknownSync( /** Pages laid out and built before the first paint; later pages are built as they near the viewport. */ const firstPages = 3 -/** How long one layout step may hold back a paint that waits behind it, in milliseconds. */ -const stepBudget = 24 - /** * How many pages either side of the page painted last stay built. A built page holds about 5 MB in the engine and * builds again in about 100 ms. This keeps every page near the viewport, which paints a viewport ahead in both @@ -63,6 +67,9 @@ type Opened = Awaited> /** A value built on first use. */ type Lazy = { value: T | undefined } +/** Where the region layout that finishes the document has got to. */ +type LayoutCursor = { state: WorkerLayoutState } + /** The document this worker opened, once it has. */ const opened: Lazy = { value: undefined } @@ -167,9 +174,8 @@ async function open(bytes: Uint8Array) { if (retained.frame.displayList.pages.length === 0) throw new Error("The document produced no pages") - // The region layout that finishes the document: begun on the first step, `cost` the running average milliseconds a - // body block takes. - const layout = { loading: decodeLayoutReply(prefix).provisional ?? false, begun: false, cost: 3 } + // The region layout that finishes the document, a step at a time. + const layout: LayoutCursor = { state: createWorkerLayoutState(decodeLayoutReply(prefix).provisional ?? false) } // Builds a page's content when it is needed and not built, the first time or again after `release`. const built = (index: number) => { @@ -190,7 +196,7 @@ async function open(bytes: Uint8Array) { // when it is needed. const release = (painted: number) => { // The engine releases pages of the whole document's layout only, and few pages show before it. - if (layout.loading) return + if (!workerLayoutComplete(layout.state)) return const far = retained.frame.displayList.pages.flatMap((page, index) => !page.unbuilt && Math.abs(painted - index) > keptAround ? [index] : [], @@ -209,7 +215,7 @@ async function open(bytes: Uint8Array) { const before = retained.frame.displayList.pages retained.frame = display(retained.frame, reply) - layout.loading = false + layout.state = transitionWorkerLayout(layout.state, { type: "step.completed" }) const pages = retained.frame.displayList.pages @@ -234,34 +240,41 @@ async function open(bytes: Uint8Array) { return { pages: () => retained.frame.displayList.pages, - loading: () => layout.loading, + loading: () => !workerLayoutComplete(layout.state), built, - /** - * Lays out about `stepBudget` milliseconds more of the body. Blocks vary widely, and sizing a step by the last one - * alone overshoots after a run of cheap blocks. - */ + /** Begins the region layout, or lays out about `WORD_STEP_BUDGET_MS` more of the body. */ step: () => { - if (!layout.loading) { + const state = layout.state + + if (state.status === "complete") { const pages = retained.frame.displayList.pages return { done: true as const, pages: pages.map(pageSize), kept: pages.map(() => true) } } - if (!layout.begun) { - layout.begun = true - - const begun = session.beginRegionLayout(input) - - return begun.layoutJson === undefined ? { done: false as const } : complete(begun.layoutJson) - } - - const blocks = Math.min(8192, Math.max(1, Math.round(stepBudget / layout.cost))) + const blocks = state.status === "stepping" ? stepBlocks(state.cost) : 0 const started = performance.now() - const progress = session.resumeRegionLayout(blocks) - layout.cost = layout.cost * 0.7 + ((performance.now() - started) / blocks) * 0.3 + // A step that throws returns the cursor to the prefix, so the next step begins the region layout again rather + // than resuming a broken one. + try { + const progress = + state.status === "stepping" ? session.resumeRegionLayout(blocks) : session.beginRegionLayout(input) - return progress.layoutJson === undefined ? { done: false as const } : complete(progress.layoutJson) + if (progress.layoutJson !== undefined) return complete(progress.layoutJson) + + layout.state = transitionWorkerLayout(state, { + type: "step.progressed", + elapsedMs: performance.now() - started, + blocks, + }) + + return { done: false as const } + } catch (error) { + layout.state = transitionWorkerLayout(layout.state, { type: "step.failed" }) + + throw error + } }, paint: async (index: number, scale: number, ratio: number, signal: AbortSignal) => { // A page that scrolled away before its paint began, or while it rasterized, needs no bitmap. diff --git a/packages/gui-plugins/src/microsoft-office/i18n/en.ts b/packages/gui-plugins/src/microsoft-office/i18n/en.ts index bae469ace8f..5f0271b517c 100644 --- a/packages/gui-plugins/src/microsoft-office/i18n/en.ts +++ b/packages/gui-plugins/src/microsoft-office/i18n/en.ts @@ -10,6 +10,7 @@ export default { hiddenSlide: "Hidden slide", slideFailed: "This slide could not be shown", speakerNotes: "Speaker notes", + "document.layoutFailed": "The rest of this document could not be laid out", "sheet.copyTooLarge": "The selection is too large to copy", "sheet.copyFailed": "The cells could not be copied", "sheet.openFailed": "This sheet could not be opened", diff --git a/packages/gui-plugins/src/microsoft-office/word-layout-machine.test.ts b/packages/gui-plugins/src/microsoft-office/word-layout-machine.test.ts new file mode 100644 index 00000000000..79629630bdf --- /dev/null +++ b/packages/gui-plugins/src/microsoft-office/word-layout-machine.test.ts @@ -0,0 +1,257 @@ +import { describe, expect, test } from "bun:test" +import { + WORD_INITIAL_BLOCK_COST_MS, + WORD_MAX_STEP_BLOCKS, + createWordLayoutState, + createWorkerLayoutState, + mergeWordPages, + stepBlocks, + transitionWordLayout, + transitionWorkerLayout, + wordLayoutFailed, + wordLayoutIncomplete, + wordLayoutLoading, + wordLayoutPages, + workerLayoutComplete, + type WordLayoutEvent, + type WordLayoutState, + type WordLayoutTransition, +} from "./word-layout-machine" + +const page = (height: number) => ({ width: 816, height, background: undefined }) + +// Folds the events in order and returns the last transition. +const replay = (events: readonly WordLayoutEvent[], state: WordLayoutState) => + events.reduce((last, event) => transitionWordLayout(last.state, event), { state, effects: [] }) + +const longDocument = () => createWordLayoutState({ pages: [page(1056), page(1056), page(1056)], loading: true }) + +describe("transitionWordLayout", () => { + test("a pane that never paints keeps the layout at the prefix, and the first paint starts it behind its paints", () => { + const prefix = longDocument() + + expect(prefix.status).toBe("prefix") + expect(wordLayoutLoading(prefix)).toBe(true) + + const painted = transitionWordLayout(prefix, { type: "paint.queued" }) + + expect(painted).toEqual({ + state: { status: "laying-out", pages: wordLayoutPages(prefix), attempt: 1 }, + effects: [{ type: "start-step", attempt: 1, defer: true }], + }) + + const again = transitionWordLayout(painted.state, { type: "paint.queued" }) + + expect(again.state).toBe(painted.state) + expect(again.effects).toEqual([]) + }) + + test("a short document starts complete and never lays out", () => { + const complete = createWordLayoutState({ pages: [page(1056)], loading: false }) + + expect(complete.status).toBe("complete") + expect(wordLayoutLoading(complete)).toBe(false) + expect(wordLayoutIncomplete(complete)).toBe(false) + expect(transitionWordLayout(complete, { type: "paint.queued" }).state).toBe(complete) + expect(transitionWordLayout(complete, { type: "layout.requested" }).state).toBe(complete) + }) + + test("each step that leaves more asks for the next one", () => { + const laying = replay([{ type: "paint.queued" }], longDocument()) + const progressed = transitionWordLayout(laying.state, { type: "step.progressed", attempt: 1 }) + + expect(progressed.state).toBe(laying.state) + expect(progressed.effects).toEqual([{ type: "start-step", attempt: 1, defer: false }]) + }) + + test("a failed step keeps the pages, stops the loader and lets a bookmark try again", () => { + const prefix = longDocument() + const failed = replay([{ type: "paint.queued" }, { type: "step.failed", attempt: 1 }], prefix) + + expect(failed).toEqual({ + state: { status: "failed", pages: wordLayoutPages(prefix), attempt: 1 }, + effects: [{ type: "resolve-waiters", completed: false }], + }) + expect(wordLayoutLoading(failed.state)).toBe(false) + expect(wordLayoutIncomplete(failed.state)).toBe(true) + + // Scrolling on does not hammer a failing layout. + expect(transitionWordLayout(failed.state, { type: "paint.queued" }).state).toBe(failed.state) + + const retry = transitionWordLayout(failed.state, { type: "layout.requested" }) + + expect(retry).toEqual({ + state: { status: "laying-out", pages: wordLayoutPages(prefix), attempt: 2 }, + effects: [{ type: "start-step", attempt: 2, defer: false }], + }) + + const full = [page(1056), page(1056), page(1056), page(900)] + + const completed = transitionWordLayout(retry.state, { + type: "step.completed", + attempt: 2, + pages: full, + kept: [true, true, true, false], + }) + + expect(completed.state.status).toBe("complete") + expect(completed.effects).toEqual([ + { type: "report-details", pageCount: 4 }, + { type: "resolve-waiters", completed: true }, + ]) + }) + + test("a slow step keeps the loader up until it lands, so the first pages never pass for the whole document", () => { + const laying = replay([{ type: "paint.queued" }], longDocument()) + + // No step carries a deadline: the worker runs it synchronously and cannot be stopped, only discarded. + expect(laying.effects).toEqual([{ type: "start-step", attempt: 1, defer: true }]) + expect(wordLayoutLoading(laying.state)).toBe(true) + expect(wordLayoutFailed(laying.state)).toBe(false) + + const completed = transitionWordLayout(laying.state, { + type: "step.completed", + attempt: 1, + pages: [page(1056), page(1056), page(1056), page(1056)], + kept: [true, true, true, false], + }) + + expect(completed.state.status).toBe("complete") + expect(completed.effects).toEqual([ + { type: "report-details", pageCount: 4 }, + { type: "resolve-waiters", completed: true }, + ]) + }) + + test("a step that throws shows the notice, and Retry starts a new run", () => { + const failed = replay([{ type: "paint.queued" }, { type: "step.failed", attempt: 1 }], longDocument()) + + expect(wordLayoutFailed(failed.state)).toBe(true) + expect(wordLayoutLoading(failed.state)).toBe(false) + + // Retry dispatches the same event a bookmark past the laid-out pages does. + const retry = transitionWordLayout(failed.state, { type: "layout.requested" }) + + expect(retry.effects).toEqual([{ type: "start-step", attempt: 2, defer: false }]) + expect(wordLayoutFailed(retry.state)).toBe(false) + expect(wordLayoutLoading(retry.state)).toBe(true) + }) + + test("a bookmark before the first paint starts the layout at once", () => { + expect(transitionWordLayout(longDocument(), { type: "layout.requested" }).effects).toEqual([ + { type: "start-step", attempt: 1, defer: false }, + ]) + + const laying = replay([{ type: "paint.queued" }], longDocument()) + + expect(transitionWordLayout(laying.state, { type: "layout.requested" }).state).toBe(laying.state) + }) + + test("replies of an earlier run, or out of phase, change nothing", () => { + const retry = replay( + [{ type: "paint.queued" }, { type: "step.failed", attempt: 1 }, { type: "layout.requested" }], + longDocument(), + ) + + for (const event of [ + { type: "step.progressed", attempt: 1 }, + { type: "step.failed", attempt: 1 }, + { type: "step.completed", attempt: 1, pages: [page(1)], kept: [false] }, + ] satisfies WordLayoutEvent[]) { + const stale = transitionWordLayout(retry.state, event) + + expect(stale.state).toBe(retry.state) + expect(stale.effects).toEqual([]) + } + + const prefix = longDocument() + + expect(transitionWordLayout(prefix, { type: "step.progressed", attempt: 1 }).state).toBe(prefix) + }) + + test("disposal withdraws the step, answers waiting bookmarks and ignores everything after it", () => { + const disposed = replay([{ type: "paint.queued" }, { type: "disposed" }], longDocument()) + + expect(disposed).toEqual({ + state: { status: "disposed" }, + effects: [ + { type: "end-step", attempt: 1 }, + { type: "resolve-waiters", completed: false }, + ], + }) + expect(transitionWordLayout(longDocument(), { type: "disposed" }).effects).toEqual([ + { type: "resolve-waiters", completed: false }, + ]) + expect(wordLayoutPages(disposed.state)).toEqual([]) + expect(wordLayoutIncomplete(disposed.state)).toBe(false) + + for (const event of [ + { type: "paint.queued" }, + { type: "layout.requested" }, + { type: "step.completed", attempt: 1, pages: [page(1)], kept: [false] }, + { type: "disposed" }, + ] satisfies WordLayoutEvent[]) { + const after = transitionWordLayout(disposed.state, event) + + expect(after.state).toBe(disposed.state) + expect(after.effects).toEqual([]) + } + }) +}) + +describe("mergeWordPages", () => { + test("a page the full layout kept keeps its object; a changed or new page takes the new one", () => { + const previous = [page(1056), page(1056), page(1056)] + const next = [page(1056), page(1056), page(1000), page(1056)] + const merged = mergeWordPages(previous, next, [true, false, true, false]) + + expect(merged[0]).toBe(previous[0]) + // Not kept by the engine, even at the same size. + expect(merged[1]).toBe(next[1]) + // Kept by the engine, but a new size. + expect(merged[2]).toBe(next[2]) + expect(merged[3]).toBe(next[3]) + }) +}) + +describe("transitionWorkerLayout", () => { + test("a step that throws returns the cursor to the prefix, so the retry begins the layout again", () => { + const begun = transitionWorkerLayout(createWorkerLayoutState(true), { + type: "step.progressed", + elapsedMs: 40, + blocks: 0, + }) + + expect(begun).toEqual({ status: "stepping", cost: WORD_INITIAL_BLOCK_COST_MS }) + + const failed = transitionWorkerLayout(begun, { type: "step.failed" }) + + expect(failed).toEqual({ status: "prefix" }) + expect(workerLayoutComplete(failed)).toBe(false) + expect(transitionWorkerLayout(failed, { type: "step.failed" })).toBe(failed) + }) + + test("the block cost follows a running average, and the step size follows the cost", () => { + const stepping = transitionWorkerLayout( + { status: "stepping", cost: 3 }, + { type: "step.progressed", elapsedMs: 80, blocks: 8 }, + ) + + expect(stepping).toEqual({ status: "stepping", cost: 3 * 0.7 + 10 * 0.3 }) + expect(stepBlocks(3)).toBe(8) + expect(stepBlocks(1000)).toBe(1) + expect(stepBlocks(0.0001)).toBe(WORD_MAX_STEP_BLOCKS) + }) + + test("only a complete layout releases pages, and it stays complete", () => { + const short = createWorkerLayoutState(false) + + expect(workerLayoutComplete(short)).toBe(true) + expect(transitionWorkerLayout(short, { type: "step.failed" })).toBe(short) + + const completed = transitionWorkerLayout({ status: "stepping", cost: 3 }, { type: "step.completed" }) + + expect(workerLayoutComplete(completed)).toBe(true) + expect(workerLayoutComplete(createWorkerLayoutState(true))).toBe(false) + }) +}) diff --git a/packages/gui-plugins/src/microsoft-office/word-layout-machine.ts b/packages/gui-plugins/src/microsoft-office/word-layout-machine.ts new file mode 100644 index 00000000000..2ac20d25897 --- /dev/null +++ b/packages/gui-plugins/src/microsoft-office/word-layout-machine.ts @@ -0,0 +1,219 @@ +import type { WordPageSize } from "./word-protocol" + +/** How long one worker step may hold back a paint that waits behind it, in milliseconds. */ +export const WORD_STEP_BUDGET_MS = 24 + +/** What a body block is assumed to cost before the first step measures it, in milliseconds. */ +export const WORD_INITIAL_BLOCK_COST_MS = 3 + +/** The most body blocks one step lays out, however cheap they were. */ +export const WORD_MAX_STEP_BLOCKS = 8192 + +/** + * The window's view of a Word document's layout. The worker opens a document with its first pages laid out; a long one + * lays out the rest a step at a time once the first pages asked for their paints, or at once when a bookmark needs it. + * Each run of steps takes the next attempt number, so a reply whose attempt the state no longer holds is stale. + * + * A step has no timeout: the worker runs it synchronously, so withdrawing it would only discard a step that may still + * succeed, and the document would look complete when it is not. A worker that dies ends the viewer instead. + */ +export type WordLayoutState = + /** Only the first pages are laid out, and no paint has asked for any yet. */ + | { readonly status: "prefix"; readonly pages: readonly WordPageSize[] } + /** The rest of the document lays out, a step at a time. */ + | { readonly status: "laying-out"; readonly pages: readonly WordPageSize[]; readonly attempt: number } + | { readonly status: "complete"; readonly pages: readonly WordPageSize[] } + /** + * A step threw: the pages laid out so far stay readable, a notice under the last one offers to try again, and a + * bookmark past them tries again too. + */ + | { readonly status: "failed"; readonly pages: readonly WordPageSize[]; readonly attempt: number } + | { readonly status: "disposed" } + +export type WordLayoutEvent = + /** A page asked the worker for its paint. */ + | { readonly type: "paint.queued" } + /** A bookmark is not in the pages laid out so far, or the user asked to try a failed layout again. */ + | { readonly type: "layout.requested" } + /** A step laid out more of the document, and more is left. */ + | { readonly type: "step.progressed"; readonly attempt: number } + /** `kept` tells, per page, whether the full layout left the page shown so far unchanged. */ + | { + readonly type: "step.completed" + readonly attempt: number + readonly pages: readonly WordPageSize[] + readonly kept: readonly boolean[] + } + /** The step threw in the worker, or its call rejected. */ + | { readonly type: "step.failed"; readonly attempt: number } + | { readonly type: "disposed" } + +export type WordLayoutEffect = + /** + * Asks the worker for one step. `defer` waits a microtask, so every paint the first pages ask for in the same task + * reaches the worker's queue ahead of the step. + */ + | { readonly type: "start-step"; readonly attempt: number; readonly defer: boolean } + /** Withdraws the attempt's step. */ + | { readonly type: "end-step"; readonly attempt: number } + | { readonly type: "report-details"; readonly pageCount: number } + /** Answers the bookmarks waiting for the layout: `completed` when the whole document is laid out. */ + | { readonly type: "resolve-waiters"; readonly completed: boolean } + +export type WordLayoutTransition = { readonly state: WordLayoutState; readonly effects: readonly WordLayoutEffect[] } + +const NONE: readonly WordLayoutEffect[] = [] + +export function createWordLayoutState(first: { + readonly pages: readonly WordPageSize[] + readonly loading: boolean +}): WordLayoutState { + return first.loading ? { status: "prefix", pages: first.pages } : { status: "complete", pages: first.pages } +} + +export function transitionWordLayout(state: WordLayoutState, event: WordLayoutEvent): WordLayoutTransition { + if (state.status === "disposed") return { state, effects: NONE } + + if (event.type === "disposed") + return { + state: { status: "disposed" }, + effects: + state.status === "laying-out" + ? [ + { type: "end-step", attempt: state.attempt }, + { type: "resolve-waiters", completed: false }, + ] + : [{ type: "resolve-waiters", completed: false }], + } + + // The first paint starts the rest of the layout; a failed layout waits for Retry or a bookmark rather than retrying on + // every scroll. + if (event.type === "paint.queued") return state.status === "prefix" ? start(state, 1, true) : { state, effects: NONE } + + if (event.type === "layout.requested") { + if (state.status === "prefix") return start(state, 1, false) + + if (state.status === "failed") return start(state, state.attempt + 1, false) + + return { state, effects: NONE } + } + + if (state.status !== "laying-out" || event.attempt !== state.attempt) return { state, effects: NONE } + + if (event.type === "step.progressed") + return { state, effects: [{ type: "start-step", attempt: state.attempt, defer: false }] } + + if (event.type === "step.completed") { + const pages = mergeWordPages(state.pages, event.pages, event.kept) + + return { + state: { status: "complete", pages }, + effects: [ + { type: "report-details", pageCount: pages.length }, + { type: "resolve-waiters", completed: true }, + ], + } + } + + return { + state: { status: "failed", pages: state.pages, attempt: state.attempt }, + effects: [{ type: "resolve-waiters", completed: false }], + } +} + +/** + * The full layout's pages, where a page the full layout left unchanged keeps its object, and so its bitmap and text + * layer. A changed page gets the new object, keeps its row and paints again over its old bitmap. + */ +export function mergeWordPages( + previous: readonly WordPageSize[], + pages: readonly WordPageSize[], + kept: readonly boolean[], +) { + return pages.map((page, index) => { + const size = previous[index] + + return size && + kept[index] && + size.width === page.width && + size.height === page.height && + size.background === page.background + ? size + : page + }) +} + +/** The pages the column shows. */ +export function wordLayoutPages(state: WordLayoutState): readonly WordPageSize[] { + return state.status === "disposed" ? [] : state.pages +} + +/** Whether the last page shows the loader for the pages still to come. */ +export function wordLayoutLoading(state: WordLayoutState) { + return state.status === "prefix" || state.status === "laying-out" +} + +/** Whether the last page shows the notice that the rest could not be laid out, with Retry. */ +export function wordLayoutFailed(state: WordLayoutState) { + return state.status === "failed" +} + +/** Whether a bookmark not found so far may still turn up once the layout runs. */ +export function wordLayoutIncomplete(state: WordLayoutState) { + return state.status === "prefix" || state.status === "laying-out" || state.status === "failed" +} + +function start( + state: Extract, + attempt: number, + defer: boolean, +): WordLayoutTransition { + return { + state: { status: "laying-out", pages: state.pages, attempt }, + effects: [{ type: "start-step", attempt, defer }], + } +} + +/** + * The worker's region layout cursor. Only the prefix is laid out until the first step begins the region layout; a step + * that throws returns the cursor to the prefix, so the next step begins it again instead of resuming a broken one. + */ +export type WorkerLayoutState = + | { readonly status: "prefix" } + /** `cost` is the running average milliseconds one body block takes. */ + | { readonly status: "stepping"; readonly cost: number } + | { readonly status: "complete" } + +export type WorkerLayoutEvent = + /** A step laid out `blocks` body blocks in `elapsedMs`; the step that begins the layout reports no blocks. */ + | { readonly type: "step.progressed"; readonly elapsedMs: number; readonly blocks: number } + | { readonly type: "step.completed" } + | { readonly type: "step.failed" } + +export function createWorkerLayoutState(provisional: boolean): WorkerLayoutState { + return provisional ? { status: "prefix" } : { status: "complete" } +} + +export function transitionWorkerLayout(state: WorkerLayoutState, event: WorkerLayoutEvent): WorkerLayoutState { + if (state.status === "complete") return state + + if (event.type === "step.completed") return { status: "complete" } + + if (event.type === "step.failed") return state.status === "prefix" ? state : { status: "prefix" } + + // Blocks vary widely, and sizing a step by the last one alone overshoots after a run of cheap blocks. + if (state.status === "stepping" && event.blocks > 0) + return { status: "stepping", cost: state.cost * 0.7 + (event.elapsedMs / event.blocks) * 0.3 } + + return state.status === "stepping" ? state : { status: "stepping", cost: WORD_INITIAL_BLOCK_COST_MS } +} + +/** How many body blocks the next step lays out to take about `WORD_STEP_BUDGET_MS`. */ +export function stepBlocks(cost: number) { + return Math.min(WORD_MAX_STEP_BLOCKS, Math.max(1, Math.round(WORD_STEP_BUDGET_MS / cost))) +} + +/** Whether the whole document is laid out, so the engine can release built pages. */ +export function workerLayoutComplete(state: WorkerLayoutState) { + return state.status === "complete" +}