sailfork / t3code-github / apps/ web/ src/ components/ files/ office/ document.worker.ts

// Adapted from opencode (MIT). Copyright (c) 2025 opencode. See LICENSE.opencode.
import * as Schema from "effect/Schema";
import {
  buildResidentRegionLayoutRequest,
  getLayoutKernelInputs,
  workerLayoutComputation,
} from "@betteroffice/docx/editor";
import { createRustMeasureSource } from "@betteroffice/docx/layout";
import {
  applyFrameDelta,
  decodeFrameDelta,
  encodeDisplayListFrameExtras,
  GlyphCache,
  rasterizeDisplayPageToBackBuffer,
  type DisplayPage,
  type RetainedFrame,
} from "@betteroffice/docx/layout/render";
import {
  createYrsPositionProjection,
  createYrsSession,
  type YrsPositionProjection,
} from "@betteroffice/docx/yrs";
import { wordFonts } from "./fonts";
import { createBitmapImageResolver } from "./word-images";
import { layerFont, type WordMethods, type WordPageSize, type WordSpan } from "./word-protocol";
import { pageText, positionTarget, type TextMeasure } from "./word-text";
import { serveWorker, Transfer } from "./worker-rpc";

// One worker holds one open Word document: its engine session, fonts, layout, built pages and painting. The window
// terminates the worker when the document closes, which is the only way the engine's memory is given back.

const FontRequirements = Schema.fromJsonString(
  Schema.Array(
    Schema.Struct({
      key: Schema.String,
      family: Schema.String,
      bold: Schema.Boolean,
      italic: Schema.Boolean,
      scripts: Schema.optional(
        Schema.Array(Schema.Literals(["cjk-sc", "cjk-tc", "cjk-jp", "cjk-kr", "arabic", "hebrew"])),
      ),
    }),
  ),
);

const decodeFontRequirements = Schema.decodeUnknownSync(FontRequirements);

/** A prefix layout's reply marks itself provisional when the document goes on past it. */
const decodeLayoutReply = Schema.decodeUnknownSync(
  Schema.fromJsonString(Schema.Struct({ provisional: Schema.optional(Schema.Boolean) })),
);

/** 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
 * directions, and lets a reader scroll back a few screens without waiting, while a long read holds at most 21 pages.
 */
const keptAround = 10;

type Opened = Awaited<ReturnType<typeof open>>;

/** A value built on first use. */
type Lazy<T> = { value: T | undefined };

/** The document this worker opened, once it has. */
const opened: Lazy<Opened> = { value: undefined };

serveWorker<WordMethods>({
  open: async (input) => {
    if (opened.value) throw new Error("The worker already holds a document");

    const loaded = await open(new Uint8Array(input.bytes));

    opened.value = loaded;

    return { pages: loaded.pages().map(pageSize), loading: loaded.loading() };
  },
  layout: () => required().step(),
  paint: async (input, signal) => {
    const bitmap = await required().paint(input.index, input.scale, input.ratio, signal);

    return bitmap ? new Transfer(bitmap, [bitmap]) : undefined;
  },
  build: (input) => {
    required().built(input.index);

    return undefined;
  },
  text: (input) => required().text(input.index),
  bookmark: (input) => required().target(input.name),
});

function required() {
  if (!opened.value) throw new Error("The worker holds no document");

  return opened.value;
}

/** Opens the document and lays out its first pages; the rest lay out a `step` at a time. */
async function open(bytes: Uint8Array) {
  const session = await createYrsSession();
  const document = session.openDocx(bytes, true, { mediaTokens: true }).document;
  const settings = document.package.settings;

  const measure = createRustMeasureSource({
    engine: {
      registerFont: (font) => session.registerFont(font),
      registerSubstituteFont: (id, family) => session.registerSubstituteFont(id, family),
      clearFonts: () => session.clearFonts(),
    },
    bundled: wordFonts(),
  });

  measure.setCompat(settings?.compatibilityFlags);

  const request = buildResidentRegionLayoutRequest(document, 0, {
    themeColors: Object.fromEntries(
      Object.entries(document.package.theme?.colorScheme ?? {}).filter(
        (entry): entry is [string, string] => entry[1] !== undefined,
      ),
    ),
    defaultTabStopTwips: settings?.defaultTabStop ?? null,
    numericIds: {},
    mediaTokens: true,
  });

  const requirements = decodeFontRequirements(
    session.layoutFontRequirementsJson(JSON.stringify(request)),
  ).map(({ scripts, ...requirement }) => ({
    ...requirement,
    ...(scripts ? { scripts: [...scripts] } : {}),
  }));

  await measure.prepareFontRequirements(requirements);

  const measurement = measure.measurementConfigForRequirements(requirements);

  if (!measurement) throw new Error("The document's fonts could not be prepared");

  const input = JSON.stringify({ ...request, measurement });

  // Word shows resolved comments without the active highlight.
  const resolvedCommentIds = (document.package.document.comments ?? [])
    .filter(
      (comment) =>
        (comment.done || comment.status === "resolved") && comment.parentId === undefined,
    )
    .map((comment) => comment.id);

  // The session keeps the layout it last ran and builds display frames from it: only the display extras go in, and a
  // binary frame comes back with the window's pages built and every other page a placeholder carrying its geometry.
  const display = (previous: RetainedFrame | null, reply: string) => {
    const layout = workerLayoutComputation(reply).layout;

    session.setDisplayWindow(0, firstPages);

    const extras = encodeDisplayListFrameExtras({
      measured: [],
      options: {},
      layout,
      fontChains: measurement.fontChains,
      ...(getLayoutKernelInputs(layout)?.headersFooters
        ? { headersFooters: getLayoutKernelInputs(layout)!.headersFooters! }
        : {}),
      resolvedCommentIds,
    });

    return applyFrameDelta(
      previous,
      decodeFrameDelta(session.buildDisplayListFrame(extras, previous?.frameEpoch ?? 0)),
    );
  };

  // Only as much of the body as fills the first pages; a long document goes on past it.
  const prefix = session.layoutDocumentWithRegionsPrefixRetainedJson(input, firstPages);
  const retained = { frame: display(null, prefix) };

  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 };

  // Builds a page's content when it is needed and not built, the first time or again after `release`.
  const built = (index: number) => {
    const page = retained.frame.displayList.pages[index];

    if (!page?.unbuilt) return page;

    retained.frame = applyFrameDelta(
      retained.frame,
      decodeFrameDelta(session.buildDisplayPagesFrame([index], retained.frame.frameEpoch)),
    );

    return retained.frame.displayList.pages[index];
  };

  // Gives back the built pages far from the page about to paint, so a long read keeps only the pages around the
  // viewport. A released page keeps its geometry and document positions, which bookmarks search, and builds again
  // 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;

    const far = retained.frame.displayList.pages.flatMap((page, index) =>
      !page.unbuilt && Math.abs(painted - index) > keptAround ? [index] : [],
    );

    if (far.length === 0) return;

    const frame = session.releaseDisplayPagesFrame(far, retained.frame.frameEpoch);

    // A superseded release changes nothing; the next one tries again.
    if (frame) retained.frame = applyFrameDelta(retained.frame, decodeFrameDelta(frame));
  };

  // The whole document's layout replaces the prefix's frame.
  const complete = (reply: string) => {
    const before = retained.frame.displayList.pages;

    retained.frame = display(retained.frame, reply);
    layout.loading = false;

    const pages = retained.frame.displayList.pages;

    return {
      done: true as const,
      pages: pages.map(pageSize),
      kept: pages.map((page, index) => {
        const was = before[index];

        return was === page || (!!was?.unbuilt && !!page.unbuilt);
      }),
    };
  };

  const glyphCache = new GlyphCache({
    provider: (font, glyph) => session.outlineGlyphJson(font, glyph),
  });
  const images = createBitmapImageResolver((token) => session.mediaSource(token));
  const surface = new OffscreenCanvas(1, 1);
  const textMeasure = layerMeasure();
  const texts = new WeakMap<DisplayPage, readonly WordSpan[]>();
  // Built on the first followed bookmark: most documents are read without one.
  const projection: Lazy<YrsPositionProjection | null> = { value: undefined };

  return {
    pages: () => retained.frame.displayList.pages,
    loading: () => layout.loading,
    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.
     */
    step: () => {
      if (!layout.loading) {
        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 started = performance.now();
      const progress = session.resumeRegionLayout(blocks);

      layout.cost = layout.cost * 0.7 + ((performance.now() - started) / blocks) * 0.3;

      return progress.layoutJson === undefined
        ? { done: false as const }
        : complete(progress.layoutJson);
    },
    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.
      if (signal.aborted) return undefined;

      // Released first, so the page builds in the memory they free.
      release(index);

      const page = built(index);

      if (!page) return undefined;

      // The window drew image elements, which shrink smoothly at the default quality; a bitmap needs medium quality to
      // look the same. Sizing the surface first keeps the setting: the painter resizes it, which resets the context,
      // only when its size differs.
      const context = surface.getContext("2d");
      const width = Math.ceil(page.width * ratio * scale);
      const height = Math.ceil(page.height * ratio * scale);

      if (surface.width !== width) surface.width = width;

      if (surface.height !== height) surface.height = height;

      if (context) context.imageSmoothingQuality = "medium";

      await rasterizeDisplayPageToBackBuffer(
        surface,
        page,
        { glyphCache, resolveImage: images.resolve },
        ratio,
        scale,
      );
      images.trim();

      if (signal.aborted) return undefined;

      return surface.transferToImageBitmap();
    },
    text: (index: number) => {
      const page = built(index);

      if (!page || !textMeasure) return [];

      const cached = texts.get(page);

      if (cached) return cached;

      const spans = pageText(page, textMeasure);

      texts.set(page, spans);

      return spans;
    },
    target: (name: string) => {
      projection.value ??= createYrsPositionProjection(session, "body");

      const position = projection.value?.bookmarkPosition(name) ?? undefined;

      if (position !== undefined)
        return positionTarget(retained.frame.displayList.pages, position, built);

      // Word's reserved bookmark for the start of the document.
      return name === "_top" ? { index: 0, y: 0 } : undefined;
    },
  };
}

function pageSize(page: DisplayPage): WordPageSize {
  return { width: page.width, height: page.height, background: page.background };
}

/** Measures the text layer's font with a detached canvas; undefined where the worker offers no 2D context. */
function layerMeasure(): TextMeasure | undefined {
  const context = new OffscreenCanvas(1, 1).getContext("2d");

  if (!context) return undefined;

  // Measured large and scaled down, so rounding stays well below a pixel at any zoom.
  const size = 100;

  context.font = `${size}px ${layerFont}`;

  const metrics = context.measureText("Hg");

  return {
    width: (text) => context.measureText(text).width / size,
    ascent: metrics.fontBoundingBoxAscent / size,
    descent: metrics.fontBoundingBoxDescent / size,
  };
}