fix(gui-plugins): drive Word progressive layout with an explicit state machine (#61895)

This commit is contained in:
Luke Parker
2026-11-04 21:41:18 -06:00
committed by GitHub
Unverified
parent 5eeb906b27
commit bc8cb10ea5
5 changed files with 675 additions and 177 deletions
@@ -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<readonly WordPageSize[]>
/** The pages shown so far are the document's first; the rest are still being laid out. */
readonly loading: Accessor<boolean>
readonly paint: PaintPage
/** The page's text layer. */
readonly text: (index: number, signal: AbortSignal) => Promise<readonly WordSpan[]>
/** 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<number>
}
type Client = WorkerClient<WordMethods>
/** 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<T> = { 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<T> = { 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<WordMethods, Opened>({
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) {
</Show>
}
>
{(opened) => (
<DocumentContent
opened={opened.value}
onDetails={(details) => props.onDetails(details)}
onError={() => props.onError()}
/>
)}
{(opened) => <DocumentContent opened={opened.value} onDetails={(details) => props.onDetails(details)} />}
</Show>
)
}
/** 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<WordPageSize, readonly WordSpan[]>()
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<boolean>((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 (
<OfficePages
pages={props.opened.pages()}
paint={props.opened.paint}
pages={pages()}
paint={paint}
label={(index) => ctx.t("page", { number: index + 1 })}
overlay={(input) => (
<WordTextLayer
index={input.index}
page={props.opened.pages()[input.index]}
text={props.opened.text}
follow={follow}
/>
)}
overlay={(input) => <WordTextLayer index={input.index} page={pages()[input.index]} text={text} follow={follow} />}
text
footer={(index) => (
<Show when={props.opened.loading() && index === props.opened.pages().length - 1}>
<Loader />
<Show when={index === pages().length - 1}>
<Show when={loading()}>
<Loader />
</Show>
<Show when={failed()}>
<div role="status" class="flex items-center gap-2 text-12-regular text-v2-text-text-muted">
{ctx.t("document.layoutFailed")}
<Button size="small" variant="outline" onClick={() => dispatch({ type: "layout.requested" })}>
{ctx.t("common.retry")}
</Button>
</div>
</Show>
</Show>
)}
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<Opened> {
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<number> => {
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<Promise<number>> = { 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<WordPageSize, readonly WordSpan[]>()
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
}
@@ -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<ReturnType<typeof open>>
/** A value built on first use. */
type Lazy<T> = { 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<Opened> = { 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.
@@ -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",
@@ -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<WordLayoutTransition>((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)
})
})
@@ -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<WordLayoutState, { status: "prefix" | "failed" }>,
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"
}