The best way to control Claude Code, Codex and more from any computer or phone
fix(web): improve Word document previews (#34722)
Co-authored-by: Cursor <cursoragent@cursor.com>
Yash Singh committed
Nov 11, 2026 at 22:07 UTC
fd033dfec350500c72a6719473a35eded3aa57a9
17 files changed
+884
-436
apps/web/package.json
+1
-1
@@ -15,7 +15,7 @@
15
},
16
"dependencies": {
17
"@base-ui/react": "^1.9.0",
18
- "@betteroffice/docx": "0.4.3",
18
+ "@betteroffice/docx": "0.5.1",
19
"@betteroffice/fonts": "0.4.0",
20
"@betteroffice/fonts-cjk": "0.4.0",
21
"@betteroffice/pptx": "0.5.1",
apps/web/src/components/files/office/Presentation.tsx
+2
-31
@@ -8,12 +8,8 @@ import {
8
} from "../fileSurfaceChrome";
9
import { OfficePages, type PaintPage } from "./OfficePages";
10
import { createWorkerClient } from "./worker-rpc";
11
-import {
12
- maxImageSide,
13
- type SlideMethods,
14
- type SlideSummary,
15
- type VectorRequest,
16
-} from "./slide-protocol";
11
+import type { SlideMethods, SlideSummary } from "./slide-protocol";
12
+import { rasterize } from "./vector-pictures";
13
14
type Opened = { slides: readonly SlideSummary[]; paint: PaintPage };
15
export default function Presentation(props: {
@@ -160,28 +156,3 @@ export default function Presentation(props: {
156
</div>
157
);
158
}
163
-async function rasterize(request: VectorRequest) {
164
- const url = URL.createObjectURL(request.blob);
165
- const image = new Image();
166
- image.src = url;
167
- try {
168
- await image.decode();
169
- const shrink = Math.min(1, maxImageSide / Math.max(image.naturalWidth, image.naturalHeight));
170
- const size = request.size ?? {
171
- width: Math.max(1, Math.round(image.naturalWidth * shrink)),
172
- height: Math.max(1, Math.round(image.naturalHeight * shrink)),
173
- };
174
- return {
175
- asset: request.asset,
176
- bitmap: await createImageBitmap(image, {
177
- resizeWidth: size.width,
178
- resizeHeight: size.height,
179
- resizeQuality: "high",
180
- }),
181
- };
182
- } catch {
183
- return { asset: request.asset, bitmap: undefined };
184
- } finally {
185
- URL.revokeObjectURL(url);
186
- }
187
-}
apps/web/src/components/files/office/WordDocument.tsx
+25
-7
@@ -4,6 +4,7 @@ import { Tooltip, TooltipTrigger, TooltipPopup } from "~/components/ui/tooltip";
4
import { Fragment, useEffect, useRef, useState } from "react";
5
import { FileSurfaceLoading } from "../fileSurfaceChrome";
6
import { OfficePages, type PaintPage } from "./OfficePages";
7
+import { rasterize } from "./vector-pictures";
8
import { createWorkerClient } from "./worker-rpc";
9
import {
10
layerFont,
@@ -39,8 +40,14 @@ export default function WordDocument(props: {
40
worker.addEventListener("error", fail);
41
worker.addEventListener("messageerror", fail);
42
const buffer = bytes.slice(0);
42
- const paint: PaintPage = async (index, canvas, scale, signal) => {
43
- const bitmap = await engine.call(
43
+ const paint = async (
44
+ index: number,
45
+ canvas: HTMLCanvasElement,
46
+ scale: number,
47
+ signal: AbortSignal,
48
+ again = false,
49
+ ): Promise<void> => {
50
+ const painted = await engine.call(
51
"paint",
52
{ index, scale, ratio: window.devicePixelRatio || 1 },
53
{ key: `paint:${index}`, signal },
@@ -48,15 +55,26 @@ export default function WordDocument(props: {
55
void engine
56
.call("build", { index: index + 1 }, { key: "build", signal })
57
.catch(() => undefined);
51
- if (!bitmap) return;
58
+ if (!painted) return;
59
const context = canvas.getContext("bitmaprenderer");
60
if (!context || signal.aborted) {
54
- bitmap.close();
61
+ painted.bitmap.close();
62
return;
63
}
57
- canvas.width = bitmap.width;
58
- canvas.height = bitmap.height;
59
- context.transferFromImageBitmap(bitmap);
64
+ canvas.width = painted.bitmap.width;
65
+ canvas.height = painted.bitmap.height;
66
+ context.transferFromImageBitmap(painted.bitmap);
67
+ if (again || !painted.vectors.length) return;
68
+ const bitmaps = await Promise.all(painted.vectors.map(rasterize));
69
+ if (signal.aborted) {
70
+ bitmaps.forEach((value) => value.bitmap?.close());
71
+ return;
72
+ }
73
+ await engine.call("vectors", bitmaps, {
74
+ transfer: bitmaps.flatMap((value) => (value.bitmap ? [value.bitmap] : [])),
75
+ signal,
76
+ });
77
+ if (!signal.aborted) await paint(index, canvas, scale, signal, true);
78
};
79
void engine
80
.call("open", { bytes: buffer }, { transfer: [buffer], signal: controller.signal })
apps/web/src/components/files/office/document.worker.ts
+18
-344
@@ -1,81 +1,24 @@
1
// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
2
-import * as Schema from "effect/Schema";
3
-import {
4
- buildResidentRegionLayoutRequest,
5
- getLayoutKernelInputs,
6
- workerLayoutComputation,
7
-} from "@betteroffice/docx/editor";
8
-import { createRustMeasureSource } from "@betteroffice/docx/layout";
9
-import {
10
- applyFrameDelta,
11
- decodeFrameDelta,
12
- encodeDisplayListFrameExtras,
13
- GlyphCache,
14
- rasterizeDisplayPageToBackBuffer,
15
- type DisplayPage,
16
- type RetainedFrame,
17
-} from "@betteroffice/docx/layout/render";
18
-import {
19
- createYrsPositionProjection,
20
- createYrsSession,
21
- type YrsPositionProjection,
22
-} from "@betteroffice/docx/yrs";
23
-import { wordFonts } from "./fonts";
24
-import { createBitmapImageResolver } from "./word-images";
25
-import { layerFont, type WordMethods, type WordPageSize, type WordSpan } from "./word-protocol";
26
-import { pageText, positionTarget, type TextMeasure } from "./word-text";
2
+import { openWordDocument, pageSize } from "./word-document";
3
+import type { WordMethods } from "./word-protocol";
4
import { serveWorker, Transfer } from "./worker-rpc";
5
29
-// One worker holds one open Word document: its engine session, fonts, layout, built pages and painting. The window
30
-// terminates the worker when the document closes, which is the only way the engine's memory is given back.
31
-
32
-const FontRequirements = Schema.fromJsonString(
33
- Schema.Array(
34
- Schema.Struct({
35
- key: Schema.String,
36
- family: Schema.String,
37
- bold: Schema.Boolean,
38
- italic: Schema.Boolean,
39
- scripts: Schema.optional(
40
- Schema.Array(Schema.Literals(["cjk-sc", "cjk-tc", "cjk-jp", "cjk-kr", "arabic", "hebrew"])),
41
- ),
42
- }),
43
- ),
44
-);
45
-
46
-const decodeFontRequirements = Schema.decodeUnknownSync(FontRequirements);
47
-
48
-/** A prefix layout's reply marks itself provisional when the document goes on past it. */
49
-const decodeLayoutReply = Schema.decodeUnknownSync(
50
- Schema.fromJsonString(Schema.Struct({ provisional: Schema.optional(Schema.Boolean) })),
51
-);
52
-
53
-/** Pages laid out and built before the first paint; later pages are built as they near the viewport. */
54
-const firstPages = 3;
55
-
56
-/** How long one layout step may hold back a paint that waits behind it, in milliseconds. */
57
-const stepBudget = 24;
58
-
59
-/**
60
- * How many pages either side of the page painted last stay built. A built page holds about 5 MB in the engine and
61
- * builds again in about 100 ms. This keeps every page near the viewport, which paints a viewport ahead in both
62
- * directions, and lets a reader scroll back a few screens without waiting, while a long read holds at most 21 pages.
63
- */
64
-const keptAround = 10;
65
-
66
-type Opened = Awaited<ReturnType<typeof open>>;
67
-
68
-/** A value built on first use. */
69
-type Lazy<T> = { value: T | undefined };
6
+// One worker holds one open Word document. The window terminates the worker when the document closes, which is the only
7
+// way the engine's memory is given back.
8
9
/** The document this worker opened, once it has. */
72
-const opened: Lazy<Opened> = { value: undefined };
10
+const opened: { value: Awaited<ReturnType<typeof openWordDocument>> | undefined } = {
11
+ value: undefined,
12
+};
13
14
serveWorker<WordMethods>({
15
open: async (input) => {
16
if (opened.value) throw new Error("The worker already holds a document");
17
78
- const loaded = await open(new Uint8Array(input.bytes));
18
+ // SAFETY: a worker's global scope is a FontFaceSource, whose `fonts` is a FontFaceSet (CSS Font Loading, exposed to
19
+ // workers). The window's types declare it on documents only. Without one, the canvas keeps the system's fonts.
20
+ const fonts = "fonts" in self ? (self.fonts as FontFaceSet) : undefined;
21
+ const loaded = await openWordDocument(new Uint8Array(input.bytes), fonts);
22
23
opened.value = loaded;
24
@@ -83,9 +26,14 @@ serveWorker<WordMethods>({
26
},
27
layout: () => required().step(),
28
paint: async (input, signal) => {
86
- const bitmap = await required().paint(input.index, input.scale, input.ratio, signal);
29
+ const painted = await required().paint(input.index, input.scale, input.ratio, signal);
30
+
31
+ return painted ? new Transfer(painted, [painted.bitmap]) : undefined;
32
+ },
33
+ vectors: (input) => {
34
+ required().vectors(input);
35
88
- return bitmap ? new Transfer(bitmap, [bitmap]) : undefined;
36
+ return undefined;
37
},
38
build: (input) => {
39
required().built(input.index);
@@ -101,277 +49,3 @@ function required() {
49
50
return opened.value;
51
}
104
-
105
-/** Opens the document and lays out its first pages; the rest lay out a `step` at a time. */
106
-async function open(bytes: Uint8Array) {
107
- const session = await createYrsSession();
108
- const document = session.openDocx(bytes, true, { mediaTokens: true }).document;
109
- const settings = document.package.settings;
110
-
111
- const measure = createRustMeasureSource({
112
- engine: {
113
- registerFont: (font) => session.registerFont(font),
114
- registerSubstituteFont: (id, family) => session.registerSubstituteFont(id, family),
115
- clearFonts: () => session.clearFonts(),
116
- },
117
- bundled: wordFonts(),
118
- });
119
-
120
- measure.setCompat(settings?.compatibilityFlags);
121
-
122
- const request = buildResidentRegionLayoutRequest(document, 0, {
123
- themeColors: Object.fromEntries(
124
- Object.entries(document.package.theme?.colorScheme ?? {}).filter(
125
- (entry): entry is [string, string] => entry[1] !== undefined,
126
- ),
127
- ),
128
- defaultTabStopTwips: settings?.defaultTabStop ?? null,
129
- numericIds: {},
130
- mediaTokens: true,
131
- });
132
-
133
- const requirements = decodeFontRequirements(
134
- session.layoutFontRequirementsJson(JSON.stringify(request)),
135
- ).map(({ scripts, ...requirement }) => ({
136
- ...requirement,
137
- ...(scripts ? { scripts: [...scripts] } : {}),
138
- }));
139
-
140
- await measure.prepareFontRequirements(requirements);
141
-
142
- const measurement = measure.measurementConfigForRequirements(requirements);
143
-
144
- if (!measurement) throw new Error("The document's fonts could not be prepared");
145
-
146
- const input = JSON.stringify({ ...request, measurement });
147
-
148
- // Word shows resolved comments without the active highlight.
149
- const resolvedCommentIds = (document.package.document.comments ?? [])
150
- .filter(
151
- (comment) =>
152
- (comment.done || comment.status === "resolved") && comment.parentId === undefined,
153
- )
154
- .map((comment) => comment.id);
155
-
156
- // The session keeps the layout it last ran and builds display frames from it: only the display extras go in, and a
157
- // binary frame comes back with the window's pages built and every other page a placeholder carrying its geometry.
158
- const display = (previous: RetainedFrame | null, reply: string) => {
159
- const layout = workerLayoutComputation(reply).layout;
160
-
161
- session.setDisplayWindow(0, firstPages);
162
-
163
- const extras = encodeDisplayListFrameExtras({
164
- measured: [],
165
- options: {},
166
- layout,
167
- fontChains: measurement.fontChains,
168
- ...(getLayoutKernelInputs(layout)?.headersFooters
169
- ? { headersFooters: getLayoutKernelInputs(layout)!.headersFooters! }
170
- : {}),
171
- resolvedCommentIds,
172
- });
173
-
174
- return applyFrameDelta(
175
- previous,
176
- decodeFrameDelta(session.buildDisplayListFrame(extras, previous?.frameEpoch ?? 0)),
177
- );
178
- };
179
-
180
- // Only as much of the body as fills the first pages; a long document goes on past it.
181
- const prefix = session.layoutDocumentWithRegionsPrefixRetainedJson(input, firstPages);
182
- const retained = { frame: display(null, prefix) };
183
-
184
- if (retained.frame.displayList.pages.length === 0)
185
- throw new Error("The document produced no pages");
186
-
187
- // The region layout that finishes the document: begun on the first step, `cost` the running average milliseconds a
188
- // body block takes.
189
- const layout = { loading: decodeLayoutReply(prefix).provisional ?? false, begun: false, cost: 3 };
190
-
191
- // Builds a page's content when it is needed and not built, the first time or again after `release`.
192
- const built = (index: number) => {
193
- const page = retained.frame.displayList.pages[index];
194
-
195
- if (!page?.unbuilt) return page;
196
-
197
- retained.frame = applyFrameDelta(
198
- retained.frame,
199
- decodeFrameDelta(session.buildDisplayPagesFrame([index], retained.frame.frameEpoch)),
200
- );
201
-
202
- return retained.frame.displayList.pages[index];
203
- };
204
-
205
- // Gives back the built pages far from the page about to paint, so a long read keeps only the pages around the
206
- // viewport. A released page keeps its geometry and document positions, which bookmarks search, and builds again
207
- // when it is needed.
208
- const release = (painted: number) => {
209
- // The engine releases pages of the whole document's layout only, and few pages show before it.
210
- if (layout.loading) return;
211
-
212
- const far = retained.frame.displayList.pages.flatMap((page, index) =>
213
- !page.unbuilt && Math.abs(painted - index) > keptAround ? [index] : [],
214
- );
215
-
216
- if (far.length === 0) return;
217
-
218
- const frame = session.releaseDisplayPagesFrame(far, retained.frame.frameEpoch);
219
-
220
- // A superseded release changes nothing; the next one tries again.
221
- if (frame) retained.frame = applyFrameDelta(retained.frame, decodeFrameDelta(frame));
222
- };
223
-
224
- // The whole document's layout replaces the prefix's frame.
225
- const complete = (reply: string) => {
226
- const before = retained.frame.displayList.pages;
227
-
228
- retained.frame = display(retained.frame, reply);
229
- layout.loading = false;
230
-
231
- const pages = retained.frame.displayList.pages;
232
-
233
- return {
234
- done: true as const,
235
- pages: pages.map(pageSize),
236
- kept: pages.map((page, index) => {
237
- const was = before[index];
238
-
239
- return was === page || (!!was?.unbuilt && !!page.unbuilt);
240
- }),
241
- };
242
- };
243
-
244
- const glyphCache = new GlyphCache({
245
- provider: (font, glyph) => session.outlineGlyphJson(font, glyph),
246
- });
247
- const images = createBitmapImageResolver((token) => session.mediaSource(token));
248
- const surface = new OffscreenCanvas(1, 1);
249
- const textMeasure = layerMeasure();
250
- const texts = new WeakMap<DisplayPage, readonly WordSpan[]>();
251
- // Built on the first followed bookmark: most documents are read without one.
252
- const projection: Lazy<YrsPositionProjection | null> = { value: undefined };
253
-
254
- return {
255
- pages: () => retained.frame.displayList.pages,
256
- loading: () => layout.loading,
257
- built,
258
- /**
259
- * Lays out about `stepBudget` milliseconds more of the body. Blocks vary widely, and sizing a step by the last one
260
- * alone overshoots after a run of cheap blocks.
261
- */
262
- step: () => {
263
- if (!layout.loading) {
264
- const pages = retained.frame.displayList.pages;
265
-
266
- return { done: true as const, pages: pages.map(pageSize), kept: pages.map(() => true) };
267
- }
268
-
269
- if (!layout.begun) {
270
- layout.begun = true;
271
-
272
- const begun = session.beginRegionLayout(input);
273
-
274
- return begun.layoutJson === undefined
275
- ? { done: false as const }
276
- : complete(begun.layoutJson);
277
- }
278
-
279
- const blocks = Math.min(8192, Math.max(1, Math.round(stepBudget / layout.cost)));
280
- const started = performance.now();
281
- const progress = session.resumeRegionLayout(blocks);
282
-
283
- layout.cost = layout.cost * 0.7 + ((performance.now() - started) / blocks) * 0.3;
284
-
285
- return progress.layoutJson === undefined
286
- ? { done: false as const }
287
- : complete(progress.layoutJson);
288
- },
289
- paint: async (index: number, scale: number, ratio: number, signal: AbortSignal) => {
290
- // A page that scrolled away before its paint began, or while it rasterized, needs no bitmap.
291
- if (signal.aborted) return undefined;
292
-
293
- // Released first, so the page builds in the memory they free.
294
- release(index);
295
-
296
- const page = built(index);
297
-
298
- if (!page) return undefined;
299
-
300
- // The window drew image elements, which shrink smoothly at the default quality; a bitmap needs medium quality to
301
- // look the same. Sizing the surface first keeps the setting: the painter resizes it, which resets the context,
302
- // only when its size differs.
303
- const context = surface.getContext("2d");
304
- const width = Math.ceil(page.width * ratio * scale);
305
- const height = Math.ceil(page.height * ratio * scale);
306
-
307
- if (surface.width !== width) surface.width = width;
308
-
309
- if (surface.height !== height) surface.height = height;
310
-
311
- if (context) context.imageSmoothingQuality = "medium";
312
-
313
- await rasterizeDisplayPageToBackBuffer(
314
- surface,
315
- page,
316
- { glyphCache, resolveImage: images.resolve },
317
- ratio,
318
- scale,
319
- );
320
- images.trim();
321
-
322
- if (signal.aborted) return undefined;
323
-
324
- return surface.transferToImageBitmap();
325
- },
326
- text: (index: number) => {
327
- const page = built(index);
328
-
329
- if (!page || !textMeasure) return [];
330
-
331
- const cached = texts.get(page);
332
-
333
- if (cached) return cached;
334
-
335
- const spans = pageText(page, textMeasure);
336
-
337
- texts.set(page, spans);
338
-
339
- return spans;
340
- },
341
- target: (name: string) => {
342
- projection.value ??= createYrsPositionProjection(session, "body");
343
-
344
- const position = projection.value?.bookmarkPosition(name) ?? undefined;
345
-
346
- if (position !== undefined)
347
- return positionTarget(retained.frame.displayList.pages, position, built);
348
-
349
- // Word's reserved bookmark for the start of the document.
350
- return name === "_top" ? { index: 0, y: 0 } : undefined;
351
- },
352
- };
353
-}
354
-
355
-function pageSize(page: DisplayPage): WordPageSize {
356
- return { width: page.width, height: page.height, background: page.background };
357
-}
358
-
359
-/** Measures the text layer's font with a detached canvas; undefined where the worker offers no 2D context. */
360
-function layerMeasure(): TextMeasure | undefined {
361
- const context = new OffscreenCanvas(1, 1).getContext("2d");
362
-
363
- if (!context) return undefined;
364
-
365
- // Measured large and scaled down, so rounding stays well below a pixel at any zoom.
366
- const size = 100;
367
-
368
- context.font = `${size}px ${layerFont}`;
369
-
370
- const metrics = context.measureText("Hg");
371
-
372
- return {
373
- width: (text) => context.measureText(text).width / size,
374
- ascent: metrics.fontBoundingBoxAscent / size,
375
- descent: metrics.fontBoundingBoxDescent / size,
376
- };
377
-}
apps/web/src/components/files/office/presentation.worker.ts
+2
-8
@@ -10,14 +10,8 @@ import {
10
type SlidePrimitive,
11
} from "@betteroffice/pptx";
12
import { slideFonts } from "./slide-fonts";
13
-import {
14
- maxImageSide,
15
- type SlideMethods,
16
- type SlidePainted,
17
- type SlideSummary,
18
- type VectorBitmap,
19
- type VectorRequest,
20
-} from "./slide-protocol";
13
+import type { SlideMethods, SlidePainted, SlideSummary } from "./slide-protocol";
14
+import { maxImageSide, type VectorBitmap, type VectorRequest } from "./vector-pictures";
15
import { deckText } from "./slide-text";
16
import { officeImageBitmap } from "./image-bitmap";
17
import { serveWorker, Transfer } from "./worker-rpc";
apps/web/src/components/files/office/slide-protocol.ts
+1
-13
@@ -1,9 +1,7 @@
1
// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
2
+import type { VectorBitmap, VectorRequest } from "./vector-pictures";
3
import type { Method } from "./worker-rpc";
4
4
-/** The longest side a decoded picture keeps: enough for a full-width slide on a high-density screen. */
5
-export const maxImageSide = 2560;
6
-
5
/** What the window shows of one slide besides its bitmap. */
6
export type SlideSummary = {
7
/** In CSS pixels. */
@@ -13,16 +11,6 @@ export type SlideSummary = {
11
readonly notes: string | undefined;
12
};
13
16
-/** An SVG picture the worker cannot decode, which the window rasterizes at `size`, or at its own size when absent. */
17
-export type VectorRequest = {
18
- readonly asset: string;
19
- readonly blob: Blob;
20
- readonly size: { readonly width: number; readonly height: number } | undefined;
21
-};
22
-
23
-/** A rasterized SVG picture, or none when the window could not decode it either. */
24
-export type VectorBitmap = { readonly asset: string; readonly bitmap: ImageBitmap | undefined };
25
-
14
export type SlidePainted =
15
| {
16
readonly kind: "painted";
apps/web/src/components/files/office/vector-pictures.ts
new
+41
@@ -0,0 +1,41 @@
1
+// SVG pictures, which only an image element decodes. Workers have none, so the window rasterizes them for the worker.
2
+
3
+/** The longest side a decoded picture keeps: enough for a full-width page or slide on a high-density screen. */
4
+export const maxImageSide = 2560;
5
+
6
+/** An SVG picture the worker cannot decode, which the window rasterizes at `size`, or at its own size when absent. */
7
+export type VectorRequest = {
8
+ readonly asset: string;
9
+ readonly blob: Blob;
10
+ readonly size: { readonly width: number; readonly height: number } | undefined;
11
+};
12
+
13
+/** A rasterized SVG picture, or none when the window could not decode it either. */
14
+export type VectorBitmap = { readonly asset: string; readonly bitmap: ImageBitmap | undefined };
15
+
16
+/** Rasterizes a worker's SVG picture in the window. */
17
+export async function rasterize(request: VectorRequest): Promise<VectorBitmap> {
18
+ const url = URL.createObjectURL(request.blob);
19
+ const image = new Image();
20
+ image.src = url;
21
+ try {
22
+ await image.decode();
23
+ const shrink = Math.min(1, maxImageSide / Math.max(image.naturalWidth, image.naturalHeight));
24
+ const size = request.size ?? {
25
+ width: Math.max(1, Math.round(image.naturalWidth * shrink)),
26
+ height: Math.max(1, Math.round(image.naturalHeight * shrink)),
27
+ };
28
+ return {
29
+ asset: request.asset,
30
+ bitmap: await createImageBitmap(image, {
31
+ resizeWidth: size.width,
32
+ resizeHeight: size.height,
33
+ resizeQuality: "high",
34
+ }),
35
+ };
36
+ } catch {
37
+ return { asset: request.asset, bitmap: undefined };
38
+ } finally {
39
+ URL.revokeObjectURL(url);
40
+ }
41
+}
apps/web/src/components/files/office/word-document.browser.test.ts
new
+84
@@ -0,0 +1,84 @@
1
+import JSZip from "jszip";
2
+import { expect, it, vi } from "vite-plus/test";
3
+import type { DisplayPage, GlyphRunPrimitive } from "@betteroffice/docx/layout/render";
4
+import { openWordDocument } from "./word-document";
5
+import { withWholeMissingGlyphs } from "./word-glyphs";
6
+
7
+const ns = 'xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"';
8
+
9
+function relationship(id: string, type: string, target: string) {
10
+ return `<Relationship Id="${id}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/${type}" Target="${target}"/>`;
11
+}
12
+
13
+/** A document with a numbered Calibri paragraph and an Arial paragraph of Thai, which no bundled face covers. */
14
+function document_() {
15
+ const run = (font: string, text: string) =>
16
+ `<w:r><w:rPr><w:rFonts w:ascii="${font}" w:hAnsi="${font}" w:cs="${font}"/></w:rPr><w:t>${text}</w:t></w:r>`;
17
+
18
+ return new JSZip()
19
+ .file(
20
+ "[Content_Types].xml",
21
+ '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/><Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/></Types>',
22
+ )
23
+ .file(
24
+ "_rels/.rels",
25
+ `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${relationship("rId1", "officeDocument", "word/document.xml")}</Relationships>`,
26
+ )
27
+ .file(
28
+ "word/_rels/document.xml.rels",
29
+ `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${relationship("rId1", "numbering", "numbering.xml")}</Relationships>`,
30
+ )
31
+ .file(
32
+ "word/numbering.xml",
33
+ `<w:numbering ${ns}><w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/></w:rPr></w:lvl></w:abstractNum><w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num></w:numbering>`,
34
+ )
35
+ .file(
36
+ "word/document.xml",
37
+ `<w:document ${ns}><w:body><w:p><w:pPr><w:numPr><w:ilvl w:val="0"/><w:numId w:val="1"/></w:numPr></w:pPr>${run("Calibri", "Numbered")}</w:p><w:p>${run("Arial", "ภาษาไทย")}</w:p><w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/></w:sectPr></w:body></w:document>`,
38
+ )
39
+ .generateAsync({ type: "uint8array" });
40
+}
41
+
42
+it("draws list numbers with the document's faces, and text no bundled face covers with the system's", async () => {
43
+ const opened = await openWordDocument(await document_(), document.fonts);
44
+ const drawn: { text: string; font: string }[] = [];
45
+ using _fillText = vi
46
+ .spyOn(OffscreenCanvasRenderingContext2D.prototype, "fillText")
47
+ .mockImplementation(function (this: OffscreenCanvasRenderingContext2D, text) {
48
+ drawn.push({ text, font: this.font });
49
+ });
50
+
51
+ await opened.paint(0, 1, 1, new AbortController().signal);
52
+
53
+ expect(drawn.map((call) => call.text)).toEqual(expect.arrayContaining(["1.", "ภาษาไทย"]));
54
+ expect(drawn.find((call) => call.text === "1.")?.font).toContain("Calibri");
55
+ expect([...document.fonts].map((face) => face.family.replaceAll('"', ""))).toContain("Calibri");
56
+});
57
+
58
+it("joins missing glyphs only across runs styled alike, with clusters into the joined text", () => {
59
+ const run = (text: string, at: number, style: Partial<GlyphRunPrimitive> = {}) =>
60
+ ({
61
+ kind: "glyphRun",
62
+ fontId: 2,
63
+ size: 16,
64
+ color: "#000000",
65
+ text,
66
+ glyphs: [{ id: 0, x: at * 10, y: 20, cluster: 0, advance: 10 }],
67
+ docStart: at,
68
+ docEnd: at + 1,
69
+ ...style,
70
+ }) satisfies GlyphRunPrimitive;
71
+ const page = {
72
+ width: 100,
73
+ height: 100,
74
+ primitives: [run("ภ", 0), run("า", 1), run("ษ", 2, { textOutline: true })],
75
+ } as unknown as DisplayPage;
76
+ const measure = new OffscreenCanvas(1, 1).getContext("2d")!;
77
+
78
+ const [joined, outlined] = withWholeMissingGlyphs(page, measure)
79
+ .primitives as GlyphRunPrimitive[];
80
+
81
+ expect(joined?.text).toBe("ภา");
82
+ expect(joined?.glyphs.map((glyph) => glyph.cluster)).toEqual([0, 3]);
83
+ expect(outlined).toMatchObject({ text: "ษ", textOutline: true });
84
+});
apps/web/src/components/files/office/word-document.ts
new
+430
@@ -0,0 +1,430 @@
1
+// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
2
+import * as Schema from "effect/Schema";
3
+import {
4
+ buildResidentRegionLayoutRequest,
5
+ getLayoutKernelInputs,
6
+ workerLayoutComputation,
7
+} from "@betteroffice/docx/editor";
8
+import { createRustMeasureSource } from "@betteroffice/docx/layout";
9
+import {
10
+ applyFrameDelta,
11
+ decodeFrameDelta,
12
+ encodeDisplayListFrameExtras,
13
+ GlyphCache,
14
+ rasterizeDisplayPageToBackBuffer,
15
+ type DisplayPage,
16
+ type RetainedFrame,
17
+} from "@betteroffice/docx/layout/render";
18
+import {
19
+ createYrsPositionProjection,
20
+ createYrsSession,
21
+ type YrsPositionProjection,
22
+} from "@betteroffice/docx/yrs";
23
+import { loadFace, sheetFace, wordFonts } from "./fonts";
24
+import { maxImageSide, type VectorBitmap } from "./vector-pictures";
25
+import { withWholeMissingGlyphs } from "./word-glyphs";
26
+import { createBitmapImageResolver } from "./word-images";
27
+import { layerFont, type WordPageSize, type WordSpan } from "./word-protocol";
28
+import { pageText, positionTarget, type TextMeasure } from "./word-text";
29
+
30
+// An open Word document: its engine session, fonts, layout, built pages and painting. The document worker holds one.
31
+
32
+const FontRequirements = Schema.fromJsonString(
33
+ Schema.Array(
34
+ Schema.Struct({
35
+ key: Schema.String,
36
+ family: Schema.String,
37
+ bold: Schema.Boolean,
38
+ italic: Schema.Boolean,
39
+ scripts: Schema.optional(
40
+ Schema.Array(Schema.Literals(["cjk-sc", "cjk-tc", "cjk-jp", "cjk-kr", "arabic", "hebrew"])),
41
+ ),
42
+ }),
43
+ ),
44
+);
45
+
46
+const decodeFontRequirements = Schema.decodeUnknownSync(FontRequirements);
47
+
48
+/** A prefix layout's reply marks itself provisional when the document goes on past it. */
49
+const decodeLayoutReply = Schema.decodeUnknownSync(
50
+ Schema.fromJsonString(Schema.Struct({ provisional: Schema.optional(Schema.Boolean) })),
51
+);
52
+
53
+/** Pages laid out and built before the first paint; later pages are built as they near the viewport. */
54
+const firstPages = 3;
55
+
56
+/** How long one layout step may hold back a paint that waits behind it, in milliseconds. */
57
+const stepBudget = 24;
58
+
59
+/**
60
+ * How many pages either side of the page painted last stay built. A built page holds about 5 MB in the engine and
61
+ * builds again in about 100 ms. This keeps every page near the viewport, which paints a viewport ahead in both
62
+ * directions, and lets a reader scroll back a few screens without waiting, while a long read holds at most 21 pages.
63
+ */
64
+const keptAround = 10;
65
+
66
+/** A value built on first use. */
67
+type Lazy<T> = { value: T | undefined };
68
+
69
+/**
70
+ * Opens the document and lays out its first pages; the rest lay out a `step` at a time. `fonts` is the font set the
71
+ * painting canvas draws text with, if it has one.
72
+ */
73
+export async function openWordDocument(bytes: Uint8Array, fonts: FontFaceSet | undefined) {
74
+ const session = await createYrsSession();
75
+ const document = session.openDocx(bytes, true, { mediaTokens: true }).document;
76
+ const settings = document.package.settings;
77
+
78
+ const measure = createRustMeasureSource({
79
+ engine: {
80
+ registerFont: (font) => session.registerFont(font),
81
+ registerSubstituteFont: (id, family) => session.registerSubstituteFont(id, family),
82
+ clearFonts: () => session.clearFonts(),
83
+ },
84
+ bundled: wordFonts(),
85
+ });
86
+
87
+ measure.setCompat(settings?.compatibilityFlags);
88
+
89
+ const request = buildResidentRegionLayoutRequest(document, 0, {
90
+ themeColors: Object.fromEntries(
91
+ Object.entries(document.package.theme?.colorScheme ?? {}).filter(
92
+ (entry): entry is [string, string] => entry[1] !== undefined,
93
+ ),
94
+ ),
95
+ defaultTabStopTwips: settings?.defaultTabStop ?? null,
96
+ numericIds: {},
97
+ mediaTokens: true,
98
+ });
99
+
100
+ const requirements = decodeFontRequirements(
101
+ session.layoutFontRequirementsJson(JSON.stringify(request)),
102
+ ).map(({ scripts, ...requirement }) => ({
103
+ ...requirement,
104
+ ...(scripts ? { scripts: [...scripts] } : {}),
105
+ }));
106
+
107
+ await Promise.all([
108
+ measure.prepareFontRequirements(requirements),
109
+ fonts && addCanvasFaces(fonts, requirements),
110
+ ]);
111
+
112
+ const measurement = measure.measurementConfigForRequirements(requirements);
113
+
114
+ if (!measurement) throw new Error("The document's fonts could not be prepared");
115
+
116
+ const input = JSON.stringify({ ...request, measurement });
117
+
118
+ // Word shows resolved comments without the active highlight.
119
+ const resolvedCommentIds = (document.package.document.comments ?? [])
120
+ .filter(
121
+ (comment) =>
122
+ (comment.done || comment.status === "resolved") && comment.parentId === undefined,
123
+ )
124
+ .map((comment) => comment.id);
125
+
126
+ // The session keeps the layout it last ran and builds display frames from it: only the display extras go in, and a
127
+ // binary frame comes back with the window's pages built and every other page a placeholder carrying its geometry.
128
+ const display = (previous: RetainedFrame | null, reply: string) => {
129
+ const layout = workerLayoutComputation(reply).layout;
130
+
131
+ session.setDisplayWindow(0, firstPages);
132
+
133
+ const extras = encodeDisplayListFrameExtras({
134
+ measured: [],
135
+ options: {},
136
+ layout,
137
+ fontChains: measurement.fontChains,
138
+ ...(getLayoutKernelInputs(layout)?.headersFooters
139
+ ? { headersFooters: getLayoutKernelInputs(layout)!.headersFooters! }
140
+ : {}),
141
+ resolvedCommentIds,
142
+ });
143
+
144
+ return applyFrameDelta(
145
+ previous,
146
+ decodeFrameDelta(session.buildDisplayListFrame(extras, previous?.frameEpoch ?? 0)),
147
+ );
148
+ };
149
+
150
+ // Only as much of the body as fills the first pages; a long document goes on past it.
151
+ const prefix = session.layoutDocumentWithRegionsPrefixRetainedJson(input, firstPages);
152
+ const retained = { frame: display(null, prefix) };
153
+
154
+ if (retained.frame.displayList.pages.length === 0)
155
+ throw new Error("The document produced no pages");
156
+
157
+ // The region layout that finishes the document: begun on the first step, `cost` the running average milliseconds a
158
+ // body block takes.
159
+ const layout = { loading: decodeLayoutReply(prefix).provisional ?? false, begun: false, cost: 3 };
160
+
161
+ // Builds a page's content when it is needed and not built, the first time or again after `release`.
162
+ const built = (index: number) => {
163
+ const page = retained.frame.displayList.pages[index];
164
+
165
+ if (!page?.unbuilt) return page;
166
+
167
+ retained.frame = applyFrameDelta(
168
+ retained.frame,
169
+ decodeFrameDelta(session.buildDisplayPagesFrame([index], retained.frame.frameEpoch)),
170
+ );
171
+
172
+ return retained.frame.displayList.pages[index];
173
+ };
174
+
175
+ // Gives back the built pages far from the page about to paint, so a long read keeps only the pages around the
176
+ // viewport. A released page keeps its geometry and document positions, which bookmarks search, and builds again
177
+ // when it is needed.
178
+ const release = (painted: number) => {
179
+ // The engine releases pages of the whole document's layout only, and few pages show before it.
180
+ if (layout.loading) return;
181
+
182
+ const far = retained.frame.displayList.pages.flatMap((page, index) =>
183
+ !page.unbuilt && Math.abs(painted - index) > keptAround ? [index] : [],
184
+ );
185
+
186
+ if (far.length === 0) return;
187
+
188
+ const frame = session.releaseDisplayPagesFrame(far, retained.frame.frameEpoch);
189
+
190
+ // A superseded release changes nothing; the next one tries again.
191
+ if (frame) retained.frame = applyFrameDelta(retained.frame, decodeFrameDelta(frame));
192
+ };
193
+
194
+ // The whole document's layout replaces the prefix's frame.
195
+ const complete = (reply: string) => {
196
+ const before = retained.frame.displayList.pages;
197
+
198
+ retained.frame = display(retained.frame, reply);
199
+ layout.loading = false;
200
+
201
+ const pages = retained.frame.displayList.pages;
202
+
203
+ return {
204
+ done: true as const,
205
+ pages: pages.map(pageSize),
206
+ kept: pages.map((page, index) => {
207
+ const was = before[index];
208
+
209
+ return was === page || (!!was?.unbuilt && !!page.unbuilt);
210
+ }),
211
+ };
212
+ };
213
+
214
+ const glyphCache = new GlyphCache({
215
+ // The engine sets glyphs no bundled face has, such as Thai ones or emoji, as missing glyphs, which outline as empty
216
+ // boxes. A run whose outlines fail paints whole with the canvas's fonts instead, which the system's cover.
217
+ provider: (font, glyph) => {
218
+ if (glyph === 0) throw new Error("No bundled face has this glyph");
219
+
220
+ return session.outlineGlyphJson(font, glyph);
221
+ },
222
+ });
223
+ const images = createBitmapImageResolver((token) => session.mediaSource(token));
224
+ const surface = new OffscreenCanvas(1, 1);
225
+ const fitting = new OffscreenCanvas(1, 1).getContext("2d");
226
+ const painted = new WeakMap<DisplayPage, DisplayPage>();
227
+ const textMeasure = layerMeasure();
228
+ const texts = new WeakMap<DisplayPage, readonly WordSpan[]>();
229
+ // Built on the first followed bookmark: most documents are read without one.
230
+ const projection: Lazy<YrsPositionProjection | null> = { value: undefined };
231
+
232
+ return {
233
+ pages: () => retained.frame.displayList.pages,
234
+ loading: () => layout.loading,
235
+ built,
236
+ /**
237
+ * Lays out about `stepBudget` milliseconds more of the body. Blocks vary widely, and sizing a step by the last one
238
+ * alone overshoots after a run of cheap blocks.
239
+ */
240
+ step: () => {
241
+ if (!layout.loading) {
242
+ const pages = retained.frame.displayList.pages;
243
+
244
+ return { done: true as const, pages: pages.map(pageSize), kept: pages.map(() => true) };
245
+ }
246
+
247
+ if (!layout.begun) {
248
+ layout.begun = true;
249
+
250
+ const begun = session.beginRegionLayout(input);
251
+
252
+ return begun.layoutJson === undefined
253
+ ? { done: false as const }
254
+ : complete(begun.layoutJson);
255
+ }
256
+
257
+ const blocks = Math.min(8192, Math.max(1, Math.round(stepBudget / layout.cost)));
258
+ const started = performance.now();
259
+ const progress = session.resumeRegionLayout(blocks);
260
+
261
+ layout.cost = layout.cost * 0.7 + ((performance.now() - started) / blocks) * 0.3;
262
+
263
+ return progress.layoutJson === undefined
264
+ ? { done: false as const }
265
+ : complete(progress.layoutJson);
266
+ },
267
+ paint: async (index: number, scale: number, ratio: number, signal: AbortSignal) => {
268
+ // A page that scrolled away before its paint began, or while it rasterized, needs no bitmap.
269
+ if (signal.aborted) return undefined;
270
+
271
+ // Released first, so the page builds in the memory they free.
272
+ release(index);
273
+
274
+ const page = built(index);
275
+
276
+ if (!page) return undefined;
277
+
278
+ const paintable =
279
+ painted.get(page) ?? (fitting ? withWholeMissingGlyphs(page, fitting) : page);
280
+
281
+ painted.set(page, paintable);
282
+
283
+ // The window drew image elements, which shrink smoothly at the default quality; a bitmap needs medium quality to
284
+ // look the same. Sizing the surface first keeps the setting: the painter resizes it, which resets the context,
285
+ // only when its size differs.
286
+ const context = surface.getContext("2d");
287
+ const width = Math.ceil(page.width * ratio * scale);
288
+ const height = Math.ceil(page.height * ratio * scale);
289
+
290
+ if (surface.width !== width) surface.width = width;
291
+
292
+ if (surface.height !== height) surface.height = height;
293
+
294
+ if (context) context.imageSmoothingQuality = "medium";
295
+
296
+ await rasterizeDisplayPageToBackBuffer(
297
+ surface,
298
+ paintable,
299
+ { glyphCache, resolveImage: images.resolve },
300
+ ratio,
301
+ scale,
302
+ );
303
+
304
+ const vectors = images.vectors(pictureSizes(paintable, ratio * scale));
305
+
306
+ images.trim();
307
+
308
+ if (signal.aborted) return undefined;
309
+
310
+ return { bitmap: surface.transferToImageBitmap(), vectors };
311
+ },
312
+ vectors: (bitmaps: readonly VectorBitmap[]) => images.provide(bitmaps),
313
+ text: (index: number) => {
314
+ const page = built(index);
315
+
316
+ if (!page || !textMeasure) return [];
317
+
318
+ const cached = texts.get(page);
319
+
320
+ if (cached) return cached;
321
+
322
+ const spans = pageText(page, textMeasure);
323
+
324
+ texts.set(page, spans);
325
+
326
+ return spans;
327
+ },
328
+ target: (name: string) => {
329
+ projection.value ??= createYrsPositionProjection(session, "body");
330
+
331
+ const position = projection.value?.bookmarkPosition(name) ?? undefined;
332
+
333
+ if (position !== undefined)
334
+ return positionTarget(retained.frame.displayList.pages, position, built);
335
+
336
+ // Word's reserved bookmark for the start of the document.
337
+ return name === "_top" ? { index: 0, y: 0 } : undefined;
338
+ },
339
+ };
340
+}
341
+
342
+/**
343
+ * The canvas draws list numbers, and runs no bundled face has glyphs for, with its own fonts, by their Word family.
344
+ * Adding the document's faces under those names draws them like the rest of its text. A family the app ships no face
345
+ * for stays with the system's, and CJK faces, tens of megabytes each, are not held twice.
346
+ */
347
+async function addCanvasFaces(
348
+ fonts: FontFaceSet,
349
+ requirements: readonly { family: string; bold: boolean; italic: boolean }[],
350
+) {
351
+ const faces = new Map<string, Promise<FontFace>>();
352
+
353
+ for (const { family, bold, italic } of requirements) {
354
+ const face = sheetFace(family, bold, italic);
355
+
356
+ if (!face || face.script?.startsWith("cjk-")) continue;
357
+
358
+ const key = `${family}\u0000${face.weight}\u0000${face.style}`;
359
+
360
+ if (faces.has(key)) continue;
361
+
362
+ // A family without the requested style gets the face it has, which the browser then slants or emboldens.
363
+ faces.set(
364
+ key,
365
+ loadFace(face).then((source) =>
366
+ new FontFace(family, source, {
367
+ weight: face.weight === 700 ? "700" : "400",
368
+ style: face.style === "italic" ? "italic" : "normal",
369
+ }).load(),
370
+ ),
371
+ );
372
+ }
373
+
374
+ await Promise.all(
375
+ [...faces.values()].map((face) =>
376
+ face.then((loaded) => void fonts.add(loaded)).catch(() => undefined),
377
+ ),
378
+ );
379
+}
380
+
381
+/** Each picture's drawn size on a page in device pixels at `density`, up to `maxImageSide`. */
382
+function pictureSizes(page: DisplayPage, density: number) {
383
+ const sizes = new Map<string, { width: number; height: number }>();
384
+ const primitives = [
385
+ ...page.primitives,
386
+ ...(page.header?.primitives ?? []),
387
+ ...(page.footer?.primitives ?? []),
388
+ ...(page.noteAreas ?? []).flatMap((area) => area.primitives ?? []),
389
+ ];
390
+
391
+ for (const primitive of primitives) {
392
+ if (primitive.kind !== "image") continue;
393
+
394
+ const width = (primitive.contentFrame?.w ?? primitive.w) * density;
395
+ const height = (primitive.contentFrame?.h ?? primitive.h) * density;
396
+ const shrink = Math.min(1, maxImageSide / Math.max(width, height));
397
+ const previous = sizes.get(primitive.relId);
398
+
399
+ sizes.set(primitive.relId, {
400
+ width: Math.max(previous?.width ?? 1, Math.round(width * shrink)),
401
+ height: Math.max(previous?.height ?? 1, Math.round(height * shrink)),
402
+ });
403
+ }
404
+
405
+ return sizes;
406
+}
407
+
408
+export function pageSize(page: DisplayPage): WordPageSize {
409
+ return { width: page.width, height: page.height, background: page.background };
410
+}
411
+
412
+/** Measures the text layer's font with a detached canvas; undefined where the worker offers no 2D context. */
413
+function layerMeasure(): TextMeasure | undefined {
414
+ const context = new OffscreenCanvas(1, 1).getContext("2d");
415
+
416
+ if (!context) return undefined;
417
+
418
+ // Measured large and scaled down, so rounding stays well below a pixel at any zoom.
419
+ const size = 100;
420
+
421
+ context.font = `${size}px ${layerFont}`;
422
+
423
+ const metrics = context.measureText("Hg");
424
+
425
+ return {
426
+ width: (text) => context.measureText(text).width / size,
427
+ ascent: metrics.fontBoundingBoxAscent / size,
428
+ descent: metrics.fontBoundingBoxDescent / size,
429
+ };
430
+}
apps/web/src/components/files/office/word-glyphs.ts
new
+126
@@ -0,0 +1,126 @@
1
+import type {
2
+ DisplayPage,
3
+ DisplayPrimitive,
4
+ GlyphRunPrimitive,
5
+} from "@betteroffice/docx/layout/render";
6
+
7
+/**
8
+ * The page as the canvas paints it. The engine sets each glyph no bundled face has, such as Thai or Devanagari ones and
9
+ * emoji, as a run of its own, which the canvas draws with the system's fonts. Neighbouring runs join here, so the
10
+ * canvas shapes their text whole and marks join their letters. A run wider than the room the engine left it shrinks
11
+ * into that room, rather than over the text after it.
12
+ */
13
+export function withWholeMissingGlyphs(
14
+ page: DisplayPage,
15
+ measure: OffscreenCanvasRenderingContext2D,
16
+): DisplayPage {
17
+ const regions = [
18
+ page.primitives,
19
+ page.header?.primitives,
20
+ page.footer?.primitives,
21
+ ...(page.noteAreas ?? []).map((area) => area.primitives),
22
+ ];
23
+
24
+ if (!regions.some((primitives) => primitives?.some(missing))) return page;
25
+
26
+ const join = (primitives: readonly DisplayPrimitive[]) =>
27
+ primitives
28
+ .reduce<DisplayPrimitive[]>((joined, primitive) => {
29
+ const previous = joined.at(-1);
30
+
31
+ if (missing(previous) && missing(primitive) && continues(previous, primitive))
32
+ joined[joined.length - 1] = {
33
+ ...previous,
34
+ text: previous.text + primitive.text,
35
+ glyphs: [...previous.glyphs, ...shifted(primitive.glyphs, previous.text)],
36
+ ...(primitive.docEnd === undefined ? {} : { docEnd: primitive.docEnd }),
37
+ };
38
+ else joined.push(primitive);
39
+
40
+ return joined;
41
+ }, [])
42
+ .map((primitive) => (missing(primitive) ? fitted(primitive, measure) : primitive));
43
+
44
+ // Watermark primitives lead the body and count apart, so they join apart.
45
+ const marks = join(page.primitives.slice(0, page.watermarkPrimitiveCount ?? 0));
46
+
47
+ return {
48
+ ...page,
49
+ primitives: [...marks, ...join(page.primitives.slice(page.watermarkPrimitiveCount ?? 0))],
50
+ ...(page.watermarkPrimitiveCount === undefined
51
+ ? {}
52
+ : { watermarkPrimitiveCount: marks.length }),
53
+ ...(page.header
54
+ ? { header: { ...page.header, primitives: join(page.header.primitives) } }
55
+ : {}),
56
+ ...(page.footer
57
+ ? { footer: { ...page.footer, primitives: join(page.footer.primitives) } }
58
+ : {}),
59
+ ...(page.noteAreas
60
+ ? {
61
+ noteAreas: page.noteAreas.map((area) =>
62
+ area.primitives ? { ...area, primitives: join(area.primitives) } : area,
63
+ ),
64
+ }
65
+ : {}),
66
+ };
67
+}
68
+
69
+function missing(primitive: DisplayPrimitive | undefined): primitive is GlyphRunPrimitive {
70
+ return (
71
+ primitive?.kind === "glyphRun" && !primitive.rtl && primitive.glyphs.some((glyph) => !glyph.id)
72
+ );
73
+}
74
+
75
+/** Neighbours in the document on one baseline whose runs differ only in their text and where it sits. */
76
+function continues(previous: GlyphRunPrimitive, next: GlyphRunPrimitive) {
77
+ return (
78
+ previous.docEnd !== undefined &&
79
+ previous.docEnd === next.docStart &&
80
+ previous.glyphs[0]?.y === next.glyphs[0]?.y &&
81
+ style(previous) === style(next)
82
+ );
83
+}
84
+
85
+function style(run: GlyphRunPrimitive) {
86
+ return JSON.stringify({
87
+ ...run,
88
+ text: undefined,
89
+ glyphs: undefined,
90
+ docStart: undefined,
91
+ docEnd: undefined,
92
+ logicalOrder: undefined,
93
+ });
94
+}
95
+
96
+/** Glyphs whose clusters, UTF-8 offsets into their run's text, now follow `before`. */
97
+function shifted(glyphs: GlyphRunPrimitive["glyphs"], before: string) {
98
+ const offset = new TextEncoder().encode(before).length;
99
+
100
+ return glyphs.map((glyph) => ({ ...glyph, cluster: glyph.cluster + offset }));
101
+}
102
+
103
+function fitted(run: GlyphRunPrimitive, measure: OffscreenCanvasRenderingContext2D) {
104
+ const first = run.glyphs[0];
105
+ const last = run.glyphs.at(-1);
106
+
107
+ if (!first || !last) return run;
108
+
109
+ const room = last.x + (last.advance ?? 0) - first.x;
110
+ const font = run.fallbackFont ?? `${run.size}px sans-serif`;
111
+
112
+ measure.font = font;
113
+
114
+ const width = measure.measureText(run.text).width;
115
+
116
+ if (width <= room || room <= 0) return run;
117
+
118
+ // Smaller rather than narrower, so emoji keep their shape.
119
+ return {
120
+ ...run,
121
+ fallbackFont: font.replace(
122
+ /(\d+(?:\.\d+)?)px/u,
123
+ (_, size) => `${(Number(size) * room) / width}px`,
124
+ ),
125
+ };
126
+}
apps/web/src/components/files/office/word-images.browser.test.ts
new
+24
@@ -0,0 +1,24 @@
1
+import { expect, it } from "vite-plus/test";
2
+import { createBitmapImageResolver } from "./word-images";
3
+
4
+it("asks the window to rasterize SVG pictures at their drawn size, and draws the bitmaps it returns", async () => {
5
+ const svg = new TextEncoder().encode(
6
+ '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"><rect width="10" height="10"/></svg>',
7
+ );
8
+ const images = createBitmapImageResolver(() => ({ bytes: svg, mimeType: "image/svg+xml" }));
9
+ const sizes = new Map([["media:1", { width: 40, height: 20 }]]);
10
+
11
+ expect(await images.resolve("media:1")).toBeNull();
12
+
13
+ const [request, ...rest] = images.vectors(sizes);
14
+
15
+ expect(rest).toEqual([]);
16
+ expect(request).toMatchObject({ asset: "media:1", size: { width: 40, height: 20 } });
17
+
18
+ const bitmap = await createImageBitmap(new ImageData(40, 20));
19
+
20
+ images.provide([{ asset: "media:1", bitmap }]);
21
+
22
+ expect(await images.resolve("media:1")).toBe(bitmap);
23
+ expect(images.vectors(sizes)).toEqual([]);
24
+});
apps/web/src/components/files/office/word-images.ts
+79
-18
@@ -2,6 +2,7 @@
2
import type { ImageResolver } from "@betteroffice/docx/layout/render";
3
import type { YrsMediaSource } from "@betteroffice/docx/yrs";
4
import { officeImageBitmap } from "./image-bitmap";
5
+import type { VectorBitmap, VectorRequest } from "./vector-pictures";
6
7
/** An embedded image's source, which names a part of the package the session reads. */
8
const mediaToken = /^media:(0|[1-9]\d*)$/u;
@@ -9,23 +10,28 @@ const mediaToken = /^media:(0|[1-9]\d*)$/u;
10
/** How many bytes of decoded images stay for repaints; the least recently drawn go first past it. */
11
const budget = 256 * 1024 * 1024;
12
13
+type Size = { readonly width: number; readonly height: number };
14
+
15
type Decoded = {
13
- readonly image: Promise<CanvasImageSource | null>;
16
+ image: Promise<CanvasImageSource | null>;
17
/** The decoded image once it is one; the shared placeholder is never closed. */
18
bitmap: ImageBitmap | undefined;
19
+ /** An SVG picture, which the window rasterizes into `bitmap`; `failed` once it could not. */
20
+ vector: { readonly blob: Blob; failed: boolean } | undefined;
21
};
22
23
/**
19
- * Resolves the display list's images in a worker, where there is no `Image` element: a `media:{n}` source decodes
20
- * from the bytes the session reads, and a `data:` or `blob:` source decodes in place. Anything else, such as a remote
21
- * address, resolves to nothing, so painting never makes a request. A part that is missing or cannot be decoded paints a
22
- * grey box, as the window's resolver does. Decoded images stay for repaints within `budget`.
24
+ * Resolves the display list's images in a worker: `media:{n}` sources decode from the session's bytes, `data:` and
25
+ * `blob:` ones in place, and nothing else, so painting never makes a request. Undecodable parts paint a grey box. SVG
26
+ * pictures, which the engine converts WMF and EMF ones to, need the window: `vectors` lists them, `provide` takes them.
27
*/
28
export function createBitmapImageResolver(media: (token: string) => YrsMediaSource | null) {
29
const cache = new Map<string, Decoded>();
30
const placeholder = greyBox();
31
+ // The SVG pictures the paint since the last `vectors` drew.
32
+ const drawn = new Set<string>();
33
28
- const decode = (source: string): Promise<CanvasImageSource | null> => {
34
+ const decode = (source: string, entry: Decoded): Promise<CanvasImageSource | null> => {
35
const token = mediaToken.test(source);
36
const found = token ? media(source) : undefined;
37
@@ -35,10 +41,18 @@ export function createBitmapImageResolver(media: (token: string) => YrsMediaSour
41
? Promise.resolve(new Blob([new Uint8Array(found.bytes)], { type: found.mimeType }))
42
: fetch(source).then((response) => response.blob());
43
38
- return blob.then(officeImageBitmap).then(
39
- (bitmap): CanvasImageSource => bitmap,
40
- () => (token ? placeholder : null),
41
- );
44
+ return blob.then((decoded) => {
45
+ if (decoded.type === "image/svg+xml") {
46
+ entry.vector = { blob: decoded, failed: false };
47
+
48
+ return null;
49
+ }
50
+
51
+ return officeImageBitmap(decoded).then(
52
+ (bitmap): CanvasImageSource => bitmap,
53
+ () => (token ? placeholder : null),
54
+ );
55
+ });
56
};
57
58
const resolve: ImageResolver = (source) => {
@@ -52,18 +66,22 @@ export function createBitmapImageResolver(media: (token: string) => YrsMediaSour
66
cache.delete(source);
67
cache.set(source, cached);
68
55
- return cached.image;
69
+ if (cached.vector) drawn.add(source);
70
+
71
+ return cached.vector
72
+ ? Promise.resolve(cached.bitmap ?? (cached.vector.failed ? placeholder : null))
73
+ : cached.image;
74
}
75
58
- const entry: Decoded = {
59
- image: decode(source).then((image) => {
60
- if (image instanceof ImageBitmap) entry.bitmap = image;
76
+ const entry: Decoded = { image: Promise.resolve(null), bitmap: undefined, vector: undefined };
77
+
78
+ entry.image = decode(source, entry).then((decoded) => {
79
+ if (decoded instanceof ImageBitmap) entry.bitmap = decoded;
80
62
- return image;
63
- }),
64
- bitmap: undefined,
65
- };
81
+ if (entry.vector) drawn.add(source);
82
83
+ return decoded;
84
+ });
85
cache.set(source, entry);
86
87
return entry.image;
@@ -71,6 +89,45 @@ export function createBitmapImageResolver(media: (token: string) => YrsMediaSour
89
90
return {
91
resolve,
92
+ /**
93
+ * The SVG pictures the paints since the last call drew without a bitmap, or with one smaller than `sizes` asks, at
94
+ * the size to rasterize them; a picture absent from `sizes` rasterizes at its own size.
95
+ */
96
+ vectors(sizes: ReadonlyMap<string, Size>): VectorRequest[] {
97
+ const requests = [...drawn].flatMap((source) => {
98
+ const entry = cache.get(source);
99
+ const size = sizes.get(source);
100
+
101
+ if (!entry?.vector || entry.vector.failed) return [];
102
+
103
+ if (entry.bitmap && (!size || covers(entry.bitmap, size))) return [];
104
+
105
+ return [{ asset: source, blob: entry.vector.blob, size }];
106
+ });
107
+
108
+ drawn.clear();
109
+
110
+ return requests;
111
+ },
112
+ /** Keeps the window's rasterized SVG pictures in place of coarser ones. */
113
+ provide(bitmaps: readonly VectorBitmap[]) {
114
+ for (const { asset, bitmap } of bitmaps) {
115
+ const entry = cache.get(asset);
116
+
117
+ if (!entry?.vector || (bitmap && entry.bitmap && covers(entry.bitmap, bitmap))) {
118
+ bitmap?.close();
119
+ continue;
120
+ }
121
+
122
+ if (!bitmap) {
123
+ entry.vector.failed = !entry.bitmap;
124
+ continue;
125
+ }
126
+
127
+ entry.bitmap?.close();
128
+ entry.bitmap = bitmap;
129
+ }
130
+ },
131
/** Closes the least recently drawn images past the budget. Call it between paints, never during one. */
132
trim() {
133
const size = (entry: Decoded) =>
@@ -93,6 +150,10 @@ export function createBitmapImageResolver(media: (token: string) => YrsMediaSour
150
};
151
}
152
153
+function covers(bitmap: Size, size: Size) {
154
+ return bitmap.width >= size.width && bitmap.height >= size.height;
155
+}
156
+
157
/** The grey box a missing image paints: one pixel the painter stretches over the image's place. */
158
function greyBox() {
159
const canvas = new OffscreenCanvas(1, 1);
apps/web/src/components/files/office/word-protocol.ts
+8
-2
@@ -1,4 +1,5 @@
1
// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
2
+import type { VectorBitmap, VectorRequest } from "./vector-pictures";
3
import type { Method } from "./worker-rpc";
4
5
// What the Word preview's window and its document worker say to each other. The window keeps only the page column, the
@@ -70,11 +71,16 @@ export type WordMethods = {
71
>;
72
/** Lays out a short step more of the document. */
73
readonly layout: Method<undefined, WordLayoutStep>;
73
- /** Paints a page at `scale` page pixels per CSS pixel times `ratio` device pixels per CSS pixel. */
74
+ /**
75
+ * Paints a page at `scale` page pixels per CSS pixel times `ratio` device pixels per CSS pixel. `vectors` lists the
76
+ * SVG pictures it drew without, or too coarse: paint again once the worker has them.
77
+ */
78
readonly paint: Method<
79
{ readonly index: number; readonly scale: number; readonly ratio: number },
76
- ImageBitmap | undefined
80
+ { readonly bitmap: ImageBitmap; readonly vectors: readonly VectorRequest[] } | undefined
81
>;
82
+ /** Hands over SVG pictures rasterized for `VectorRequest`s. */
83
+ readonly vectors: Method<readonly VectorBitmap[], undefined>;
84
/** Builds a page's content ahead of its paint. */
85
readonly build: Method<{ readonly index: number }, undefined>;
86
/** A page's text layer. */
apps/web/src/components/files/officeArchive.test.ts
+15
@@ -91,6 +91,21 @@ describe("Word preview limits", () => {
91
expect(await result.part("word/document.xml")).toContain("Item 5999");
92
});
93
94
+ it("keeps the lists of a document with picture bullets, with their text bullets", async () => {
95
+ const picture = `<w:numPicBullet w:numPicBulletId="0"><w:pict><v:shape style="width:9pt;height:9pt"><v:imagedata r:id="rId1"/></v:shape></w:pict></w:numPicBullet>`;
96
+ const pictured = `<w:abstractNum w:abstractNumId="0"><w:lvl w:ilvl="0"><w:numFmt w:val="bullet"/><w:lvlText w:val="\uf0b7"/><w:lvlPicBulletId w:val="0"/></w:lvl></w:abstractNum>`;
97
+ const numbered = `<w:abstractNum w:abstractNumId="1"><w:lvl w:ilvl="0"><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/></w:lvl></w:abstractNum>`;
98
+ const lists = `<w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num><w:num w:numId="2"><w:abstractNumId w:val="1"/></w:num>`;
99
+ const result = await prepared(
100
+ await wordFile(paragraph("Item", `<w:pPr><w:numPr><w:numId w:val="2"/></w:numPr></w:pPr>`), {
101
+ numbering: `<w:numbering ${W} ${V} ${R}>${picture}${pictured}${numbered}${lists}</w:numbering>`,
102
+ }),
103
+ );
104
+ expect(await result.part("word/numbering.xml")).toBe(
105
+ `<w:numbering ${W} ${V} ${R}>${pictured.replace('<w:lvlPicBulletId w:val="0"/>', "")}${numbered}${lists}</w:numbering>`,
106
+ );
107
+ });
108
+
109
const text = "x".repeat(140_000);
110
it.each([
111
["on its own", `<w:p><w:r><w:t>${text}</w:t></w:r></w:p>`],
apps/web/src/components/files/officeArchive.ts
+22
-6
@@ -812,13 +812,17 @@ function wordPartTypes() {
812
}
813
814
// Bound inherited style and numbering expansion before the engine loads it.
815
-// Picture bullets can duplicate embedded images, so omit those definitions.
815
+// Picture bullets can duplicate embedded images, so `pictures` locates those definitions to omit.
816
function wordXmlCost(xml: string, roles: Set<string> | undefined) {
817
const parser = xmlParser();
818
let depth = 0;
819
let markup = 0;
820
const limit = Symbol("Word style budget");
821
- const exceeded = { bytes: Infinity, markup: Infinity, pictures: false };
821
+ const exceeded = {
822
+ bytes: Infinity,
823
+ markup: Infinity,
824
+ pictures: [] as { start: number; end: number }[],
825
+ };
826
let styleCount = 0;
827
let ownUnits = 0;
828
const styles = new Map<
@@ -832,7 +836,8 @@ function wordXmlCost(xml: string, roles: Set<string> | undefined) {
836
const references: { id: string; selector: number }[] = [];
837
let definition: { id: string; start: number; markup: number } | null = null;
838
let reference: { id: string; selector: number } | null = null;
835
- let pictures = false;
839
+ const pictures: { start: number; end: number }[] = [];
840
+ let picture: { start: number; depth: number } | null = null;
841
parser.on("opentag", (tag) => {
842
if (++depth > 64)
843
throw new Error("Preview limited: this Word document has excessive XML nesting.");
@@ -870,9 +875,14 @@ function wordXmlCost(xml: string, roles: Set<string> | undefined) {
875
}
876
if (tag.local === "abstractNumId" && reference) reference.id = attr("val");
877
}
873
- if (tag.local === "numPicBullet") pictures = true;
878
+ if (!picture && (tag.local === "numPicBullet" || tag.local === "lvlPicBulletId"))
879
+ picture = { start: xml.lastIndexOf("<", parser.position - 1), depth };
880
});
881
parser.on("closetag", (tag) => {
882
+ if (picture?.depth === depth) {
883
+ pictures.push({ start: picture.start, end: parser.position });
884
+ picture = null;
885
+ }
886
if (definition && tag.local === "abstractNum") {
887
const previous = definitions.get(definition.id);
888
definitions.set(definition.id, {
@@ -1251,11 +1261,17 @@ export async function boundedArchive(input: Extract<OfficeWorkerRequest, { type:
1261
if (entry.name === "[Content_Types].xml" || entry.name.endsWith(".rels"))
1262
xml = partTypes.metadata(entry.name, xml);
1263
const roles = partTypes.roles.get(entry.name);
1254
- const cost = wordXmlCost(xml, roles);
1264
+ let cost = wordXmlCost(xml, roles);
1265
// The renderer parses related parts even when their render option is off.
1266
if (roles && [...roles].every((role) => WORD_DISABLED_PARTS.has(role))) continue;
1267
+ // Picture bullets come out, and their list levels keep the text bullets Word falls back to.
1268
+ if (roles?.has("numbering") && cost.pictures.length > 0) {
1269
+ for (const range of cost.pictures.toReversed())
1270
+ xml = xml.slice(0, range.start) + xml.slice(range.end);
1271
+ cost = wordXmlCost(xml, roles);
1272
+ wordInputTruncated = true;
1273
+ }
1274
if (
1258
- (roles?.has("numbering") && cost.pictures) ||
1275
(roles?.has("styles") &&
1276
(cost.bytes > WORD_LIMITS.styleBytes || cost.markup > WORD_LIMITS.styleUnits)) ||
1277
(roles?.has("numbering") &&
pnpm-lock.yaml
+5
-5
@@ -1032,8 +1032,8 @@ importers:
1032
specifier: ^1.9.0
1033
version: 1.9.0(@date-fns/tz@1.5.0)(@types/react@19.3.0)(date-fns@4.4.0)(react-dom@19.3.0(react@19.3.0))(react@19.3.0)
1034
'@betteroffice/docx':
1035
- specifier: 0.4.3
1036
- version: 0.4.3(@betteroffice/fonts@0.4.0(@betteroffice/fonts-cjk@0.4.0))
1035
+ specifier: 0.5.1
1036
+ version: 0.5.1(@betteroffice/fonts@0.4.0(@betteroffice/fonts-cjk@0.4.0))
1037
'@betteroffice/fonts':
1038
specifier: 0.4.0
1039
version: 0.4.0(@betteroffice/fonts-cjk@0.4.0)
@@ -3273,8 +3273,8 @@ packages:
3273
'@types/react':
3274
optional: true
3275
3276
- '@betteroffice/docx@0.4.3':
3277
- resolution: {integrity: sha512-CEErXJH3iCsi2a61gTNkAofLCzSTcktLmp710gGhMwbBfOqwQ2yI7dRFBV3ElGa9JxkS03IfejvLX0sAvlTrUQ==}
3276
+ '@betteroffice/docx@0.5.1':
3277
+ resolution: {integrity: sha512-90OVOjArTdk7KmHNSGBPMLDPg1sU+k/LI0HooZDdALwidGpjNjFAazkKSTg29K6fpmv6qmygCdJiXCCoxL2GRw==}
3278
peerDependencies:
3279
'@betteroffice/fonts': ^0
3280
peerDependenciesMeta:
@@ -13858,7 +13858,7 @@ snapshots:
13858
optionalDependencies:
13859
'@types/react': 19.3.0
13860
13861
- '@betteroffice/docx@0.4.3(@betteroffice/fonts@0.4.0(@betteroffice/fonts-cjk@0.4.0))':
13861
+ '@betteroffice/docx@0.5.1(@betteroffice/fonts@0.4.0(@betteroffice/fonts-cjk@0.4.0))':
13862
optionalDependencies:
13863
'@betteroffice/fonts': 0.4.0(@betteroffice/fonts-cjk@0.4.0)
13864
third-party-licenses.config.json
+1
-1
@@ -279,7 +279,7 @@
279
},
280
{
281
"name": "@betteroffice/docx",
282
- "version": "0.4.3",
282
+ "version": "0.5.1",
283
"license": "Apache-2.0",
284
"sourceUrl": "https://github.com/openooxml/betteroffice",
285
"generatedNotice": {