sumatrapdf Documentation

Technical Documentation: sumatrapdfreader/sumatrapdf

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Ext Mupdf Docs Reference C Overview (`ext/mupdf/docs/reference/c/overview.md`) Copy Section

Overview

Basic MuPDF usage example Copy Chapter

To limit the complexity and give an easier introduction
this code has no error handling at all, but any serious piece of code
using MuPDF should use the error handling strategies described below.

Common function arguments Copy Chapter

Most functions in MuPDF's interface take a context argument.

A context contains global state used by MuPDF inside functions when
parsing or rendering pages of the document. It contains for example:

• an exception stack (see error handling below),
• a memory allocator (allowing for custom allocators)
• a resource store (for caching of images, fonts, etc.)
• a set of locks and (un-)locking functions (for multi-threading)

Without the set of locks and accompanying functions the context and
its proxies may only be used in a single-threaded application.

Error handling Copy Chapter

MuPDF uses a set of exception handling macros to simplify error return
and cleanup. Conceptually, they work a lot like C++'s try/catch
system, but do not require any special compiler support.

The basic formulation is as follows:

fz_try(ctx)
{
	// Try to perform a task. Never 'return', 'goto' or
	// 'longjmp' out of here. 'break' may be used to
	// safely exit (just) the try block scope.
}
fz_always(ctx)
{
	// Any code here is always executed, regardless of
	// whether an exception was thrown within the try or
	// not. Never 'return', 'goto' or longjmp out from
	// here. 'break' may be used to safely exit (just) the
	// always block scope.
}
fz_catch(ctx)
{
	// This code is called (after any always block) only
	// if something within the fz_try block (including any
	// functions it called) threw an exception. The code
	// here is expected to handle the exception (maybe
	// record/report the error, cleanup any stray state
	// etc) and can then either exit the block, or pass on
	// the exception to a higher level (enclosing) fz_try
	// block (using fz_throw, or fz_rethrow).
}

The fz_always block is optional, and can safely be omitted.

The macro based nature of this system has 3 main limitations:

1. Never return from within try (or 'goto' or longjmp out of it).
   This upsets the internal housekeeping of the macros and will
   cause problems later on. The code will detect such things
   happening, but by then it is too late to give a helpful error
   report as to where the original infraction occurred.

2. The try/always/catch statement is not one atomic C statement.

   The fz_try(ctx) { ... } fz_always(ctx) { ... } fz_catch(ctx) { ... } is not one atomic C statement.
   That is to say, if you do:

   text Copy

   if (condition)
        fz_try(ctx) { ... }
        fz_catch(ctx) { ... }

   then you will not get what you want. Use the following instead:

   text Copy

   if (condition) {
        fz_try(ctx) { ... }
        fz_catch(ctx) { ... }
    }

3. The macros are implemented using setjmp and longjmp, and so
   the standard C restrictions on the use of those functions
   apply to fz_try/fz_catch too.

   In particular, any "truly local"
   variable that is set between the start of fz_try and something
   in fz_try throwing an exception may become undefined as part
   of the process of throwing that exception.

As a way of mitigating this problem, we provide a fz_var()
macro that tells the compiler to ensure that that variable is
not unset by the act of throwing the exception.

A model piece of code using these macros then might be:

house build_house(plans *p)
{
	material m = NULL;
	walls w = NULL;
	roof r = NULL;
	house h = NULL;
	tiles t = make_tiles();

	fz_var(w);
	fz_var(r);
	fz_var(h);

	fz_try(ctx)
	{
		fz_try(ctx)
		{
			m = make_bricks();
		}
		fz_catch(ctx)
		{
			// No bricks available, make do with straw?
			m = make_straw();
		}
		w = make_walls(m, p);
		r = make_roof(m, t);
		// Note, NOT: return combine(w,r);
		h = combine(w, r);
	}
	fz_always(ctx)
	{
		drop_walls(w);
		drop_roof(r);
		drop_material(m);
		drop_tiles(t);
	}
	fz_catch(ctx)
	{
		fz_throw(ctx, "build_house failed");
	}
	return h;
}

Things to note about this:

1. If make_tiles throws an exception, this will immediately be
   handled by some higher level exception handler. If it
   succeeds, t will be set before fz_try starts, so there is no
   need to fz_var(t);

2. We try first off to make some bricks as our building material.
   If this fails, we fall back to straw. If this fails, we'll end
   up in the fz_catch, and the process will fail neatly.

3. We assume in this code that combine takes new reference to
   both the walls and the roof it uses, and therefore that w and
   r need to be cleaned up in all cases.

4. We assume the standard C convention that it is safe to destroy
   NULL things.

Multi-threading Copy Chapter

First off, study the basic usage example in docs/examples/example.c
and make sure you understand how it works as the data structures manipulated
there will be referred to in this section too.

MuPDF can usefully be built into a multi-threaded application without
the library needing to know anything threading at all. If the library
opens a document in one thread, and then sits there as a 'server'
requesting pages and rendering them for other threads that need them,
then the library is only ever being called from this one thread.

Other threads can still be used to handle UI requests etc, but as far
as MuPDF is concerned it is only being used in a single threaded way.
In this instance, there are no threading issues with MuPDF at all,
and it can safely be used without any locking, as described in the
previous sections.

This section will attempt to explain how to use MuPDF in the more
complex case; where we genuinely want to call the MuPDF library
concurrently from multiple threads within a single application.

MuPDF can be invoked with a user supplied set of locking functions.
It uses these to take mutexes around operations that would conflict
if performed concurrently in multiple threads. By leaving the
exact implementation of locks to the caller MuPDF remains threading
library agnostic.

The following simple rules should be followed to ensure that
multi-threaded operations run smoothly:

1. "No simultaneous calls to MuPDF in different threads are
   allowed to use the same context."

   Most of the time it is simplest to just use a different
   context for every thread; just create a new context at the
   same time as you create the thread. For more details see
   "Cloning the context" below.

2. "No simultaneous calls to MuPDF in different threads are
   allowed to use the same document."

   Only one thread can be accessing a document at a time, but
   once display lists are created from that document, multiple
   threads at a time can operate on them.

   The document can be used from several different threads as
   long as there are safeguards in place to prevent the usages
   being simultaneous.

3. "No simultaneous calls to MuPDF in different threads are
   allowed to use the same device."

   Calling a device simultaneously from different threads will
   cause it to get confused and may crash. Calling a device from
   several different threads is perfectly acceptable as long as
   there are safeguards in place to prevent the calls being
   simultaneous.

4. "An fz_locks_context must be supplied at context creation time,
   unless MuPDF is to be used purely in a single thread at a time."

   MuPDF needs to protect against unsafe access to certain structures/
   resources/libraries from multiple threads. It does this by using
   the user supplied locking functions. This holds true even when
   using completely separate instances of MuPDF.

5. "All contexts in use must share the same fz_locks_context (or
   the underlying locks thereof)."

   We strongly recommend that fz_new_context is called just once,
   and fz_clone_context is called to generate new contexts from
   that. This will automatically ensure that the same locking
   mechanism is used in all MuPDF instances. For now, we do support
   multiple completely independent contexts being created using
   repeated calls to fz_new_context, but these MUST share the
   same fz_locks_context (or at least depend upon the same underlying
   locks). The facility to create different independent contexts
   may be removed in future.

So, how does a multi-threaded example differ from a non-multithreaded
one?

Firstly, when we create the first context, we call fz_new_context
as before, but the second argument should be a pointer to a set
of locking functions.

The calling code should provide FZ_LOCK_MAX mutexes, which will be
locked/unlocked by MuPDF calling the lock/unlock function pointers
in the supplied structure with the user pointer from the structure
and the lock number, i (0 <= i < FZ_LOCK_MAX). These mutexes can
safely be recursive or non-recursive as MuPDF only calls in a non-
recursive style.

To make subsequent contexts, the user should NOT call fz_new_context
again (as this will fail to share important resources such as the
store and glyphcache), but should rather call fz_clone_context.
Each of these cloned contexts can be freed by fz_free_context as
usual. They will share the important data structures (like store,
glyph cache etc) with the original context, but will have their
own exception stacks.

To open a document, call fz_open_document as usual, passing a context
and a filename. It is important to realise that only one thread at a
time can be accessing the documents itself.

This means that only one thread at a time can perform operations such
as fetching a page, or rendering that page to a display list. Once a
display list has been obtained however, it can be rendered from any
other thread (or even from several threads simultaneously, giving
banded rendering).

This means that an implementer has 2 basic choices when constructing
an application to use MuPDF in multi-threaded mode. Either he can
construct it so that a single nominated thread opens the document
and then acts as a 'server' creating display lists for other threads
to render, or he can add his own mutex around calls to mupdf that
use the document. The former is likely to be far more efficient in
the long run.

For an example of how to do multi-threading see
docs/examples/multi-threaded.c
which has a main thread and one rendering thread per page.

Cloning the context Copy Chapter

As described above, every context contains an exception stack which is
manipulated during the course of nested fz_try/fz_catches. For obvious
reasons the same exception stack cannot be used from more than one
thread at a time.

If, however, we simply created a new context (using fz_new_context) for
every thread, we would end up with separate stores/glyph caches etc,
which is not (generally) what is desired. MuPDF therefore provides a
mechanism for "cloning" a context. This creates a new context that
shares everything with the given context, except for the exception
stack.

A commonly used general scheme is therefore to create a 'base' context
at program start up, and to clone this repeatedly to get new contexts
that can be used on new threads.

Ext Mupdf Docs Reference C Fitz Api Overview (`ext/mupdf/docs/reference/c/fitz/api-overview.md`) Copy Section

API Overview

The MuPDF fitz library is the core C API for rendering and manipulating PDF,
XPS, EPUB, and other document formats. The public API is exposed through the
include/mupdf/fitz/ header files, all of which are collected under the
umbrella header mupdf/fitz.h.

The library is organised into functional groups:

• Core – context, geometry, system utilities
• I/O – buffers, streams, compression, archives
• Resources – pixmaps, images, bitmaps, fonts, colour spaces, paths
• Rendering – devices, display lists, structured text
• Document – documents, pages, links, outlines, bookmarks
• Utilities – high-level helpers combining the above

Note: All functions that allocate memory or may fail take an fz_context *ctx
as their first argument. Errors are signalled via setjmp/longjmp
exception handling; callers should wrap operations in
fz_try / fz_catch blocks.

📒 For more see the full {doc}../api/index.

mupdf/fitz.h – Umbrella Header Copy Chapter

#include "mupdf/fitz.h"

This single header pulls in the entire public fitz API. It is the recommended
way to include MuPDF in your project.

Include groups (in order of declaration):

• Core: version.h, config.h, system.h, context.h, output.h, log.h
• Utilities: crypt.h, getopt.h, geometry.h, hash.h, pool.h,
  string-util.h, tree.h, bidi.h, xml.h, json.h, hyphen.h
• I/O: buffer.h, stream.h, compress.h, compressed-buffer.h,
  filter.h, archive.h, heap.h
• Resources: store.h, color.h, pixmap.h, image.h, bitmap.h,
  shade.h, font.h, path.h, text.h, separation.h, glyph.h
• Rendering: device.h, display-list.h, structured-text.h,
  transition.h, glyph-cache.h
• Document: link.h, outline.h, document.h

context.h – Context & Error Handling Copy Chapter

#include "mupdf/fitz/context.h"

The fz_context is the central state object passed to virtually every fitz
function. It holds the allocator, exception stack, and resource caches.

Exception Macros Copy Section

fz_try(ctx)      { /* code that may throw */ }
fz_catch(ctx)    { /* handle the error */ }
fz_always(ctx)   { /* always executed (cleanup) */ }

fz_throw(ctx, FZ_ERROR_GENERIC, "format %s", msg);
fz_rethrow(ctx);
fz_warn(ctx, "warning: %s", msg);

Error codes (selected) Copy Section

Context lifecycle Copy Section

fz_context *fz_new_context(const fz_alloc_context *alloc, const fz_locks_context *locks, size_t max_store)

Create a new fitz context.

• alloc – Custom allocator, or NULL for the system default.
• locks – Locking callbacks for thread safety, or NULL.
• max_store – Maximum size of the resource store in bytes (e.g. FZ_STORE_DEFAULT).
• Returns: A new fz_context, or NULL on failure.

fz_context *fz_clone_context(fz_context *ctx)

Clone a context for use in a new thread. Shares the same resource store
and locks as the original.

• ctx – The context to clone.
• Returns: A new context; must be freed with fz_drop_context.

void fz_drop_context(fz_context *ctx)

Free a context and all associated resources. Never throws exceptions.

• ctx – The context to destroy.

Memory helpers Copy Section

void *fz_malloc(fz_context *ctx, size_t size)

Allocate size bytes. Throws FZ_ERROR_MEMORY on failure.

void *fz_calloc(fz_context *ctx, size_t count, size_t size)

Allocate and zero-initialise count * size bytes.

void fz_free(fz_context *ctx, void *p)

Free memory previously allocated with fz_malloc / fz_calloc.

geometry.h – Geometric Types Copy Chapter

#include "mupdf/fitz/geometry.h"

Types Copy Section

fz_point – A 2-D point.

typedef struct { float x, y; } fz_point;

fz_rect – An axis-aligned rectangle with float coordinates.

typedef struct { float x0, y0, x1, y1; } fz_rect;

The fz_empty_rect and fz_infinite_rect constants are provided for convenience.

fz_irect – An axis-aligned rectangle with int coordinates (used for pixmap bounds).

typedef struct { int x0, y0, x1, y1; } fz_irect;

fz_matrix – A 3×2 affine transformation matrix.

typedef struct { float a, b, c, d, e, f; } fz_matrix;

Pre-defined matrices: fz_identity.

fz_quad – A quadrilateral (four corners), used for text hit quads.

typedef struct { fz_point ul, ur, ll, lr; } fz_quad;

Selected functions Copy Section

fz_matrix fz_scale(float sx, float sy) – Create a scaling matrix.

fz_matrix fz_rotate(float degrees) – Create a rotation matrix (counter-clockwise, in degrees).

fz_matrix fz_translate(float tx, float ty) – Create a translation matrix.

fz_matrix fz_concat(fz_matrix left, fz_matrix right) – Concatenate two matrices (left is applied first).

fz_matrix fz_invert_matrix(fz_matrix m) – Invert a matrix. Returns fz_identity if the matrix is singular.

fz_point fz_transform_point(fz_point p, fz_matrix m) – Transform a point by a matrix.

fz_rect fz_transform_rect(fz_rect r, fz_matrix m) – Transform a rectangle by a matrix (returns the bounding box of the result).

fz_rect fz_intersect_rect(fz_rect a, fz_rect b) – Return the intersection of two rectangles.

fz_rect fz_union_rect(fz_rect a, fz_rect b) – Return the smallest rectangle containing both a and b.

fz_irect fz_round_rect(fz_rect r) – Convert a float rect to an integer rect by rounding outwards.

int fz_is_empty_rect(fz_rect r) – Return non-zero if the rectangle is empty.

int fz_is_infinite_rect(fz_rect r) – Return non-zero if the rectangle is the infinite rectangle.

archive.h – Archive Access Copy Chapter

#include "mupdf/fitz/archive.h"

An fz_archive provides a uniform interface over ZIP files, TAR files, and
plain directories.

fz_archive – Opaque handle to an archive.

fz_archive *fz_open_archive(fz_context *ctx, const char *filename)

Open a ZIP or TAR archive by filename. The archive type is detected
automatically from the file signature.

• ctx – Active fitz context.
• filename – Path to the archive file.
• Returns: A new fz_archive whose ownership is returned to the caller.
• Raises: FZ_ERROR_IO if the file cannot be opened.
• Raises: FZ_ERROR_FORMAT if the file format is not recognised.

fz_archive *fz_open_archive_with_stream(fz_context *ctx, fz_stream *file) – Open an archive from an existing stream.

fz_archive *fz_open_directory(fz_context *ctx, const char *path) – Open a directory as an archive.

int fz_is_directory(fz_context *ctx, fz_archive *arch) – Return non-zero if the archive is backed by a directory.

int fz_has_archive_entry(fz_context *ctx, fz_archive *arch, const char *name) – Return non-zero if name exists in the archive.

int fz_count_archive_entries(fz_context *ctx, fz_archive *arch) – Return the number of entries in the archive.

const char *fz_list_archive_entry(fz_context *ctx, fz_archive *arch, int idx) – Return the name of entry idx.

fz_stream *fz_open_archive_entry(fz_context *ctx, fz_archive *arch, const char *name) – Open an archive entry as a stream.

fz_buffer *fz_read_archive_entry(fz_context *ctx, fz_archive *arch, const char *name) – Read an archive entry entirely into a buffer.

void fz_drop_archive(fz_context *ctx, fz_archive *arch) – Release an archive.

pixmap.h – Raster Images (Pixmaps) Copy Chapter

#include "mupdf/fitz/pixmap.h"

A fz_pixmap represents a raster image: a rectangular region of pixels, each
with n colour components (process colours + spot colours + optional alpha) stored
contiguously in row-major order. Samples are in premultiplied alpha during
rendering, but non-premultiplied for colorspace conversions.

fz_pixmap – Opaque pixmap type. Key fields accessible via accessor functions:

• width / height (pixels)
• x / y origin (in device space)
• n (components per pixel)
• alpha (1 if alpha channel present, else 0)
• stride (bytes per row)
• samples (unsigned char * pixel data)
• colorspace (fz_colorspace *)
• xres / yres (resolution in dpi)

Creating pixmaps Copy Section

fz_pixmap *fz_new_pixmap(fz_context *ctx, fz_colorspace *cs, int w, int h, fz_separations *seps, int alpha)

Allocate a pixmap of size w × h.

• cs – Colour space (or NULL for alpha-only).
• seps – Spot separations, or NULL.
• alpha – Non-zero to include an alpha channel.

fz_pixmap *fz_new_pixmap_with_bbox(fz_context *ctx, fz_colorspace *cs, fz_irect bbox, fz_separations *seps, int alpha) – Allocate a pixmap covering bbox (sets the x/y origin accordingly).

fz_pixmap *fz_new_pixmap_with_data(fz_context *ctx, fz_colorspace *cs, int w, int h, fz_separations *seps, int alpha, int stride, unsigned char *samples) – Wrap an existing sample buffer; the buffer is not freed on drop.

fz_pixmap *fz_new_pixmap_with_bbox_and_data(fz_context *ctx, fz_colorspace *cs, fz_irect bbox, fz_separations *seps, int alpha, unsigned char *samples) – Wrap an existing buffer with a bounding box origin.

Reference counting Copy Section

fz_pixmap *fz_keep_pixmap(fz_context *ctx, fz_pixmap *pix) – Increment the reference count. Returns the same pointer. Never throws exceptions.

void fz_drop_pixmap(fz_context *ctx, fz_pixmap *pix) – Decrement the reference count; the pixmap is freed when it reaches zero. Never throws exceptions.

Accessors Copy Section

fz_irect fz_pixmap_bbox(fz_context *ctx, const fz_pixmap *pix) – Return the bounding box of the pixmap.

int fz_pixmap_width(fz_context *ctx, const fz_pixmap *pix) – Return the width in pixels.

int fz_pixmap_height(fz_context *ctx, const fz_pixmap *pix) – Return the height in pixels.

int fz_pixmap_x(fz_context *ctx, const fz_pixmap *pix) – Return the x origin of the pixmap (left edge, in device space).

int fz_pixmap_y(fz_context *ctx, const fz_pixmap *pix) – Return the y origin of the pixmap.

int fz_pixmap_stride(fz_context *ctx, const fz_pixmap *pix) – Return the stride (bytes per row).

int fz_pixmap_components(fz_context *ctx, const fz_pixmap *pix) – Return the total number of components (including alpha if present).

unsigned char *fz_pixmap_samples(fz_context *ctx, fz_pixmap *pix) – Return a pointer to the raw sample data.

fz_colorspace *fz_pixmap_colorspace(fz_context *ctx, fz_pixmap *pix) – Return the colour space of the pixmap (may be NULL).

Manipulation Copy Section

void fz_clear_pixmap(fz_context *ctx, fz_pixmap *pix) – Set all components (including alpha) of all pixels to zero.

void fz_clear_pixmap_with_value(fz_context *ctx, fz_pixmap *pix, int value) – Clear all pixels to value (0–255); alpha is always set to 255 (opaque).

void fz_fill_pixmap_with_color(fz_context *ctx, fz_pixmap *pix, fz_colorspace *cs, float *color, fz_color_params color_params) – Fill the pixmap with a solid colour.

void fz_copy_pixmap_rect(fz_context *ctx, fz_pixmap *dest, fz_pixmap *src, fz_irect r, const fz_default_colorspaces *default_cs) – Copy a rectangular region from src to dest.

fz_pixmap *fz_clone_pixmap(fz_context *ctx, const fz_pixmap *old) – Clone a pixmap to new storage. The reference count of old is unchanged.

fz_pixmap *fz_convert_pixmap(fz_context *ctx, const fz_pixmap *pix, fz_colorspace *cs_des, fz_colorspace *prf, fz_default_colorspaces *default_cs, fz_color_params color_params, int keep_alpha)

Convert the pixmap to a different colour space.

• cs_des – Destination colour space (NULL = alpha only).
• prf – Proofing colour space (or NULL).
• keep_alpha – If 0, alpha is stripped.

fz_pixmap *fz_scale_pixmap(fz_context *ctx, fz_pixmap *src, float x, float y, float w, float h, const fz_irect *clip) – Scale a pixmap to the given w × h size, optionally clipping.

void fz_invert_pixmap(fz_context *ctx, fz_pixmap *pix) – Invert all colour components (not alpha) in place.

void fz_gamma_pixmap(fz_context *ctx, fz_pixmap *pix, float gamma) – Apply gamma correction.

int fz_is_pixmap_monochrome(fz_context *ctx, fz_pixmap *pix) – Return non-zero if the pixmap contains only values 0 and 255.

bitmap.h – 1-bit Bitmaps Copy Chapter

#include "mupdf/fitz/bitmap.h"

A fz_bitmap stores 1 bit per component, used for halftoned output (e.g. for
sending to a printer). Samples are stored MSB-first, compatible with PBM format.

fz_bitmap

typedef struct {
    int refs;
    int w, h, stride, n;
    int xres, yres;
    unsigned char *samples;
} fz_bitmap;

fz_bitmap *fz_keep_bitmap(fz_context *ctx, fz_bitmap *bit) – Increment the reference count. Never throws exceptions.

void fz_drop_bitmap(fz_context *ctx, fz_bitmap *bit) – Decrement the reference count; bitmap is freed when it reaches zero. Never throws exceptions.

fz_bitmap *fz_new_bitmap_from_pixmap(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht) – Convert a pixmap to a halftoned 1-bit bitmap.

fz_bitmap *fz_new_bitmap_from_pixmap_band(fz_context *ctx, fz_pixmap *pix, fz_halftone *ht, int band_start) – Same as above, rendering a single horizontal band.

path.h – Vector Paths Copy Chapter

#include "mupdf/fitz/path.h"

Vector paths can be filled or stroked, and may have a dash pattern.

fz_path – Opaque path type.

fz_linecap

typedef enum {
    FZ_LINECAP_BUTT     = 0,
    FZ_LINECAP_ROUND    = 1,
    FZ_LINECAP_SQUARE   = 2,
    FZ_LINECAP_TRIANGLE = 3,
} fz_linecap;

fz_linejoin

typedef enum {
    FZ_LINEJOIN_MITER     = 0,
    FZ_LINEJOIN_ROUND     = 1,
    FZ_LINEJOIN_BEVEL     = 2,
    FZ_LINEJOIN_MITER_XPS = 3,
} fz_linejoin;

fz_stroke_state – Stroke parameters:

typedef struct {
    int refs;
    fz_linecap start_cap, dash_cap, end_cap;
    fz_linejoin linejoin;
    float linewidth;
    float miterlimit;
    float dash_phase;
    int dash_len;
    float dash_list[FZ_FLEXIBLE_ARRAY];
} fz_stroke_state;

Path construction Copy Section

fz_path *fz_new_path(fz_context *ctx) – Create a new empty path.

fz_path *fz_keep_path(fz_context *ctx, const fz_path *path) – Increment the reference count.

void fz_drop_path(fz_context *ctx, const fz_path *path) – Decrement the reference count; frees when zero.

void fz_moveto(fz_context *ctx, fz_path *path, float x, float y) – Start a new subpath at (x, y).

void fz_lineto(fz_context *ctx, fz_path *path, float x, float y) – Add a straight line segment to (x, y).

void fz_curveto(fz_context *ctx, fz_path *path, float cx1, float cy1, float cx2, float cy2, float ex, float ey) – Add a cubic Bézier curve.

void fz_closepath(fz_context *ctx, fz_path *path) – Close the current subpath.

void fz_rectto(fz_context *ctx, fz_path *path, float x1, float y1, float x2, float y2) – Add a rectangle as a closed subpath.

fz_rect fz_bound_path(fz_context *ctx, const fz_path *path, const fz_stroke_state *stroke, fz_matrix ctm) – Return the bounding box of a path (for fill or, if stroke is not NULL, stroke).

fz_path *fz_clone_path(fz_context *ctx, fz_path *old) – Return a writable clone of a (possibly shared) path.

Stroke state Copy Section

fz_stroke_state *fz_new_stroke_state(fz_context *ctx) – Allocate a default stroke state (1pt width, butt caps, miter join).

fz_stroke_state *fz_keep_stroke_state(fz_context *ctx, const fz_stroke_state *stroke) – Increment the reference count.

void fz_drop_stroke_state(fz_context *ctx, const fz_stroke_state *stroke) – Decrement the reference count; frees when zero.

document.h – Documents & Pages Copy Chapter

#include "mupdf/fitz/document.h"

Types Copy Section

fz_document – Opaque document handle.

fz_page – Opaque page handle.

fz_location – A document location (chapter + page).

typedef struct { int chapter, page; } fz_location;

fz_bookmark – An opaque bookmark (intptr_t).

fz_box_type – Page box type.

typedef enum {
    FZ_MEDIA_BOX,
    FZ_CROP_BOX,
    FZ_BLEED_BOX,
    FZ_TRIM_BOX,
    FZ_ART_BOX,
    FZ_UNKNOWN_BOX,
} fz_box_type;

Opening documents Copy Section

fz_document *fz_open_document(fz_context *ctx, const char *filename)

Open a document from filename. The format is detected automatically.

• Returns: A new fz_document; ownership is returned to the caller.

fz_document *fz_open_document_with_stream(fz_context *ctx, const char *magic, fz_stream *stream) – Open a document from a stream, using magic (MIME type or file extension) for format detection.

fz_document *fz_open_accelerated_document(fz_context *ctx, const char *filename, const char *accel) – Open a document with an accelerator file (e.g. pre-computed linearisation).

void fz_drop_document(fz_context *ctx, fz_document *doc) – Release a document.

fz_document *fz_keep_document(fz_context *ctx, fz_document *doc) – Increment the reference count.

Authentication Copy Section

int fz_needs_password(fz_context *ctx, fz_document *doc) – Return non-zero if the document requires a password.

int fz_authenticate_password(fz_context *ctx, fz_document *doc, const char *password) – Attempt to authenticate with password. Returns non-zero on success.

Layout Copy Section

void fz_style_document(fz_context *ctx, fz_document *doc, int publisher_css, const char *user_css)

Control use of publisher and user stylesheets.

• publisher_css – Enable/disable use of publisher styles.
• user_css – User stylesheet (the contents; not a file name).

void fz_layout_document(fz_context *ctx, fz_document *doc, float w, float h, float em)

Set the page layout for reflowable documents (EPUB, FB2, etc.).

• w – Page width in points.
• h – Page height in points.
• em – Default em-size in points.

Pre-defined layout constants:

FZ_LAYOUT_KINDLE_W   = 260   /* 6in 4:3 */
FZ_LAYOUT_KINDLE_H   = 346
FZ_LAYOUT_KINDLE_EM  = 9
FZ_LAYOUT_A5_W       = 420
FZ_LAYOUT_A5_H       = 595
FZ_LAYOUT_A5_EM      = 11

Page counting & navigation Copy Section

int fz_count_chapters(fz_context *ctx, fz_document *doc) – Return the number of chapters.

int fz_count_pages(fz_context *ctx, fz_document *doc) – Return the total number of pages (across all chapters).

int fz_count_chapter_pages(fz_context *ctx, fz_document *doc, int chapter) – Return the number of pages in a chapter.

fz_location fz_last_page(fz_context *ctx, fz_document *doc) – Return the location of the last page.

fz_location fz_next_page(fz_context *ctx, fz_document *doc, fz_location loc) – Return the next page location, wrapping across chapters.

fz_location fz_previous_page(fz_context *ctx, fz_document *doc, fz_location loc) – Return the previous page location.

int fz_page_number_from_location(fz_context *ctx, fz_document *doc, fz_location loc) – Convert a chapter/page location to a flat (zero-based) page number.

Loading pages Copy Section

fz_page *fz_load_page(fz_context *ctx, fz_document *doc, int number) – Load page by flat page number (zero-based).

fz_page *fz_load_chapter_page(fz_context *ctx, fz_document *doc, int chapter, int page) – Load a page by chapter and page index.

void fz_drop_page(fz_context *ctx, fz_page *page) – Release a page.

Page bounds & rendering Copy Section

fz_rect fz_bound_page(fz_context *ctx, fz_page *page) – Return the bounding box of the page (in points, with y increasing downward).

fz_rect fz_bound_page_box(fz_context *ctx, fz_page *page, fz_box_type box) – Return the bounding box of a specific page box type.

void fz_run_page(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie) – Render the page (content, annotations, and widgets) to a device.

void fz_run_page_contents(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie) – Render only the page content stream (no annotations/widgets).

void fz_run_page_annots(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie) – Render only the annotations.

void fz_run_page_widgets(fz_context *ctx, fz_page *page, fz_device *dev, fz_matrix transform, fz_cookie *cookie) – Render only the widgets (interactive form fields).

Metadata Copy Section

int fz_lookup_metadata(fz_context *ctx, fz_document *doc, const char *key, char *buf, size_t size)

Look up a metadata string. Standard keys include "format",
"encryption", "info:Title", "info:Author", etc.

• Returns: Length of the value string (or -1 if not found).

void fz_set_metadata(fz_context *ctx, fz_document *doc, const char *key, const char *value) – Set a metadata entry (for formats that support it).

Bookmarks Copy Section

fz_bookmark fz_make_bookmark(fz_context *ctx, fz_document *doc, fz_location loc) – Create a persistent bookmark for the given location.

fz_location fz_lookup_bookmark(fz_context *ctx, fz_document *doc, fz_bookmark mark) – Resolve a bookmark to a location.

Document handler registration Copy Section

void fz_register_document_handler(fz_context *ctx, const fz_document_handler *handler) – Register a document format handler (e.g. a custom renderer).

void fz_register_document_handlers(fz_context *ctx) – Register all built-in document handlers (PDF, XPS, EPUB, etc.).

util.h – High-Level Utilities Copy Chapter

#include "mupdf/fitz/util.h"

Convenience wrappers that combine several lower-level calls.

Display lists Copy Section

fz_display_list *fz_new_display_list_from_page(fz_context *ctx, fz_page *page) – Record the complete rendering of page into a reusable display list. Ownership of the returned display list is returned to the caller.

fz_display_list *fz_new_display_list_from_page_number(fz_context *ctx, fz_document *doc, int number) – As above, addressed by flat page number.

fz_display_list *fz_new_display_list_from_page_contents(fz_context *ctx, fz_page *page) – Record only the page content stream (no annotations).

Rendering to pixmaps Copy Section

fz_pixmap *fz_new_pixmap_from_page(fz_context *ctx, fz_page *page, fz_matrix ctm, fz_colorspace *cs, int alpha)

Render page to a freshly-allocated pixmap in one step.

• ctm – View transform (typically a scale + rotation).
• cs – Output colour space (e.g. fz_device_rgb(ctx)).
• alpha – Non-zero to include an alpha channel.

fz_pixmap *fz_new_pixmap_from_page_number(fz_context *ctx, fz_document *doc, int number, fz_matrix ctm, fz_colorspace *cs, int alpha) – Render page by flat page number.

fz_pixmap *fz_new_pixmap_from_display_list(fz_context *ctx, fz_display_list *list, fz_matrix ctm, fz_colorspace *cs, int alpha) – Render a display list to a pixmap.

fz_pixmap *fz_new_pixmap_from_page_contents(fz_context *ctx, fz_page *page, fz_matrix ctm, fz_colorspace *cs, int alpha) – Render page content only (no annotations).

Search Copy Section

int fz_search_page(fz_context *ctx, fz_page *page, const char *needle, int *hit_mark, fz_quad *hit_bbox, int hit_max)

Search for text on a page.

• needle – UTF-8 search string.
• hit_mark – Array of hit marks (length hit_max); filled on return.
• hit_bbox – Array of fz_quad hit rectangles (length hit_max).
• hit_max – Capacity of the hit arrays.
• Returns: Number of hits found (may be less than the actual count if capped).

int fz_search_page_number(fz_context *ctx, fz_document *doc, int number, const char *needle, int *hit_mark, fz_quad *hit_bbox, int hit_max) – Search by flat page number.

int fz_search_display_list(fz_context *ctx, fz_display_list *list, const char *needle, int *hit_mark, fz_quad *hit_bbox, int hit_max) – Search a display list.

Quick-start Example Copy Chapter

The following example renders page 0 of a PDF to a PNG file at 150 dpi:

#include "mupdf/fitz.h"

int main(void)
{
    fz_context *ctx = fz_new_context(NULL, NULL, FZ_STORE_DEFAULT);
    fz_register_document_handlers(ctx);

    fz_document *doc = NULL;
    fz_page     *page = NULL;
    fz_pixmap   *pix  = NULL;

    fz_try(ctx) {
        doc  = fz_open_document(ctx, "input.pdf");
        page = fz_load_page(ctx, doc, 0);

        /* 150 dpi = 150/72 scale */
        fz_matrix ctm = fz_scale(150.0f / 72, 150.0f / 72);
        pix = fz_new_pixmap_from_page(ctx, page, ctm,
                                      fz_device_rgb(ctx), 0);

        fz_save_pixmap_as_png(ctx, pix, "output.png");
    }
    fz_always(ctx) {
        fz_drop_pixmap(ctx, pix);
        fz_drop_page(ctx, page);
        fz_drop_document(ctx, doc);
    }
    fz_catch(ctx) {
        fprintf(stderr, "error: %s\n", fz_caught_message(ctx));
    }

    fz_drop_context(ctx);
    return 0;
}

Header File Index Copy Chapter

The following headers make up the complete public fitz API:

Notes Copy Chapter

• All string parameters are UTF-8 encoded unless otherwise noted.
• Page numbers are zero-based throughout the API.
• The fz_context is not thread-safe; create one context per thread
  using fz_clone_context and share the resource store via locks.
• Memory management follows a keep/drop pattern:
  fz_keep_* increments a reference count, fz_drop_* decrements it
  and frees when the count reaches zero.

Dict Support (`docs/dict-support.md`) Copy Section

Offline dictionary / word lookup — plan for future work

Status: research done (2026-07-11), no code yet. This is fork feature B from
plus-merge.md — port decision pending; the recommendation below
is to port the UI/plumbing but replace the data layer with a StarDict reader.

How the sumatrapdf-plus fork implements it Copy Chapter

Fork source (extract with git show plus/main:):

• src/WordLookup.{cpp,h} (~2,450 lines) — popup UI + lookup + dictionary loading
• src/LookupAudio.{cpp,h} — pronunciation playback (Media Foundation, decodes mp3 blobs)
• src/FloatingPopupStyle.{cpp,h} — shared popup chrome (we folded an equivalent
  into SelectionToolbar.cpp when porting feature H; factor it back out if porting this)
• cmd/import-oaldpex-dict.ts, cmd/import-xdhy7-dict.ts — offline converters
• Settings: OfflineDictionaryPath (dir; default {exedir}/dict),
  EnableDoubleClickWordLookup (bool, default true)
• Commands: CmdLookupSelection, CmdToggleDoubleClickWordLookup,
  CmdSearchSelectionWithYoudaoDict (online fallback, opens browser)

Invocation (three paths) Copy Section

1. Double-click a word on the canvas (EnableDoubleClickWordLookup). Routing
   in their Canvas.cpp double-click handler, gated on isOverText:
   • fixed-layout ebooks → ShowEbookWordLookupAt
   • CJK text → ShowChineseWordLookupAt: greedy longest-prefix match against the
     Chinese dictionary (8-hanzi window, 3-char look-back) since Chinese has no
     word boundaries
   • otherwise the double-clicked word → ShowWordLookup
2. CmdLookupSelection from palette/menu; also the "Look Up" button on their
   selection toolbar (we dropped that button in our feature-H port; re-add via
   CommandAvailability when this lands).
3. Youdao web fallback command (skip in our port, or generalize to the existing
   SearchSelectionWith* family).

Popup UI (custom-drawn, NOT HTML) Copy Section

Floating WS_POPUP card ~340px wide, rounded corners, theme-aware; shows:
headword + IPA transcription, part-of-speech tabs (max 8 senses), numbered
bilingual definitions (en/zh line pairs), one example sentence per sense, speaker
icon (hover/wave animation, plays pronunciation), loading-dots spinner (lookup on
a background thread), close button. Positions near the clicked word clamped to
the canvas; pauses read-aloud while open, resumes on close.

Caveat for porting: this layout is OALD-shaped (senses/tabs/bilingual pairs).
A generic dictionary reader needs a plain "formatted text entry" rendering mode
first; their rich layout becomes a special case.

Lookup pipeline Copy Section

normalize (trim + lowercase) → candidate list via hard-coded English morphology
(irregular plurals table, irregular verbs table, -s/-es/-ies/-ed/-ing stripping)
→ binary search over a fully-in-RAM sorted index → read entry slice from the data
file by offset/size → parse entry.

Their storage format ("SumatraDict" — bespoke, not a standard) Copy Section

What dictionaries they actually support Copy Section

Exactly two, via offline bun+Python converters (readmdict/mdict-utils +
BeautifulSoup) that scrape specific MDict (.mdx/.mdd) packages, with the
dictionaries' HTML class structure hardcoded:

• OALDPE(X) — community MDX repack of Oxford Advanced Learner's Dictionary
  10th ed with Chinese translations (copyrighted; circulates on Chinese
  dictionary forums; users must source it themselves)
• 现代汉语词典 7 (Contemporary Chinese Dictionary, monolingual)

Consequences: nothing works out of the box, converting requires Python, and the
only documented sources are pirated commercial content. Very China-centric.

Dictionary format landscape Copy Chapter

• StarDict (.ifo + .idx + .dict[.dz], optional .syn) — de-facto FOSS
  standard, best first target. Simple documented format: .idx is a sorted
  list of word\0 u32be-offset u32be-size; .dict.dz is dictzip (gzip with a
  random-access extra field); .ifo is key=value metadata (incl. sametypesequence,
  typically m/t/x/h = plain text / IPA / xdxf / html). .syn maps synonym
  strings to entry indexes. Readable natively with no converter. Big
  freely-licensed ecosystem: ECDICT, FreeDict, CC-CEDICT, JMdict, Wiktionary and
  WordNet exports. Used by GoldenDict, KOReader, etc.
• MDict (.mdx/.mdd) — dominant in China and for premium repacks (OALD, LDOCE).
  Reverse-engineered, zlib blocks, entries are full HTML (GoldenDict renders them
  with a browser engine), content mostly copyrighted. Don't implement natively;
  the fork's convert-offline approach is right for this one.
• DSL (ABBYY Lingvo source) — plain-text markup, popular in Russian-speaking
  communities. Feasible later.
• DICT/dictd, Babylon BGL, EPWING (Japanese), Slob (Aard2) —
  legacy/niche, skip.
• Freely-licensed data to point users at (or bundle): ECDICT (en↔zh, also
  distributed as StarDict), WordNet (English monolingual, permissive license),
  Wiktionary extracts (wiktextract JSON, all languages), CC-CEDICT (zh→en).

Recommended plan when porting Copy Chapter

1. Port from the fork mostly as-is: popup window shell, double-click/command
   invocation, CJK longest-prefix segmentation, English morphology fallbacks,
   async lookup thread, audio playback, settings + commands. Re-add the "Look Up"
   button to SelectionToolbar.cpp (gate via CommandAvailability, hidden when
   no dictionary is installed). Factor popup chrome back out of SelectionToolbar
   into a shared FloatingPopupStyle when both need it.
2. Replace the data layer: implement a native StarDict reader
   (.ifo/.idx/.dict.dz/.syn; dictzip random access is the only nontrivial
   part — gzip FEXTRA chunk table, inflate per-chunk). Keep the sorted-index +
   binary-search + slice-read architecture — it maps 1:1. Support multiple
   dictionaries in a directory, looked up in priority order.
3. Rendering: start with a plain-text entry renderer (StarDict m/t types;
   strip tags for h/x); keep the fork's rich sense/tab layout only if we also
   keep their SumatraDict format as an "enhanced" package format.
4. Converters: optionally keep/generalize the fork's MDX scripts but emit
   StarDict instead of a third format; document ECDICT/Wiktionary/WordNet as the
   out-of-the-box sources.
5. Port adaptation notes (same issues as features D/E/H): fork uses old Vec
   API (.Size()/.at() → len()/[]), utils/ → base/ includes, no
   #pragma once, str:: API drift, ThemeUsesDarkChrome() → check effective
   colors, PCH opt-out only if a file includes mupdf headers first (these don't).
   WordLookup.cpp touches Canvas/Toolbar/Theme/read-aloud — expect conflicts;
   port by feature diff, not cherry-pick.

Open questions for Krzysztof Copy Chapter

• Bundle a small freely-licensed dictionary with the installer, or download on
  first use, or leave entirely user-supplied?
• Is en↔zh bilingual layout worth special-casing, or is generic single-language
  rendering enough for the first version?
• Keep the Youdao command (China-centric) or fold online lookup into the existing
  SearchSelectionWith* handlers (e.g. Wiktionary web)?

Find Improvements Maybe (`docs/find-improvements-maybe.md`) Copy Section

Find UI — possible future improvements

Context: there are now two find UIs that share a backend:

• the compact Chrome-style overlay bar — src/FindBar.cpp / src/FindBar.h
  (FindBarWnd).
• the floating, movable/resizable find window with a results list —
  src/FindWindow.cpp / src/FindWindow.h (FindWindowWnd). It's enabled by the
  SearchUIFloating advanced setting and toggled by the pin/dock buttons.

Which one is active is chosen by gGlobalPrefs->searchUIFloating;
ShowFindBar/HideFindBar/FindBarSetStatus/FindBarSetMatchCaseChecked in
src/FindBar.cpp dispatch to whichever UI applies. The shared backend (the find
thread, the coalescing count thread that builds n / m + the per-match snippet
list MainWindow::findMatches, and GoToFindMatch) lives in
src/SearchAndDDE.cpp.

Items 1–2 came out of the first review (compact bar). Items 3+ came out of the
review of the floating-window feature (issue #4092) and were consciously
deferred (low severity, perf-only, or refactor-only). Each is self-contained.

1. Harden the match-count cache key against engine-pointer reuse Copy Chapter

Problem Copy Section

The "n / m" counter caches all match positions for the current search term so
prev/next is instant. The cache is keyed partly on the document's engine pointer:

• MainWindow::findCountEngine (a void*, declared in src/MainWindow.h) stores
  (void*)dm->GetEngine() for the document the cache was built against. It is
  compared, never dereferenced (see the comment on the field).
• UpdateMatchCount() in src/SearchAndDDE.cpp decides "cache hit" with:
  cpp Copy

  bool cacheHit = win->findCountValid && win->findCountText &&
                  str::Eq(win->findCountText, text) &&
                  win->findCountMatchCase == win->findMatchCase &&
                  win->findCountEngine == engine;   // <-- raw pointer compare

This correctly handles the common case (tab switch → different engine pointer →
cache miss → rescan). The hole: if the user reloads/replaces the document, the
old EngineBase is freed and a new engine can be allocated at the same
address. Then findCountEngine == engine is true again, the term + match-case
match, and the cache "hits" — showing n / m computed for the old document's
pages (wrong, possibly out-of-range indices) instead of rescanning.

Severity is low: requires a reload that reuses the exact address AND the same
search term + match-case still in the box. But it is a real stale-data bug.

Fix (sketch) Copy Section

Add a monotonically increasing "document generation" counter that bumps every
time a document is (re)loaded into a MainWindow/tab, and key the cache on that
instead of (or in addition to) the engine pointer.

• Add e.g. int docEpoch to the per-tab/DisplayModel state, bumped on load, OR a
  per-MainWindow int findCountDocGen bumped wherever the doc is swapped.
• Replace findCountEngine comparison with findCountDocGen == <current gen>.
• Invalidate the cache (win->findCountValid = false) on document load/close.
  The natural hook is wherever the old inline find UI used to be reset on load;
  LoadDocIntoWindow / UpdateFindbox in src/SumatraPDF.cpp /
  src/Toolbar.cpp are candidates — find where dm->textSearch / find state is
  reset on a new doc and bump the generation there.

Simplest correct version: in the doc-load path call a new
InvalidateFindCount(win) (set findCountValid = false, free findCountText).
Then the cache can never survive a reload and the pointer compare is no longer
load-bearing.

Files Copy Section

• src/MainWindow.h — cache fields (findCount*).
• src/SearchAndDDE.cpp — UpdateMatchCount, ShowMatchCount, StartFindCount,
  CountEndTask.
• doc-load path in src/SumatraPDF.cpp (search for where textSearch /
  selection is reset on load).

2. Replace FindBar's hand-rolled layout with the wingui layout engine Copy Chapter

Problem Copy Section

FindBarWnd::Layout() in src/FindBar.cpp positions its three children — the
Edit (search box), the status Static ("n / m"), and the embedded Win32
toolbar (prev/next/match-case/close) — with manual MoveWindow + a running x
cursor and hand-computed DPI gaps and vertical centering:

int p = DpiScale(hwnd, 6);
int gap = DpiScale(hwnd, 4);
...
MoveWindow(edit->hwnd, x, (barDy - editDy) / 2, editDx, editDy, TRUE);
x += editDx + gap;
MoveWindow(status->hwnd, ...);
x += statusDx + gap;
MoveWindow(hwndBtns, ...);
SetWindowPos(hwnd, ... barDx, barDy ...);

This duplicates the HBox/VBox + LayoutAndSizeToContent machinery in
src/wingui/Layout.h that src/CommandPalette.cpp already uses for the same
shape (an Edit plus a horizontal row of controls). The manual version re-derives
spacing/centering/RTL by hand, so any change (spacing, adding a control, RTL,
high-DPI) means re-doing pixel math and re-testing.

This is a refactor, not a bug — the current layout works and was visually
verified (incl. the SS_CENTERIMAGE fix that vertically centers the status).
Deferred because reworking it risks regressions for no user-visible gain.

Fix (sketch) Copy Section

Model on CommandPaletteWnd::Create in src/CommandPalette.cpp (look for
new HBox(), AddChild, Padding, and LayoutAndSizeToContent):

• Build an HBox with alignCross = CrossAxisAlign::CrossCenter containing the
  Edit, the status Static, and the buttons.
• Wrap children in Padding/Insets for gaps instead of manual += gap.
• The catch: the buttons are a raw Win32 TOOLBARCLASSNAME HWND, not a wingui
  Wnd, so it can't be added to an HBox directly. Options:
  1. Wrap the toolbar HWND in a thin ILayout/Wnd adapter that reports the
     toolbar's TB_GETMAXSIZE as its ideal size and MoveWindows on SetBounds.
  2. Replace the embedded toolbar with individual wingui controls (e.g. bitmap
     Buttons or owner-drawn statics) so everything is a Wnd — but that loses
     the toolbar's free tooltip + checked-state (BTNS_CHECK) handling, which is
     currently why a real toolbar is used (see tooltips via TTN_GETDISPINFOW in
     FindBarWnd::OnNotify and match-case TB_CHECKBUTTON in
     FindBarSetMatchCaseChecked).
• Option 1 (adapter) is the lower-risk path: keep the toolbar, just let the
  layout engine place it.

If/when this is done, also revisit the manual RTL handling (WS_EX_LAYOUTRTL on
the popup + the button toolbar, set in FindBarWnd::Create) — the layout engine
mirrors automatically, so the explicit exStyle may become unnecessary.

Files Copy Section

• src/FindBar.cpp — FindBarWnd::Create, FindBarWnd::Layout.
• src/wingui/Layout.h — HBox, VBox, Padding, LayoutAndSizeToContent.
• src/CommandPalette.cpp — reference implementation of the same shape.

3. Share a find-UI "core" between the compact bar and the floating window Copy Chapter

Problem Copy Section

FindWindowWnd (src/FindWindow.cpp) duplicates almost all of FindBarWnd
(src/FindBar.cpp): the Edit + status Static + a flat
TOOLBARCLASSNAMEW toolbar with the same prev/next/match-case buttons, the same
SetWindowTheme(hwnd, L"", L"") + NM_CUSTOMDRAW dark-background workaround, the
same BuildStdToolbarImageList + theme-rebuild logic, the same tooltip table +
TTN_GETDISPINFOW OnNotify, and the same OnTextChanged -> OnFindBarTextChanged
dispatch. The button/command tables and the two tooltip lookup functions
(FindBarButtonTooltip / FindWindowButtonTooltip) are three-quarters identical.

Every find-UI change (new button, icon, RTL/theme fix, the toolbar dark-bg hack)
now has to be made twice and kept byte-identical, and will silently drift.

Fix (sketch) Copy Section

Extract a FindUiCore that owns the edit + status + toolbar + the
OnFindBarTextChanged dispatch + tooltip table + the NM_CUSTOMDRAW/theme/
imagelist plumbing, and have both FindBarWnd (docked chrome) and
FindWindowWnd (popup caption + results list) embed it and only add their own
chrome. The toolbar differs by exactly one button (compact has Close at index 4;
floating has the dock button) — parameterize the button table.

This is the deepest of the deferred items and touches the most code; do it before
adding any more find-UI features, not after. The duplicated NM_CUSTOMDRAW
toolbar-bg fill is itself a near-copy of the main toolbar's custom draw in
src/Toolbar.cpp (line ~507) — a shared "theme a flat toolbar's background"
helper could serve all three.

Files Copy Section

• src/FindBar.cpp, src/FindWindow.cpp — the two near-duplicate window classes.
• src/Toolbar.cpp — the canonical toolbar custom-draw to factor against.

4. Results list: stop rebuilding the whole ListBox every keystroke Copy Chapter

Problem Copy Section

On every completed count (i.e. roughly every keystroke), CountEndTask ->
FindWindowRefreshResults -> FindWindowWnd::RefreshResults calls
FillWithItems (src/wingui/UIModels.cpp), which does ListBox_ResetContent
then one LB_ADDSTRING with a UTF-8 -> WStr conversion per item. For a common
term on a big document that's up to kMaxFindResults (5000) window messages +
5000 string conversions, tearing down and rebuilding the entire listbox just to
repaint ~25 visible rows. DrawResultItem already pulls text straight from
win->findMatches[i] by index, so the listbox's own string copies are pure waste.

Fix (sketch) Copy Section

Make the results listbox owner-data: create it with LBS_NODATA and, on refresh,
just send LB_SETCOUNT with win->findMatches.size() instead of FillWithItems.
The owner-draw path (FindWindowWnd::DrawResultItem) is already index-based, so no
per-item strings are needed. Check src/wingui/ListBox.cpp for whether the wingui
ListBox wrapper supports LBS_NODATA (the model API assumes string items) — may
need a small "virtual list" mode on the wrapper, or bypass the wrapper for the
count.

Files Copy Section

• src/FindWindow.cpp — RefreshResults, the ListBox::CreateArgs in Create,
  DrawResultItem.
• src/wingui/ListBox.cpp, src/wingui/UIModels.cpp — FillWithItems, listbox
  styles, model API.

5. Build result snippets lazily instead of all 5000 up front Copy Chapter

Problem Copy Section

CountThread (src/SearchAndDDE.cpp) calls BuildSnippet for every match up to
kMaxFindResults on every count, and the count runs on every keystroke.
BuildSnippet does engine->GetTextForPage (cheap — cached) + str::Dup +
NormalizeWSInPlace + ToUtf8Temp + str::FormatTemp + str::Dup (two heap
allocs + a normalize + a utf8 pass) per match. Only ~25 snippets are ever on
screen; the rest are allocated, then freed on the next keystroke, unseen.

Fix (sketch) Copy Section

Defer snippet construction to render time. Keep the count building the cheap
positions + the match coordinates (startPage/startGlyph/endPage/endGlyph) for
all matches, but build the snippet string lazily in DrawResultItem (or
FindResultsModel::Item) for the rows actually painted, caching it back into the
FindMatch (or a side cache keyed by index) so scrolling doesn't rebuild. Note
GetTextForPage is engine-thread-affine-ish; building snippets on the UI thread
at paint time is fine since the page text is cached by then, but confirm against
the concurrency rules (see GoToFindMatch / AbortFinding serialization).
Alternative/simpler: only rebuild snippets when the search term actually changed,
not on every count completion.

Files Copy Section

• src/SearchAndDDE.cpp — CountThread, BuildSnippet, FindMatch install in
  CountEndTask, kMaxFindResults.
• src/MainWindow.h — FindMatch (would gain a "snippet not yet built" state).
• src/FindWindow.cpp — DrawResultItem / FindResultsModel::Item.

6. Dispatch find status/match-case by actual visibility, not the preference Copy Chapter

Problem Copy Section

HideFindBar decides which UI to act on by actual visibility
(IsFindWindowVisible(win)), but FindBarSetStatus and
FindBarSetMatchCaseChecked (src/FindBar.cpp) decide by the persisted
preference (gGlobalPrefs->searchUIFloating). If the two ever disagree —
preference says floating but the compact bar is the one actually showing (or vice
versa) — a count completion routes the n / m status and the Match-Case checkbox
update to the hidden control, leaving the visible UI stale.

In normal flow ToggleFloatingFindUI keeps the preference and the visible UI in
sync, so this is currently latent, but it's a fragile coupling.

Fix (sketch) Copy Section

Make the status/match-case setters key off which UI is actually visible, mirroring
HideFindBar: if (IsFindWindowVisible(win)) { FindWindowSet...; return; } then
fall through to the compact bar. A tiny helper like
static bool UseFloatingFindUI(win) { return IsFindWindowVisible(win); } used by
all four dispatchers removes the preference-vs-visibility split.

Files Copy Section

• src/FindBar.cpp — FindBarSetStatus, FindBarSetMatchCaseChecked,
  ShowFindBar, HideFindBar (unify the dispatch predicate).

7. Binary-search the match lists instead of linear scans Copy Chapter

Problem Copy Section

FindWindowWnd::CurrentMatchIndex and FindWindowWnd::FirstMatchFromCurrentPage
(src/FindWindow.cpp) do an O(n) linear scan of win->findMatches on every
selection move (each arrow key, Next/Prev, and each RefreshResults). The matches
are already in page order (the count appends them in FindNext order, sorted by
(page, glyph)).

Fix (sketch) Copy Section

• FirstMatchFromCurrentPage: std::lower_bound on startPage >= curPage.
• CurrentMatchIndex: matches are sorted by (startPage, startGlyph), so a binary
  search works; simpler still, remember the index navigated to in GoToFindMatch/
  OnResultSelected and validate it instead of rescanning.

Low impact (n <= 5000, only on user input), pure cleanup.

Files Copy Section

• src/FindWindow.cpp — CurrentMatchIndex, FirstMatchFromCurrentPage.

8. Remove the vestigial `AbortFinding(win, hideMessage)` parameter + dead Kind Copy Chapter

Problem Copy Section

The "Searching n of m..." find-progress notification was removed (the find UI's
own n / m counter is the feedback now). ShowUI no longer creates it, so the
kNotifFindProgress Kind (src/SearchAndDDE.cpp line ~46) and the
RemoveNotificationsForGroup(..., kNotifFindProgress) in AbortFinding are dead
(the HideUI copy was already removed). With that gone, AbortFinding's
hideMessage bool parameter no longer does anything.

Left in place only because removing the parameter means editing all ~14 call
sites (src/FindBar.cpp, src/FindWindow.cpp, src/SearchAndDDE.cpp,
src/SumatraPDF.cpp) plus the declaration in src/SearchAndDDE.h.

Fix (sketch) Copy Section

Drop the hideMessage parameter from AbortFinding, remove the dead
RemoveNotificationsForGroup block, and remove the kNotifFindProgress Kind
declaration. Mechanical: AbortFinding(win, true/false) -> AbortFinding(win) at
every call site. Verify the one return-value user, OnFrameKeyEsc in
src/SumatraPDF.cpp (Esc consumed iff a find thread was aborted) — behavior is
unchanged because the notification path already always returned false.

Files Copy Section

• src/SearchAndDDE.cpp / src/SearchAndDDE.h — AbortFinding, kNotifFindProgress.
• ~14 call sites across src/FindBar.cpp, src/FindWindow.cpp,
  src/SearchAndDDE.cpp, src/SumatraPDF.cpp.

9. (Optional) restore a way to cancel a long explicit find mid-scan Copy Chapter

Problem Copy Section

With the progress notification gone, an explicit Find Next/Prev (or DDE
[Search], or a Match-Case re-run) on a huge document scans to completion with no
on-screen cancel affordance. Esc still cancels (OnFrameKeyEsc -> AbortFinding
sets findCancelled), and the Find toolbar buttons are disabled during the scan,
so this is minor — but there's no longer a visible "searching… (cancel)" control.

Fix (sketch) Copy Section

If it ever feels slow in practice, show a lightweight, cancelable status only
when an explicit find runs longer than e.g. 300 ms (a timer-armed notification, or
a spinner in the find UI's status area), rather than the old always-on
"Searching n of m..." flash. Most of the time the find is instant and nothing
should appear. Keep find-as-you-type silent (it self-cancels and defers to the
count thread; see UpdateFindStatus's showProgress check).

Files Copy Section

• src/SearchAndDDE.cpp — ShowUI / HideUI / UpdateFindStatus (the
  showProgress path), FindThreadData.

Location Chapters Plan (`docs/location-chapters-plan.md`) Copy Section

Plan: chapter-aware page locations (`Location`)

Status: implemented (phases 1-7). Each phase must build (bun cmd/build.ts -dbg) before
the next starts. Never commit; the user commits.

Why Copy Chapter

mupdf addresses pages as fz_location {chapter, page}. SumatraPDF predates that
and uses one flat 1-based pageNo everywhere. For a multi-chapter ebook this
forces laying out every chapter before the first page shows:

• EngineMupdf::FinishLoading calls fz_count_pages (lays out every EPUB
  chapter) and FinishNonPDFLoading then fz_load_pages every page.
• EngineMobi::FinishLoading runs HtmlFormatter::FormatAllPages over the
  whole book. C:\Users\kjk\OneDrive\!sumatra\1000.mobi (11.9 MB of HTML,
  886 <mbp:pagebreak> chapters, 3152 pages) takes 38 s to open in the
  release build (LoadDocument: 38069 ms). Target: well under 1 s.

Facts that shape the design (verified, do not re-derive) Copy Chapter

1. .mobi never reaches mupdf. EngineCreate.cpp routes it to
   CreateEngineMobiFromFile (our EngineEbook.cpp + MobiDoc). mupdf's
   mobi.c lacks HUFF/CDIC decompression and flattens a book into a single
   HTML chapter, so routing mobi through mupdf is not an option. Both engines
   need chapters: EPUB in EngineMupdf, MOBI in EngineEbook.
2. mupdf's fz_bookmark is an in-memory fz_html_flow* pointer
   (html-outline.c: fz_make_html_bookmark). It cannot be persisted. The
   persisted "bookmark" is therefore ours: chapter:page:pagesInChapter
   (proportional restore when the chapter re-paginates), and for EngineEbook
   the exact reparseIdx byte offset that FileState.ReparseIdx was designed
   for. fz_make_bookmark/fz_lookup_bookmark are not used.
3. In mupdf only EPUB has >1 chapter (epub_count_chapters = spine length).
   fb2/html/txt/md are htdoc single-chapter; XPS/PDF single-chapter. EPUB
   chapter layout is already lazy inside mupdf (count_chapter_pages lays out
   one chapter on demand); what forces the full layout is our use of
   fz_count_pages / fz_load_page / fz_load_outline.
4. fz_load_outline resolves every outline node with fz_resolve_link
   (outline.c:118), which lays out every chapter a fragment link points into.
   Use fz_new_outline_iterator and keep the URI; resolve on click.
5. Our page numbers are 1-based. Location is therefore 1-based in both
   fields; fz_location is {loc.chapter - 1, loc.page - 1}.
6. FileState.ReparseIdx (cmd/gen-settings.ts:997) is unused today.

Design Copy Chapter

`Location` Copy Section

// src/EngineBase.h
struct Location {
    int chapter = 0; // 1-based, 0 = invalid
    int page = 0;    // 1-based within chapter, 0 = invalid
    bool IsValid() const { return chapter >= 1 && page >= 1; }
    bool operator==(const Location&) const; bool operator!=(const Location&) const;
};
inline Location LocFromPageNo(int pageNo) { return {1, pageNo}; } // single-chapter docs

Flat `pageNo` stays the view index; chapters may be _unlaid_ Copy Section

The app keeps using a flat 1-based pageNo (DisplayModel, RenderCache, text
selection, etc.). What changes: a chapter that has not been laid out counts as
1 placeholder page in the flat numbering. When a chapter gets laid out (on
first render / text extraction / explicit navigation into it) its real page
count replaces the placeholder and every later pageNo shifts. So:

• The engine owns a chapter table (ChapterTable, see below): per chapter
  {pageCount, laidOut}, prefix sums, and a generation counter bumped on
  every count change. EngineBase::pageCount is always the table's total.
• State that must survive a shift holds a Location, not a pageNo:
  ScrollState, nav history, pending scroll, RenderCache entries, TOC/link
  destinations. DisplayModel re-syncs (SyncWithEngineLayout) whenever the
  engine generation differs from its own, rebuilding pagesInfo and restoring
  the position from Location.
• Placeholder = 1 page keeps things deterministic (no estimates). All pages of
  a reflowable doc share one mediabox, so placeholders have a known size and
  never force layout just to be measured.

chapter:      1       2      3     4 ... 886
  laid out:    yes      no    yes    no
  pages:      1 2 3 4   [1]   1 2   [1]        <- [1] = placeholder
  pageNo:     1 2 3 4    5    6 7    8
  after laying out chapter 2 (3 pages): pageNo 6,7 -> 8,9 ; generation++

Engine-side contract (`EngineBase`) Copy Section

Non-virtual, backed by ChapterTable chapters (a member; single-chapter engines
never touch it and behave exactly as today):

int  ChapterCount();                      // 1 when no chapters
bool HasChapters();                       // ChapterCount() > 1
int  ChapterPageCount(int chapter);       // lays out that chapter (real count)
bool IsChapterLaidOut(int chapter);
Location LocationFromPageNo(int pageNo);  // table lookup, never lays out
int  PageNoFromLocation(Location loc);    // lays out loc.chapter first, clamps loc.page
Location NextLocation(Location), PrevLocation(Location); // cross chapter edges; lays out target chapter
Location FirstLocation(), LastLocation(); // last lays out the last chapter
Location ClampLocation(Location);         // lays out loc.chapter, clamps
int  LayoutGeneration();                  // atomic read
void EnsureAllChaptersLaidOut(ProgressUpdateUI* = nullptr); // print / dump / full search
virtual TempStr MakeBookmarkTemp(Location);   // default: "%d:%d:%d" chapter:page:ChapterPageCount
virtual Location LookupBookmark(Str);         // default: parse; scale page by newCount/oldCount
virtual Location ResolveDest(IPageDestination*); // default {1, dest->pageNo}; caches into dest

One virtual for engines with chapters:

virtual int LayOutChapter(int chapter); // returns real page count; engine calls chapters.SetPageCount()

ChapterTable (new src/ChapterTable.h/.cpp, unit-tested via -unit-tests):
Init(nChapters), SetPageCount(chapter, n) (bumps generation when changed),
TotalPages(), LocationFromPageNo, PageNoFromLocation (pure, no layout),
IsLaidOut, Generation(). Thread-safe (mutex; generation atomic). Engines
call SetPageCount from whatever thread lays out (render thread included).

Per-page virtuals (PageMediabox(int pageNo), RenderPage, ...) keep int pageNo; engines convert with LocationFromPageNo at entry. Page-keyed engine
storage (EngineMupdf::pages, EngineEbook::pages, EngineBase::pagesText)
becomes per-chapter (Vec<Vec<T*>>, chapter-major) so a shift never
re-associates cached data with the wrong page.

Structs carrying a page: IPageDestination, TocItem, IPageElement,
RenderPageArgs gain Location loc. pageNo stays as the cached flat value
(-1 = unresolved). TocItem::pageNo == -1 with a valid dest means
"resolve on click".

Lazy resolution of destinations Copy Section

• EngineMupdf: TOC built from fz_new_outline_iterator (no fz_load_outline).
  For chaptered docs a TOC item stores only the URI and gets loc = {chapter,0}
  by resolving the URI without its fragment (epub_resolve_link returns the
  spine index without layout when there is no #). ResolveDest does the full
  fz_resolve_link_dest (lays out one chapter) and caches loc/pageNo.
• EngineEbook (mobi): TOC and links are filepos byte offsets. Chapter =
  binary search of the offset in the chapter-start table (no formatting);
  page = format that chapter, then the existing reparseIdx scan.
• LinkHandler::ScrollTo(IPageDestination*) and GoToTocLink call
  ctrl->ResolveDest(dest) and navigate by Location.

`DisplayModel` Copy Section

• PageCount() returns a snapshot taken by BuildPagesInfo, not the live
  engine count. PageInfo gains Location loc.
• SyncWithEngineLayout(): if engine->LayoutGeneration() != layoutGeneration
  → remember CurrentLocation() + scroll offset, rebuild pagesInfo, Relayout,
  restore via GoToLocation, renderCache->RekeyForLayoutChange(this),
  cb->PagesRenumbered(this). Called at the top of RepaintDisplay,
  RecalcVisibleParts, GoToPage, CurrentPageNo and from the render-done
  callback path (RenderCache → UI thread).
• Location CurrentLocation(), GoToLocation(Location, bool addNavPoint)
  (= PageNoFromLocation → sync → GoToPage).
• GoToNextPage/GoToPrevPage/GoToLastPage for chaptered docs go through
  NextLocation/PrevLocation/LastLocation so "prev" from chapter 6 page 1
  lands on the last page of chapter 5 even if chapter 5 was never laid out.
  Single-chapter docs keep the current row-based code path untouched.
• ScrollState gains Location loc; GetScrollState fills it,
  SetScrollState prefers loc when valid (nav history survives shifts).
• RenderCache: BitmapCacheEntry gains Location loc (from
  PageInfo::loc); RekeyForLayoutChange(dm) recomputes pageNo from loc
  and drops entries whose loc no longer maps. RenderPageArgs::loc is what
  EngineMupdf/EngineEbook actually render (they ignore pageNo when loc
  is valid) so a shift between request and render cannot draw the wrong page.
• DocControllerCallback::PagesRenumbered(DisplayModel*): SumatraPDF.cpp
  clears selection, aborts an in-progress find, refreshes toolbar / tab /
  page-info / TOC selection, repaints.

Persistence (`FileState` / `TabState`) Copy Section

PageNo changes from Int to Str in cmd/gen-settings.ts (both structs;
Favorite.PageNo stays Int). Value grammar, parsed by one helper
(src/PagePosition.h/.cpp: ParseStoredPage(Str) -> {int pageNo; Str bookmark},
FormatStoredPageTemp(...)):

• "12" – flat page number (legacy files and every single-chapter document)
• "bm:" + engine bookmark – chaptered documents, e.g. bm:37:2:5
  (EngineMupdf: chapter:page:pagesInChapter) or bm:37:2:5:r1834211
  (EngineEbook adds the exact reparseIdx). Prefix kBookmarkPrefix = "bm:".

Old builds parse bm:... as int 0 → open at page 1 (acceptable). New builds
read old integers unchanged. FileState.ReparseIdx stays declared (compat) but
is no longer written. SetTabState / LoadDocIntoCurrentTab / NewTabState
/ CloneTabState / GoToFavorite's FileState hack / RememberSessionState
all go through the helper. -page N, DDE GotoPage, -dbg-control keep
flat page numbers (LocationFromPageNo).

UI, only when `ctrl->HasChapters()` Copy Section

• Toolbar: Page: → [chapter edit] / 886 [page edit] / 4. Second Edit
  created by ToolbarCreatePageEdit (chapter variant), two VirtText totals,
  hit-test / show-hide / theming / teardown mirror the existing page edit.
  Enter in either edit → GoToLocation({chapterEdit, pageEdit}).
  PageNoChanged fills both edits from CurrentLocation().
• Go To Page dialog: two edits (Chapter (of 886), Page (of 4)), OnOk
  builds a Location, ClampLocation, GoToLocation.
• Page-info notification and tab suffix: Ch 37 / 886, page 2 / 5.
• TOC: click resolves lazily (above); UpdateTocSelection matches by
  loc.chapter when pageNo == -1.
• Print, EngineDump, full-document text search, PDF export, stress test:
  call EnsureAllChaptersLaidOut() first (this is today's open cost, now
  paid only when the user asks for a whole-document operation).

Out of scope (explicitly) Copy Section

Favorites keep flat page numbers. Annotations / forms are PDF-only (no
chapters). EngineEpub/EngineFb2 fallbacks in EngineEbook.cpp stay
single-chapter. No mupdf patch is needed (no ext/patches change).

Phases Copy Chapter

Order: 1 → 4 → 2 → 3 → 5 → 6 → 7 (view-side plumbing before any engine
reports chapters, so a PDF-only tree stays correct at every step).

Each phase: implement, clang-format touched src/ files, build debug,
fix warnings, run the named checks. Report what was verified and what was not.

Phase 1 – `Location` + `ChapterTable` + `EngineBase` contract Copy Section

Files: src/EngineBase.h/.cpp, new src/ChapterTable.h/.cpp (+ premake
file list premake5.files.lua), src/AppUnitTests.cpp or a _ut.cpp next to
it for ChapterTable tests (bun cmd/run-unit-tests.ts -dbg).
Adds Location, ChapterTable, the non-virtual chapter API, LayOutChapter,
bookmark defaults, ResolveDest, loc fields on IPageDestination,
TocItem, IPageElement, RenderPageArgs (default {}; NewSimpleDest /
AllocTocItem set loc = LocFromPageNo(pageNo) when pageNo >= 1).
pagesText/pagesTextState become chapter-major and are (re)allocated per
chapter on first use. No behavior change for existing engines.

Phase 2 – `EngineMupdf` lazy EPUB chapters Copy Section

• FinishLoading: chapters.Init(fz_count_chapters); count chapter 1 only
  (fz_count_chapter_pages(ctx, doc, 0)); no fz_count_pages when
  ChapterCount() > 1. LayOutChapter(ch) = fz_count_chapter_pages under
  docLock + chapters.SetPageCount.
• FinishNonPDFLoading: for isReflowable fill mediaboxes from the layout
  size (ebookLayoutW/H in points; verify against page 1's fz_bound_page)
  instead of loading every page. Non-reflow (XPS) keeps the loop.
• pages → chapter-major; GetFzPageInfoLocked takes a Location, loads
  with fz_load_chapter_page, then refreshes the chapter count (a placeholder
  chapter becomes real here) and grows that chapter's FzPageInfo vector.
  Every pages[pageNo - 1] / pi->pageNo use goes through helpers.
• TOC via outline iterator; ResolveDest for PageDestinationMupdf;
  HandleLinkMupdf returns a Location. Heading-TOC background scan and
  page-label scan skipped when HasChapters().
• ApplyReflowThemeCss: drop the "keeping pageCount" hack; re-Init the
  table (all chapters unlaid), bump generation; DisplayModel restores position.
• src/libsumatrapdf.def: add fz_count_chapter_pages,
  fz_location_from_page_number (if used).
• Check: open C:\Users\kjk\OneDrive\!sumatra\Dune - Frank Herbert.epub with
  -log-to-file, confirm LoadDocument ms drops and only chapter 1 is laid
  out at open (log the chapter count / laid-out count); page through with
  CmdGoToNextPage via -dbg-control and confirm no crash and page count grows.

Phase 3 – `EngineEbook` lazy MOBI chapters Copy Section

• EngineEbook gains chapter starts: scan doc->GetHtmlData() once for
  <mbp:pagebreak (case-insensitive) → Vec chapterStart (chapter 1
  starts at 0). Only EngineMobi enables it; when no marker is found the
  document stays single-chapter and formats as today.
• pages → chapter-major Vec<Vec<HtmlPage*>*>. LayOutChapter(ch) formats
  Str(html.s + start, end - start) with MobiFormatter, adds start to every
  HtmlPage::reparseIdx and anchor offset, extracts that chapter's anchors
  (ExtractPageAnchors becomes per-chapter), and calls
  chapters.SetPageCount. Guard with pagesAccess. Check how
  HtmlFormatter treats a truncated slice (unclosed tags) and that
  GumboHtmlParser positions stay slice-relative.
• GetNamedDest(filepos): chapter by binary search over chapterStart, lay
  it out, then the existing page scan within that chapter. ResolveDest for
  ebook TOC dests (pageNo == -1, name = filepos).
• MakeBookmarkTemp appends :r<reparseIdx of loc's page>; LookupBookmark
  uses it when present (chapter from the table, page by reparseIdx scan).
• Check: 1000.mobi LoadDocument well under 1 s in a release build
  (bun cmd/build.ts -rel, -log-to-file), first page renders,
  next/prev across a chapter edge, TOC click into a far chapter.

Phase 4 – `DisplayModel` / `RenderCache` / `DocController` Copy Section

As in the design: PageInfo::loc, snapshot PageCount, SyncWithEngineLayout,
CurrentLocation/GoToLocation, chapter-aware next/prev/last, ScrollState::loc,
RenderCache re-keying + RenderPageArgs::loc, PagesRenumbered callback,
DocController additions (HasChapters, CurrentLocation, GoToLocation,
ResolveDest, ChapterCount, ChapterPageCount; ChmModel/MarkdownModel use
the single-chapter defaults). LinkHandler navigates by Location.
Check: PDF behavior unchanged (bun tests/issue-5949.ts or whichever tests
grep as page-navigation related), EPUB/MOBI continuous mode scrolls through
chapter edges without position jumps.

Phase 5 – persistence Copy Section

cmd/gen-settings.ts (PageNo → Str in FileState and TabState, doc
strings updated), bun cmd/gen-code.ts, src/PagePosition.h/.cpp, all
read/write sites listed in the design, sumatra-website/www/docs/Advanced-options-settings.md
regenerated. Check: a settings file with PageNo = 12 still opens a PDF at
page 12; closing an EPUB at chapter 37 and reopening lands in chapter 37; an
old-style int for an EPUB still opens at that flat page.

Phase 6 – UI for chaptered documents Copy Section

Toolbar, Go To Page dialog, page-info notification, tab suffix, TOC selection,
EnsureAllChaptersLaidOut at print / dump / full search / PDF export /
stress. Check with -dbg-control + screenshot (see verify skill).

Phase 7 – tests + docs Copy Section

• tests/ad-hoc-chapters.ts: opens 1000.mobi and an EPUB, asserts load time
  and chapter navigation through -dbg-control (add ChapterInfo /
  GoToLocation control commands if needed).
• tests/issue-*.ts-style regression for settings backward compat.
• sumatra-website/www/docs/Version-history.md entry (behavior change: chapter/page toolbar for
  multi-chapter ebooks, much faster open), sumatra-website/www/docs/Commands.md only if a
  command was added.

Outcome Copy Chapter

• 1000.mobi (892 chapters): LoadDocument 97.5 ms in a release build and
  ~140 ms in a debug build (was 38069 ms in release before this work) — under the "well under 1 s" target
  with headroom to spare, in the slower build config.
• Dune - Frank Herbert.epub: 62 chapters; toolbar reads Chapter: [n] / 62,
  Page: [n] / M.
• Two bugs found by tests/ad-hoc-chapters.ts and fixed in Phase 7:
  • EngineMobi::LayOutChapter asserted (ReportIf) when the UI thread and
    the render thread raced to lay out the same not-yet-laid-out chapter.
    Made idempotent: whichever caller wins keeps its result, the loser's
    redundant format is discarded.
  • DisplayModel::GoToNextPage/GoToPrevPage/GoToLastPage only used the
    chapter-aware Location crossing in non-continuous display modes.
    Continuous mode (EPUB's default) fell through to the flat row-based path,
    so CmdGoToPrevPage crossing into an unlaid previous chapter landed on
    its 1-page placeholder instead of its real last page. Fixed by dropping
    the non-continuous restriction for chaptered docs.
• tests/tmp/toolbar-epub.png/toolbar-pdf.png: confirmed the Bookmarks
  sidebar showing empty-title dots under "Book One - DUNE" is pre-existing
  (reproduces on the pre-Phase-1 baseline via git stash), not caused by
  this work; left unfixed.

Ocr Ux Ideas (`docs/ocr-ux-ideas.md`) Copy Section

OCR UX ideas for SumatraPDF

UX-focused proposal for adding OCR to SumatraPDF. Fits existing patterns: lightweight reader, command palette for newer features, notifications for feedback, copy/find/read-aloud as the main text workflows. No implementation details.

Design principle Copy Chapter

OCR in SumatraPDF should not feel like a separate “OCR app.” It should unlock text the user already expects: select, copy, find, read aloud, and screen-reader access. The mental model is “recognize text”, not “run OCR.”

Results should behave like normal PDF text: invisible overlay, I-beam cursor, existing shortcuts unchanged. No dedicated OCR panel or correction editor — that’s out of character for SumatraPDF.

What to offer (three scopes) Copy Chapter

Default recommendation: ship page and selection first; whole document as an explicit, confirmed action (progress UI, cancel). Region OCR is especially valuable because scans are often mixed (cover + text pages) and full-doc OCR is slow.

Session-only by default: recognized text lives for this open document until close. No “Save OCR’d PDF” in v1 — keeps the reader/editor boundary clean. Export-to-text-file can be a later, optional command.

When to suggest it (progressive disclosure) Copy Chapter

Don’t auto-OCR on open (CPU, privacy, wrong language). Detect likely scanned content (HasTextForPage is already the signal) and nudge at the moment of need:

1. On open (once per document): a dismissible notification:
   “This document has little selectable text. Recognize text to enable search and copy?”
   Actions: Recognize on this page · Whole document… · Don’t ask again for this file

2. When Find is used on a no-text page: enable Find but show in the find bar: “No text on this page — [Recognize text]”

3. When Copy / Select All yields only an image (today copy falls back to image):
   “No text here. Recognize text on this page?” with the same action link

4. Read Aloud already says “No text available…” — extend that path with Recognize text, then read (one combined flow, not two separate concepts)

These moments teach the feature without adding permanent chrome.

Where to put it in the UI Copy Chapter

Primary (discoverable) Copy Section

• Command palette (Ctrl+K): “Recognize Text” with sub-actions or a second step: This page / Selection / Whole document…
  Same discovery pattern as Read Aloud and Advanced Options.

• Edit menu (or View if Edit is crowded): one item “Recognize Text” → submenu matching the three scopes. Keeps the menu bar honest for users who don’t use the palette.

Contextual (high intent) Copy Section

• Right-click on page (no text under cursor): “Recognize Text on This Page” — only when the page has no text layer.

• Right-click on rectangular selection (image-only area): “Recognize Text in Selection” — sits near Copy, above or below it.

• Find toolbar / find box — inline link when search can’t run on current page (mirrors how image collections already disable Find in the menu).

Do *not* add (v1) Copy Section

• Toolbar button (too niche for permanent space; Read Aloud earned its slot as accessibility)
• Status-bar mode toggle
• Separate “OCR layer” preview

Progress and feedback Copy Chapter

Use the same family as printing notifications:

• Non-modal toast: “Recognizing text… page 3 of 47” with Cancel
• On completion: “Text recognized on 12 pages. You can now search and copy.” (auto-dismiss)
• On failure: short message + retry; no modal error storm

Optional subtle cue: after OCR, pages could show a one-time tooltip on first successful text selection — “Recognized text (session only)” — so power users know it isn’t embedded in the file.

Settings (Advanced Options) Copy Chapter

Keep OCR mostly invisible; expose only what affects behavior:

• OCR languages (multi-select, default from system/UI language)
• Prompt when opening scanned PDFs (on / off)
• Recognize text in background while reading (off by default) — only if whole-document OCR exists; otherwise skip

No tessdata paths or engine knobs in the main UI.

How it plugs into existing features Copy Chapter

After recognition, nothing new to learn:

Mixed PDFs: only run OCR on pages without text; don’t re-OCR pages that already have a layer.

What to defer Copy Chapter

• In-app OCR correction / proofreading UI
• Embedding text into the PDF and Save
• Batch folder OCR
• Command-line OCR flags (unless power users ask later)
• “OCR to HTML/SVG” export (MuPDF tool territory, not reader UX)

Suggested v1 story (one sentence for users) Copy Chapter

“If a scan has no selectable text, choose Recognize Text — then search, copy, and read aloud work like a normal PDF, for this session.”

That stays aligned with SumatraPDF: small surface area, palette + contextual prompts, and making existing commands work instead of shipping a new subsystem.

Related existing behavior Copy Chapter

• HasTextForPage() — no glyph hit-testing when page has no text (DisplayModel.cpp)
• Image collections — Find disabled (Menu.cpp); selection/copy limited (Selection.cpp, SearchAndDDE.cpp)
• Read aloud — shows “No text available…” when page lacks text (SumatraPDF.cpp)
• Copy on restricted/no-text pages — may copy as image with notification (Selection.cpp)
• MuPDF has tessocr integration (ext/mupdf/source/fitz/tessocr.cpp); tool-draw docs mention OCR output formats but mark some as disabled

Pdf Form Filling Plan (`docs/pdf-form-filling-plan.md`) Copy Section

PDF form filling — implementation plan

Goal: let the user fill interactive PDF (AcroForm) fields directly on the page
— click a text field and type, click a checkbox to toggle, click a dropdown to
pick — no side panel, no modal dialog. Save reuses the existing annotation-save
pipeline.

Scope (v1): text fields (single + multiline), checkboxes, radio buttons,
comboboxes, listboxes. Defer: digital signatures, XFA-only forms, push
buttons that run arbitrary JS, barcode fields.

Implementation status — DONE (phases 0–4, all on master) Copy Chapter

Built and validated against f1040.pdf (a hybrid-XFA form whose AcroForm layer
fills fine) plus a synthetic formtest.pdf for the field types the 1040 lacks.

JavaScript form calc — WORKING (`2f9fb05f5` enable + `24603fc57` mupdf fix) Copy Section

mupdf JS is compiled in (FZ_ENABLE_JS=1, mujs one.c, pdf-js.c).
FinishLoading now calls pdf_enable_js(ctx, pdfdoc) (replacing the old
// TODO: support javascript assertion), so doc->js is live and edits run
pdf_update_page → pdf_calculate_form.

Cross-field calc works: verified on a JS form total = a + b — the total
recomputes on every edit (10 + 20 → 30, then a = 7 → 27).

Getting there needed an upstream mupdf bug fix (24603fc57): doc_getField
and doc_resetForm in pdf-js.c called the NULL-terminated variadic
pdf_dict_getl(ctx, trailer, Root, AcroForm, Fields) without the trailing
NULL, so the va_arg loop read stack garbage as an extra dict key and
getField() returned null non-deterministically (it surfaced in our build's
stack layout). Adding the NULL — which every other call site already has —
makes getField reliable, so sums/totals compute.

• Security note: enabling JS runs document-level / open scripts and
  broadens the mujs attack surface vs the previous JS-off default. mujs itself
  is sandboxed to the PDF/form API (no file/network).

Other still-open polish: cross-page Tab (navigation is currently same-page),
comb cells aren't drawn in the edit overlay (plain edit + max-length only),
XFA-only forms fall back to read-only.

Reference implementation analyzed: ext/mupdf/platform/gl/gl-form.c,
gl-input.c, gl-main.c (the mupdf OpenGL viewer's form filling). It polls
widgets each frame and edits text/choice in a modal dialog; we want
in-place editing instead, but the mupdf API surface and the
mutate → update → re-render loop are the same.

1. What already exists in SumatraPDF (leverage, don't rebuild) Copy Chapter

• Widgets are already rendered. The page render path runs widget appearance
  streams: EngineMupdf.cpp:3538-3541 (pdf_run_page_widgets_with_usage /
  pdf_run_page_with_usage). So a checked checkbox / filled text already shows;
  they're just non-interactive.
• Widgets are already hit-testable. GetFzPageInfo walks
  pdf_first_annot/pdf_next_annot (includes widgets) into pi->annotations
  (EngineMupdf.cpp:3261-3271); EngineMupdfGetAnnotationAtPos
  (EngineMupdf.cpp:4660-4704) returns the smallest annot containing a point —
  widgets included. AnnotationType::Widget exists (Annotation.h, value 20 ==
  PDF_ANNOT_WIDGET).
• Mutation → re-render pipeline exists. Every annotation setter in
  Annotation.cpp (e.g. SetContents 351-373) does: ScopedCritSec(&docLock) →
  pdf_set_* → pdf_update_annot → (outside docLock) MarkNotificationAsModified
  which drops pageInfo->displayList under renderLock and sets the dirty flag
  (EngineMupdf.cpp:4721-4775); the caller then calls MainWindowRerender
  (SumatraPDF.cpp:2917). Form edits funnel through the same path.
• Save / dirty / unsaved-changes is reusable as-is. modifiedAnnotations →
  EngineMupdfHasUnsavedAnnotations (EngineMupdf.cpp:4610) →
  EngineMupdfSaveUpdated / pdf_save_document (~4390) → CmdSaveAnnotations
  (Ctrl+Shift+S). A filled field is just a modified pdf_obj.
• Coordinate mapping exists. DisplayModel::CvtFromScreen(Point/Rect,pageNo)
  (1197/1216) for click→page; CvtToScreen(pageNo, RectF) (1191) to place an
  overlay over a field rect; GetPageNoByPoint (1097).
• Floated child-edit pattern exists. HomePage.cpp:962 creates a WC_EDITW
  as a child of win->hwndCanvas — exactly the pattern for an in-place text box
  over a field.

2. What's missing (the actual work) Copy Chapter

1. Classify a widget: type (text/checkbox/radio/combo/listbox/signature),
   field flags (read-only, multiline, password, comb, required), value, options.
2. Mutate a widget value through mupdf under docLock, regenerate appearance,
   invalidate.
3. Route input: a click-a-field branch in the canvas, a keyboard/focus
   path (there is no canvas keyboard handler today — keyboard is frame-level),
   and a per-window "field being edited" state.
4. The direct-manipulation overlays: floated edit for text, dropdown for choice,
   immediate toggle for buttons; field highlight + Tab navigation.

3. mupdf API surface (verified against gl-form.c / form.h / annot.h) Copy Chapter

Enumerate / classify:

• pdf_annot *pdf_first_widget(ctx, pdf_page*), pdf_next_widget(ctx, pdf_annot*)
• enum pdf_widget_type pdf_widget_type(ctx, pdf_annot*) →
  PDF_WIDGET_TYPE_{BUTTON,CHECKBOX,COMBOBOX,LISTBOX,RADIOBUTTON,SIGNATURE,TEXT}
• fz_rect pdf_bound_widget(ctx, pdf_annot*) (page space)
• int pdf_annot_field_flags(ctx, pdf_annot*) → PDF_FIELD_IS_READ_ONLY,
  PDF_TX_FIELD_IS_MULTILINE|PASSWORD|COMB, PDF_BTN_FIELD_IS_RADIO|PUSHBUTTON,
  PDF_CH_FIELD_IS_COMBO|EDIT|MULTI_SELECT, PDF_FIELD_IS_REQUIRED, …
• const char *pdf_annot_field_label(ctx, pdf_annot*),
  const char *pdf_annot_field_value(ctx, pdf_annot*)
• int pdf_text_widget_max_len(ctx, pdf_annot*),
  int pdf_text_widget_format(ctx, pdf_annot*) (NONE/NUMBER/SPECIAL/DATE/TIME)

Read/write values:

• Text commit (runs validate/format/calculate/JS):
  int pdf_set_text_field_value(ctx, pdf_annot*, const char *value) — returns
  true if accepted.
• Text live keystroke filter (maxlen/comb/format, no side effects):
  int pdf_edit_text_field_value(ctx, pdf_annot*, value, change, int *selStart, int *selEnd, char **newvalue).
• Choice: int pdf_choice_widget_options(ctx, pdf_annot*, int exportval, const char *opts[]) (call with NULL to get count), pdf_choice_widget_value,
  int pdf_set_choice_field_value(ctx, pdf_annot*, const char *value),
  pdf_choice_widget_is_multiselect.
• Checkbox/radio: int pdf_toggle_widget(ctx, pdf_annot*) (used by gl-form.c:740-744;
  confirm it's present in our mupdf header during Phase 0 — fallback is
  pdf_button_field_on_state + pdf_set_field_value / the event helpers).
• Generic: int pdf_set_annot_field_value(ctx, pdf_document*, pdf_annot*, text, int ignore_trigger_events).

Event triggers (run the field's AA JavaScript; optional for v1):
pdf_annot_event_{enter,exit,down,up,focus,blur}(ctx, pdf_annot*).

Re-render / recalc:

• int pdf_update_page(ctx, pdf_page*) — regenerates out-of-date appearance
  streams, runs form recalc, returns true if redraw needed. (gl-main.c:1101.)
• int pdf_update_annot(ctx, pdf_annot*) — per-annot version (annot.h:881).
• int pdf_update_open_pages(ctx, pdf_document*) — a JS calculate can change a
  field on another page; use after edits if the form has calculations.

Important header note (annot.h:865-899): pass the same pdf_annot* objects
to pdf_update_annot that were last used to render; don't reload page/annots in
between or change-tracking breaks. Our display-list cache already keeps them
stable per FzPageInfo.

4. Architecture (three layers) Copy Chapter

4a. Engine layer — `EngineMupdf.cpp` + `Annotation.cpp` Copy Section

New, thin, mirroring the existing annotation setters (same locking):

• WidgetInfo EngineMupdfGetWidgetInfo(Annotation*) → { widgetType, fieldFlags, value, label, maxLen, txFormat, options[] } (read under docLock/ctx).
• bool EngineMupdfSetWidgetText(Annotation*, const char* val) →
  docLock { pdf_set_text_field_value; pdf_update_annot }, then (outside docLock)
  MarkNotificationAsModified.
• bool EngineMupdfToggleWidget(Annotation*) → pdf_toggle_widget (or set state).
• bool EngineMupdfSetWidgetChoice(Annotation*, const char* val) /
  ...GetWidgetChoices(...).
• Optional Annotation* EngineMupdfGetWidgetAtPos(...) that skips read-only and
  signature widgets and returns type info, layered on GetAnnotationAtPos.

Re-render: after a successful set, call the existing MarkNotificationAsModified

• MainWindowRerender(win). For forms with JS calculations, also
  pdf_update_open_pages before rerender (Phase 4).

4b. Input layer — `Canvas.cpp` + a per-window editing state Copy Section

• New state on WindowTab/MainWindow: Annotation* editedWidget (+ overlay
  HWND, page no). A MouseAction or a separate flag for "editing a field".
• Left button down (OnMouseLeftButtonDown, Canvas.cpp:1281, annot branch
  ~1311): if annot->type == Widget and not read-only, intercept before the
  drag/selection path. Classify:
  • checkbox/radio → toggle immediately, re-render, done.
  • text → begin in-place text edit (4c).
  • combobox/listbox → open dropdown (4c).
  • signature/pushbutton → ignore (v1) or show info.
• Hover (OnMouseMove/OnSetCursorMouseNone, Canvas.cpp:1027/2201): set
  cursor (I-beam over text, hand over button/choice) and optionally draw a field
  highlight; reuse the existing annotationUnderCursor hover detection.
• Keyboard / focus: while a text field is being edited, the floated child
  edit owns the keystrokes (it's a real HWND), so we get caret/selection/IME for
  free and don't need a new canvas keyboard handler. Tab/Esc/Enter are caught
  in the overlay's PreTranslateMessage (like the find bar) to commit / move /
  cancel.

4c. Direct-manipulation UI (the overlays) Copy Section

• Text field: float a WC_EDITW (or the wingui Edit) child of
  hwndCanvas, positioned with CvtToScreen(pageNo, fieldBounds), seeded with
  pdf_annot_field_value, ES_MULTILINE when PDF_TX_FIELD_IS_MULTILINE,
  ES_PASSWORD for password fields, font size ≈ field DA size × zoom. On commit
  (Enter for single-line, focus-loss, Tab) write back via
  EngineMupdfSetWidgetText; destroy the overlay; re-render. Reuses Win32 text
  editing — no custom caret/text layer (matches the analysis recommendation
  and the floated-edit pattern at HomePage.cpp:962).
• Checkbox / radio: no text entry — toggle on click and re-render. A radio
  click selects its group's option (mupdf handles the group via the field).
• Combobox / listbox: float a small dropdown (reuse the wingui ListBox /
  DropDown from CommandPalette/wingui) over the field, fill from
  pdf_choice_widget_options, commit the picked value with
  pdf_set_choice_field_value. Editable comboboxes (PDF_CH_FIELD_IS_EDIT) also
  allow typing (Phase 2/3).
• Navigation: Tab / Shift+Tab → commit current and move to next/prev field;
  Enter → commit (and, for single-line, advance); Esc → cancel without writing.
  Field order: build an ordered list of editable widgets per page (by the field
  tab order if present, else top-to-bottom/left-to-right) for Tab traversal.
• Highlight: tint editable fields lightly on hover / when the "fill mode" is
  active so the user can see what's fillable (like browsers' form highlight).

5. Threading & re-render rules (the sharp edges — same ones the find work hit) Copy Chapter

• All pdf_* field mutation runs on the UI thread holding docLock.
• Call pdf_update_annot (or pdf_update_page) inside the mutation so the
  appearance stream regenerates; otherwise the cached display list re-renders the
  old appearance.
• Call MarkNotificationAsModified outside docLock — it takes pagesLock
  then docLock/renderLock; calling it while holding docLock deadlocks
  (documented at Annotation.cpp:206). It drops the cached display list under
  renderLock.
• Then MainWindowRerender(win) (cancels the background renderer, repaints).
• The background render thread must not run a page while we mutate it — the
  display-list drop + CancelRendering in MainWindowRerender handle this, the
  same way annotation edits already work.

6. Phased plan Copy Chapter

• Phase 0 — spike / de-risk (½–1 day). Confirm f1040.pdf is a fillable
  AcroForm (not XFA-only) in our mupdf build. On left-click of a checkbox
  widget: classify via pdf_widget_type, toggle (pdf_toggle_widget), re-render
  via MarkNotificationAsModified + MainWindowRerender. This proves the whole
  mutate → appearance → invalidate loop end-to-end with the least UI.
• Phase 1 — text fields. Floated WC_EDITW overlay, single-line, commit via
  pdf_set_text_field_value, re-render, save round-trips (fill → Ctrl+Shift+S →
  reopen shows the value). Get focus/commit/cancel solid.
• Phase 2 — buttons + choice. Radio groups, comboboxes & listboxes via the
  dropdown overlay and pdf_choice_widget_*.
• Phase 3 — polish / navigation. Tab/Shift+Tab/Enter/Esc traversal, hover
  cursors + field highlight, multiline & password & comb fields (live filter via
  pdf_edit_text_field_value), read-only/required affordances, match the edit
  font size to the field.
• Phase 4 — robustness. JS calculate/format fields
  (pdf_update_open_pages), unsaved-changes prompt on close (reuse the
  annotation dirty flag + tab "unsaved" marker), "fill mode" toggle / command,
  reset-form, RTL, high-DPI/zoom/rotation correctness.

7. Test plan — `f1040.pdf` Copy Chapter

Local copy: C:\Users\kjk\OneDrive\!sumatra\sumtest\annots\f1040.pdf. Bring up
on a simpler fillable form first (fewer fields, no JS) before the 1040.

On the 1040 verify, per phase:

• Checkboxes: filing-status boxes (Single / Married filing jointly / …),
  "You as a dependent", digital-assets Yes/No — toggle, re-render, persist.
• Radio groups: any mutually-exclusive group selects one and clears siblings.
• Text fields: first/last name, home address — type, multiline where present.
• Comb fields: SSN / EIN (fixed-cell comb) — characters land in cells,
  max-length enforced.
• Numeric fields: the dollar-amount lines — number format; if the form has
  calculated totals, confirm pdf_update_open_pages recomputes them (or
  document the limitation if JS calc isn't run).
• Save round-trip: fill several fields, Ctrl+Shift+S, reopen → values
  present; re-open in Adobe/Chrome → values present and valid.
• Zoom/rotate: overlays line up with fields at 50% / 200% and rotated.

8. Key decisions / open questions Copy Chapter

• Win32 WC_EDITW vs wingui Edit vs custom caret → start with a floated
  Win32/wingui edit (free caret/IME/selection); custom on-page caret only if the
  font-mismatch-while-editing looks bad. Decided: floated edit.
• Live validation vs commit-only → Phase 1 commit-only
  (pdf_set_text_field_value returns accept/reject); add live
  pdf_edit_text_field_value filtering for comb/maxlen in Phase 3.
• JS / calculate → v1 runs whatever the pdf_set_*/pdf_update_page path
  runs (mupdf executes form JS if built with it); don't promise full JS. Note
  whether our mupdf build enables JS.
• XFA → detect XFA-only forms and fall back to read-only (mupdf fills the
  AcroForm layer, not dynamic XFA).
• Confirm pdf_toggle_widget exists in our mupdf headers (gl-form.c uses it;
  one analysis pass didn't find it in an older header) — checked in Phase 0.
• Interaction with the new find UI / annotation edit panel → forms are a
  third input mode; make sure the floated field-edit, the find bar, and the
  annotation drag don't fight over focus/clicks.

9. Files to touch Copy Chapter

• src/EngineMupdf.cpp — widget classify + mutate helpers (new), reuse
  MarkNotificationAsModified (4721), GetAnnotationAtPos (4660), render path.
• src/Annotation.cpp/.h — WidgetInfo + setters mirroring SetContents (351).
• src/Canvas.cpp — click-a-field branch in OnMouseLeftButtonDown (1281) /
  OnMouseLeftButtonUp (1453); hover cursor (1027/2201).
• New src/FormFields.cpp/.h (or fold into Canvas) — the editing-state machine +
  the floated edit / dropdown overlays + Tab navigation.
• src/DisplayModel.cpp — CvtToScreen/CvtFromScreen (already there).
• src/SumatraPDF.cpp — MainWindowRerender (2917), a "Fill form" command /
  mode if desired, unsaved-changes prompt.
• Save path: EngineMupdfSaveUpdated / CmdSaveAnnotations (reused as-is).

Plus Merge (`docs/plus-merge.md`) Copy Section

Merging from sumatrapdf-plus fork

Tracking selective merges from https://github.com/dengxibo/sumatrapdf-plus (a
Chinese-community fork "Sumatra PDF Plus", GPLv3, same license as upstream).

Fork layout / state Copy Chapter

• Remote is added locally as plus (git remote add plus https://github.com/dengxibo/sumatrapdf-plus.git).
• All work is on plus/main. Branches plus/sumatrapdf-plus, plus/feature/read-aloud-tts,
  plus/feature/smart-dark-preview are stale ancestors of main — ignore them.
• Fork point: 2854c78d6 ("re-register OpenWithProgids at startup", 2026-05-21).
• Fork scope (as of last review): 89 commits, 193 files, +61,677 / −20,075 lines
  (a chunk of that is machine-generated translations and a whitespace-only
  ext/mupdf/source/fitz/font.c reformat).
• Our master has ~1,600 commits since the fork point, so a plain git merge is
  not viable. We port selectively (see "Merge process" below).
• They do use our code-gen system (cmd/gen-settings.ts, gen-commands) — good; but
  their base predates recent gen-code.ts changes, so regenerate, never take their
  generated Settings.h/cpp, Commands.h/cpp diffs verbatim.

Last reviewed commit on plus/main: c8387b1bb ("Bump to 3.7.18…", 2026-07-26).
Update this marker after every review pass.

Review pass 2026-07-26 (`37bba7a39` → `c8387b1bb`, 90 commits) Copy Section

Already in master:

• Find bar / find window polish (shared June history + master's find work)
• Smart dark mode, CAD enhance (base), selection toolbar (base), TTS on master
• daf4d5575 illustrated PDF / CAD false positive → master 9a565f51a (#5806)

Ported this pass (small, separate commits):

• 3229c8b2c selection toolbar jitter (hide while selecting, throttle)
• 89e4edfed Text annot button on selection toolbar
• df1b2aab8 annotation Contents flush on switch/save/close (PDF path only)

Deferred / product decisions:

• G. EPUB progressive loading (full subsystem, not just post-review fixes)
• B WordLookup (+ 35fb36269 ZH→Hans only with B)
• Ebook annotations (EbookAnnotations*)
• Progressive search/ebook sync beyond master's stream-find

Skip:

• Version bumps, update-check.txt, branding (L)
• 27de3e915 continuous theme selection — mostly debug logf
• Pinned Home tab (Plus 3.7.11: always-present pinned Home tab when tabs on;
  Ctrl+W on Home-only closes the window) — not wanted
• Markdown + Mermaid (1c0601847): master already opens .md via MuPDF/cmark-gfm;
  Plus swaps in md4c + offline Mermaid via WebView2 — skip (not wanted)

Summary of fork changes, by feature Copy Chapter

A. Read Aloud (TTS) — largest feature Copy Section

Windows SAPI text-to-speech with word-by-word highlighting synced to speech; works on
PDF/EPUB/MOBI. Start from top of page / cursor / selection; pause/continue; speed
presets 0.25×–2.0×; separate Chinese/English rates; "smart bilingual" voice switching
(auto-picks a Chinese voice for CJK runs and an English voice otherwise), both local
SAPI and online voices; toolbar button with dropdown, menu, context menu; double-click
on blank area toggles read-aloud. Recommends NaturalVoiceSAPIAdapter for natural voices.

• New files: src/TextToSpeech.{cpp,h}, src/ReadAloudHighlight.{cpp,h},
  sumatra-website/www/docs/Read-Aloud.md, tools/gen_read_aloud_trans.py
• Integration spread through SumatraPDF.cpp, Toolbar.cpp, Menu.cpp, Canvas.cpp,
  DisplayModel.cpp, TextSelection.cpp
• Settings: ReadAloudVoiceId, ReadAloudSpeakingRate (legacy),
  ReadAloudSpeakingRateZh/En, ReadAloudSmartVoiceZh/En, ReadAloudSmartOnlineVoiceZh/En
• Commands: CmdReadAloud, CmdReadAloudFromCursor, CmdReadAloudFromTopPage,
  CmdReadAloudSelection, CmdPauseReadAloud, CmdContinueReadAloud, CmdStopReadAloud
• Key commits: 95812be62, 95d695b1d, 4aa346bf5, 48753162f, b4d2fdd06,
  4a6a9ece3, 5a6c285e4, 2d3684974, 270f677d3, 4e5363143 (partly)
• Note: we have our own ideas in docs/read-aloud-ux-ideas.md — compare before porting.

B. Offline dictionary / word lookup Copy Section

Double-click a word (or "Look Up Selection") to show a floating dictionary popup from
offline dictionaries (SumatraDict.* .idx/.dat files in {exedir}/dict or
OfflineDictionaryPath); phonetic transcription for multi-sense entries; optional
pronunciation audio; "Search with Youdao Dict" command.

• New files: src/WordLookup.{cpp,h} (~2,400 lines), src/LookupAudio.{cpp,h},
  src/FloatingPopupStyle.{cpp,h}, dict import scripts cmd/import-oaldpex-dict.ts,
  cmd/import-xdhy7-dict.ts, tools/gen_lookup_*_trans.py
• Settings: OfflineDictionaryPath, EnableDoubleClickWordLookup
• Commands: CmdLookupSelection, CmdToggleDoubleClickWordLookup,
  CmdSearchSelectionWithYoudaoDict
• Key commits: f1722fbb3, 399d52b45, 649b31371, 65b413ab1 (audio optional)
• Note: dictionary data is not in the repo (users supply it); import scripts convert
  OALD / xdhy7 sources.

C. Ask AI (Doubao / DeepSeek / ChatGPT) Copy Section

Select text → "Ask AI" opens the provider's web chat in the default browser and pastes
the selection (clipboard + simulated paste; several commits fight with cold-start/paste
targeting per provider). Provider picker; can be fully hidden.

• Settings: AiChatProvider (doubao/deepseek/chatgpt), EnableAskAI,
  AiChatUseDeepSeekInsteadOfDoubao (deprecated migration shim)
• Commands: CmdAnalyzeSelectionWithDoubao
• Key commits: df38d716d, 440ed7c7c, c578c0cf4, ead418671, 39df9ba19, 4c805377d
• Assessment: China-centric providers, brittle browser-paste automation.

D. Smart PDF dark mode Copy Section

A real dark-mode rendering pipeline for PDFs (not just invert): intercepts drawing via
a custom fitz device, recolors text/vector content using OKLab color math, classifies
images (photos vs. line-art/scans) to preserve photos and page-1 covers while darkening
scanned/line art; per-document color mode Auto / Black (full dark) / Light (original)
with toolbar buttons; render + engine caches; unit tests included. "Legacy" inversion
kept as default renderer initially.

• New files (~3,500 lines): src/PdfDarkMode.h, PdfDarkModeAnalysis.cpp,
  PdfDarkModeCache.cpp, PdfDarkModeColor.cpp, PdfDarkModeDevice.cpp,
  PdfDarkModeEngineCache.cpp, PdfDarkModeImageBgBlend.cpp,
  PdfDarkModeImageClassifier.cpp, PdfDarkModeImageRules.cpp,
  PdfDarkModeImageStats.cpp, PdfDarkModeInternal.h, PdfDarkModeNoOp.cpp,
  PdfDarkModeOklab.cpp, PdfDarkModeProfile.cpp, PdfDarkModeScanProcess.cpp,
  unit tests src/utils/tests/PdfDarkMode{ImageClassifier,Oklab}_ut.cpp
• Touches: EngineMupdf.cpp (+2,800 lines), RenderCache.cpp, libsumatrapdf.def
  (new exported MuPDF symbols), PdfFilter/PdfPreview stubs (PdfDarkModeNoOp.cpp,
  EngineNotifyNoOp.cpp) to fix DLL link
• Settings: PdfDocumentColorMode (auto/black/light, persisted per session 3.7.x)
• Commands: CmdSetPdfDocumentColorMode{Auto,Black,Light}, CmdTogglePreservePdfImages
• Key commits: 67fe3f0e3, e8c329473, b68a0723e, c225f86f4, 65cd4d5de,
  171cb47a2, 50a66cebb, e4e78bcb8 (light-mode perf)

E. CAD / engineering-drawing PDF enhancement Copy Section

Auto-detects CAD-style PDFs (hairline-heavy vector drawings, incl. WPS hairline and
screenshot PDFs) and thickens hairlines when rendering, with a toggle command.

• New files: src/PdfCadDetect.{cpp,h}, src/PdfCadEnhanceDevice.{cpp,h},
  src/PdfCadEnhanceNoOp.cpp
• Command: CmdToggleEngineeringDrawingEnhance
• Key commits: 735894b11, b058ba496, 38006d0e8

F. Themes & window chrome Copy Section

New named themes: Light-Warm (eye-care), Light-White, Dark-Dracula,
Dark-Black (plus System). One-click light/dark toggle remembering
LastDarkTheme/LastLightTheme. Dark-mode fixes throughout the chrome: canvas + TOC
scrollbar theming, menu check marks, maximized frame edges, toolbar separators,
tab UI. Windows 11-style caption glyphs drawn from generated geometry
(src/CaptionGlyphs.{cpp,h}, src/tools/gen_caption_glyphs.py) with DPI-aware layout and
interaction-state polish.

• Touches: Theme.cpp (+400), Caption.cpp, Toolbar.cpp, TableOfContents.cpp,
  Menu.cpp, TabsCtrl.cpp, SvgIcons.cpp
• Settings: LastDarkTheme, LastLightTheme; command CmdToggleLightDarkTheme
• Key commits: 36468333a, e8c329473, 81defc78b, 171cb47a2, 597f0c47d,
  1cd0c85d6→b0002c393 (caption series), c4018ec06, 0e493c658, 2183086c1,
  5491f5520
• Caution: our Theme.cpp/dark-mode code has evolved a lot since their base; expect
  heavy conflicts. Port ideas, not diffs.

G. Ebook (EPUB/MOBI/AZW3) engine work Copy Section

Real changes inside vendored ext/mupdf/source/html/* (~1,000–1,700 changed lines per file)
even ignoring whitespace) plus Sumatra-side ebook code: faster loading of large ebooks,
NCX table of contents for MOBI/AZW3 and EPUB, progressive TOC loading (with graying-out
of not-yet-reachable in-book links), better Chinese mixed text/image layout, fixes for
garbled MOBI TOC from corrupt NCX/CNCX labels, blank MOBI picture-book pages
(self-closing `` + missing image records), Bookworm EPUB comic layout, EPUB/MOBI
dark-theme switching artifacts.

• Touches: ext/mupdf/source/html/{html-layout,html-parse,css-apply,epub-doc,html-font}.c,
  src/MobiDoc.cpp (+1,188), src/EngineEbook.cpp (+1,370), src/HtmlFormatter.cpp,
  src/EbookFormatter.cpp, new src/EbookTypography.h, src/mupdf/mupdf_load_system_font.c,
  src/libsumatrapdf.def
• Settings: per-doc LayoutDx/LayoutDy (flowed ebook page size)
• Key commits: 937dc3454, 069eb2f23, 243092d1b, 7091e1684, 52239c27a
  (garbled TOC), 0a97bc1a0, 65b413ab1, c111312bc, d8ac31deb
• Caution: this is the riskiest area to port — vendored mupdf may have moved upstream;
  diff their mupdf changes against our current mupdf, not the fork base.
• Note: ext/mupdf/source/fitz/font.c diff is whitespace/line-endings only — ignore it.

H. Selection toolbar Copy Section

Floating mini-toolbar after selecting text in a PDF: highlight, underline, strikeout,
Ask AI. Also fixed annotation menu visibility on non-PDF files.

• New files: src/SelectionToolbar.{cpp,h}; setting SelectionToolbar (bool)
• Key commits: db0b32b7a, f1722fbb3

I. Home page: list view + tips Copy Section

HomePageViewMode setting: thumbnails (current grid) or list (filename + path).
ShowTips toggle. Thumbnail bookkeeping fields (ThumbnailDarkTheme,
ThumbnailBlankKnown, ThumbnailIsBlank — runtime-only) for dark-theme-aware
thumbnails and hiding blank ones. HomePage.cpp +756 lines.

• Key commit: 0435f1ae6 (part of the 3.7.4 release commit), e4e78bcb8

J. GitHub-based auto-update Copy Section

Rewired update checks to their repo (raw.githubusercontent.com/dengxibo/... with
jsDelivr fallback), update-check.txt in repo root, GitHub Releases downloads, download
speed/size progress UI, portable self-update that can replace the running exe,
update check on first launch, fix for manual check hanging.

• Touches: src/UpdateCheck.cpp (+160/−66), update-check.txt
• Key commits: 4e5363143, 56aefc51a, 17612a1e0, 60a8b3462, 077e00776,
  bc79cf9e6, 9938530ae
• Assessment: URLs are theirs — do not merge as-is. Possibly worth porting:
  download progress UI, portable self-replace fix, hang fix — as ideas.

K. Standalone bug fixes — verified against master 2026-07-10 (`04726daed`) Copy Section

Each fork fix was compared against current master to see if the bug still exists here.

Still applicable (bug present in master):

• 5491f5520 — TOC scrollbar mouse capture stuck during tree reload. Master's
  TreeView::Clear() / SetTreeModel() call TreeView_DeleteAllItems with no
  capture guard; TOC filter/reload paths (ClearTocBox, LoadTocTree,
  ApplyTocFilter) hit exactly that. Port ONLY the src/wingui/TreeView.cpp hunk
  (CancelInProgressInteraction helper sending WM_CANCELMODE + 2 call sites);
  the TableOfContents.cpp hunk targets fork-only ReCreateTocTreeView. Small, clean.
• 231e4124e — bin2coff.c buffer overflow (strcpy → bounded memcpy). Our
  src/tools/bin2coff.c still has the unbounded strcpys; bin2coff.exe still embeds
  fonts in the mupdf build. Low severity (inputs are build-controlled labels), fix is
  harmless. Their tests/test_invariant_bin2coff.c doesn't fit our test conventions —
  skip or adapt.
• 8cc39e227 (EngineMupdf.cpp part only) — junk PDF page labels from scanned/OCR
  ebooks (.pdg filenames / per-page prefix-only labels shown instead of page
  numbers). Master's BuildPageLabelVec (src/EngineMupdf.cpp:1846) and
  GetPageLabeTemp (:4678) have none of the three guards. Won't apply cleanly —
  master refactored page labels to Str (PageLabelInfo::type is Str, prefix is
  pdf_obj*); port by hand: prefix-only check after the trivial-default early return,
  .pdg check before final return labels;, per-label fallback in GetPageLabeTemp.

Partially applicable (core fixed here; small residual pieces):

• ac8a2f73b — crash closing tabs during background rendering. Core fz_context
  teardown race is ALREADY FIXED in master: RenderCache::CancelRendering
  (src/RenderCache.cpp:770) already waits for in-flight renders (fork re-implemented
  an equivalent wait), plus master has pauseRendering defenses the fork base lacked.
  Genuinely missing, port by hand if wanted: (a) IsValidZoom early-return guard in
  DisplayModel::SetViewPortSize; (b) in ReplaceDocumentInCurrentTab relayout the
  new doc before delete prevCtrl (master deletes at SumatraPDF.cpp:1738 before
  relayout at :1760).
• edebf7dbe — crash opening file with tabs disabled. Structurally prevented in
  master: our async load creates the tab after load in LoadDocumentFinish
  (fork used a shell-tab-first model needing all those guards; those functions don't
  exist here). Optional hardening only: guard win->CurrentTab() in
  UpdateUiForCurrentTab (SumatraPDF.cpp:1581); make ReportIf(!tab) in
  ReplaceDocumentInCurrentTab (:1614) an early return; null-guard
  SetFrameTitleForTab.
• 1369facda + 21ef059f7 — multi-monitor per-monitor-DPI UI fonts. Master
  already handles DPI detection + geometry (src/base/Dpi_win.cpp prefers
  GetDpiForWindow/GetDpiForMonitor; OnDpiChanged at SumatraPDF.cpp:5160
  rebuilds menu/toolbar/find bar) — the fork's Dpi.cpp rewrite is superseded. But the
  font half is a real master bug: GetAppMenuFontSize() (AppSettings.cpp:792)
  sizes fonts from system DPI via SystemParametersInfoW; font cache
  (src/base/Win.cpp:1871) has no DPI in its key; ResetCachedFonts() never runs on
  DPI change; toolbar text (Toolbar.cpp:1459) and tabs (Tabs.cpp:62) keep
  primary-monitor font size on other monitors. Porting = re-implementation, not
  cherry-pick (~120 lines of per-DPI font helpers in Win.cpp/WinDynCalls
  incl. SystemParametersInfoForDpi, DPI-keyed font cache, then rewire
  AppSettings.cpp font getters + OnDpiChanged). Medium effort/risk.

Not applicable:

• c7a20f168 — compiler warnings: both are in fork-only code (PreparePageNavigation,
  their ebook changes). N/A.
• 2183086c1 — dark-mode TOC scrollbar staying white: master's recursive
  EnumChildWindows dark-mode pass (DarkMode::setChildCtrlsSubclassAndTheme,
  SumatraPDF.cpp:2198/2345) already themes the nested trees; symptom can't occur here.
• 069eb2f23 — "TOC loading optimization": actually a mix of fork branding
  (HomePage links) and MobiDoc work — reclassified into group G (ebooks), not a
  standalone fix. Also accidentally commits a stray debug-76c24b.log.

L. Branding / fork-only — do not merge Copy Section

README rewrites (bilingual), readme.txt Chinese user guide, docs/github-publish-zh.md,
app renamed "Sumatra PDF Plus", their 3.7.x version numbering and release commits,
update-check.txt, fonts/README.txt, machine-generated translation blobs in
translations/*.txt (+11k lines, generated by their tools/gen_*_trans.py scripts —
if we port a feature, run our own translation flow instead), vs2022/* project file
additions (we generate via premake).

Merge process (for every future sync) Copy Chapter

1. Fetch: git fetch plus --no-tags
2. What's new: git log --date=short --format='%h %ad %s' <last-reviewed>..plus/main
   where <last-reviewed> is the marker near the top of this file.
3. Categorize new commits into the feature groups above (add new groups if needed)
   and update the group descriptions. Useful commands:
   • Full feature diff: git diff <fork-point>..plus/main -- <files> (fork point
     2854c78d6 — stable, never changes)
   • Real-change check on vendored code: add --ignore-all-space
   • One file's history: git log --oneline plus/main -- <file>
4. Present to Krzysztof for review; record his decision per feature/commit in the
   Decision log below. Nothing is merged without an explicit decision.
5. Port approved items:
   • Prefer git cherry-pick -x <sha> when it applies cleanly (-x records origin).
   • Otherwise port manually from the feature diff. Attribute in the commit message:
     Ported from dengxibo/sumatrapdf-plus <sha(s)>.
   • Settings/commands: re-add through cmd/gen-settings.ts / cmd/gen-commands.ts
     and run bun cmd/gen-code.ts — never take their generated files.
   • clang-format only our src/ files; keep ext/ edits minimal-style.
   • Skip their translations blobs; add new strings through our translation flow.
   • Build (bun cmd/build.ts -dbg) and run unit tests (bun cmd/run-unit-tests.ts -dbg).
6. Update this file: bump the "Last reviewed" marker, log decisions and merge
   commits in the Decision log.

Gotchas Copy Section

• The fork's base (2854c78d6, 2026-05-21) is ~1,600 commits behind master. Never
  git merge plus/main. Cherry-picks will often conflict in SumatraPDF.cpp,
  Toolbar.cpp, Menu.cpp, Theme.cpp — porting by feature diff is usually easier
  than commit-by-commit for the big features.
• Features are interleaved in shared files and in their "Release 3.7.x" commits; a
  single fork commit often touches several features.
• Any fix in group K may already exist in master in a different form — verify before
  porting.
• Their libsumatrapdf.def / premake file lists differ; regenerate ours rather than merging.

Decision log Copy Chapter

Read Aloud Ux Ideas (`docs/read-aloud-ux-ideas.md`) Copy Section

Read Aloud UX ideas for SumatraPDF

UX-focused analysis of the Read Aloud feature (pre-release 3.7+) and proposals for improving discoverability, controls, and listening workflows. No implementation details.

Last updated after playback bar, Stop Reading, auto-scroll, toolbar pause icon, and tab-switch behavior review (master, June 2026).

Current experience (as implemented today) Copy Chapter

Entry points Copy Section

All three menus share one builder (BuildReadAloudMenuItems): when speaking → Pause Reading + Stop Reading; when paused → Continue Reading + Stop Reading; then explicit start commands and Voice → (System default + installed voices).

Playback bar (shipped) Copy Section

While a read-aloud session is active (speaking or paused):

[Pause] [Stop]   Reading · Annual Report.pdf · page 12 of 240 · Smart start

• Pause / Resume — left-side buttons; label switches to Resume when paused.
• Stop — ends the session and clears resume state (distinct from pause).
• Status line — document name, page X of Y (from highlight map + spoken offset), and scope label: Smart start, From top, From cursor, or Selection.
• Placement — bottom of canvas, full width minus margin; relayouts on resize.
• Visibility — shown on the window that owns the session; hidden on other SumatraPDF windows while audio may still play there.

The bar is the primary session control surface. Menus and palette duplicate transport actions for keyboard-first users.

Tab and window lifecycle (as implemented) Copy Section

Switching away from a tab stops speech and clears the read-aloud session on the tab being left (LoadModelIntoTab → CloseDocumentInCurrentTab → ResetReadAloudStateForTab): TTS stops, resume text is freed, highlight and playback bar are torn down. There is no cross-tab “still reading in the background” state within one window.

Implication: toolbar and menus always target the current tab, which is also the only tab that can have an active or paused session. Cross-tab orphan sessions and “bar shows tab A while canvas shows tab B” do not occur.

What works well Copy Section

• Multiple explicit start scopes — selection, first visible text in viewport (“From Top”), cursor position (context menu), plus smart default on toolbar / CmdToggleReadAloud (selection if present, else viewport).
• Continuous listening — viewport / cursor / smart builds read from the start point through the end of the document; selection reads selection only. 1 KB TTS chunks chain automatically.
• Word follow-along — current spoken word highlighted on the canvas (selection color; timer-driven repaint).
• Auto-scroll — viewport follows the spoken word while reading; stops permanently if the user scrolls the highlight fully off-screen (respects manual navigation).
• Resume — pause remembers position; Continue Reading picks up in the same tab (until you switch tabs).
• Predictable tab policy — switching tabs ends listening and clears state; no hidden audio from another tab in the same window.
• Stop — explicit end-of-session in playback bar, all three menus, and command palette (CmdStopReadAloud).
• Session chrome — playback bar answers “what is playing, from where, how far” at a glance.
• Discoverability — menubar, context menu, toolbar dropdown, palette, and playback bar.
• Consistent naming — Pause Reading, Continue Reading, Stop Reading, Start Reading From Top (renamed from “From Here”).
• Localized menu strings — Tr / TrN on menu labels.
• Voice remembered — ReadAloudVoiceId advanced setting persists Voice submenu choice.
• Sensible text cleanup — soft hyphens and line breaks normalized before speech.
• Backend choice — WinRT Speech Synthesis with SAPI fallback.
• User docs updated — Accessibility-and-Text-to-Speech.md describes continuous reading, playback bar, menus, and scopes.

Remaining pain points Copy Section

What changed since the first UX pass Copy Chapter

Design principle (unchanged) Copy Chapter

Treat Read Aloud as listening mode layered on normal reading — not a hidden palette command. Users should see: what is reading, how to control it, and how far through the content they are.

The playback bar delivers this with minimal chrome. Next polish should reduce toolbar ambiguity and improve first-run clarity, not add modals or permanent toolbar widgets.

Recommended improvements (by priority) Copy Chapter

1. Toolbar transport clarity (highest impact remaining) Copy Section

Playback bar and tab policy are solid; the toolbar main button is the main leftover friction.

2. Multi-window polish (low priority) Copy Section

Tab switch within a window is already handled. Remaining edge case: two SumatraPDF windows, one reading:

Optional: toast when tab switch ends a paused session (“Reading stopped”) so users know Continue is no longer available.

3. Playback bar polish (incremental) Copy Section

4. Clarify start commands for first-time users Copy Section

Tooltip on toolbar dropdown items (one line each) would help more than renaming again. Consider a short in-app tip the first time Read Aloud runs.

5. Context menu: Read Aloud near Copy (optional) Copy Section

When text is selected:

• Inline Start Reading Selection under Copy (disabled when no selection).
• Keep full Read Aloud (TTS) submenu for voice, viewport start, cursor, transport.

Mirrors how Translate sits in the selection flow.

6. Settings and highlight control Copy Section

In Advanced Options (or playback-bar ⚙):

7. Clearer empty and blocked states Copy Section

Keep toasts short; one primary action each.

8. Command palette context Copy Section

Hiding Stop when idle reduces palette noise.

9. Default keyboard shortcut Copy Section

Bind a discoverable shortcut (e.g. Ctrl+Shift+S toggle pause/resume, or Ctrl+Shift+R start) in default accelerators; document in Keyboard shortcuts. Custom rebinding already supported.

10. Selection scope expectations Copy Section

Start Reading Selection does not continue past the selection (by design). Users may expect “read my highlight then keep going.” Options:

• Rename to Read Selection Only / add subtitle in menu.
• Or add Read Selection, Then Document as an advanced scope (larger lift).

Call out the difference in help and first-run tip.

What to defer Copy Chapter

• Full audiobook features (bookmarks, sleep timer, MP3 export)
• Neural / cloud voices (stay on Windows installed voices)
• Per-paragraph voice or SSML editor
• Replacing Narrator / NVDA for blind users (document limitations in help)
• Floating / undocked playback widget

Suggested user story (one sentence) Copy Chapter

“Open a document, start Read Aloud from the toolbar or right-click menu, choose where to begin (viewport, selection, or cursor), pick a voice under Voice, and listen through the document with the current word highlighted and the page scrolling along — use the playback bar or menu to pause, resume, or stop, and see which page you’re on.”

Quick wins vs larger lifts (revised) Copy Chapter

The largest remaining gap is toolbar triple-duty (start / pause / continue on one button) and discoverability of start scopes for first-time users — not cross-tab state, which is already coherent.

Related implementation map (for developers) Copy Chapter

• Commands: CmdToggleReadAloud, CmdPauseReadAloud, CmdContinueReadAloud, CmdStopReadAloud, CmdReadAloudFromTopPage, CmdReadAloudSelection — palette; no default shortcut
• TTS menu ids: CmdTtsMenuReadCurrentPage, CmdTtsMenuContinueReading, CmdTtsMenuReadSelection, CmdTtsMenuPauseReading, CmdTtsMenuReadFromCursor, CmdTtsMenuStopReading, CmdTtsVoice*
• Menus: BuildReadAloudMenuItems / RebuildReadAloudMenu in SumatraPDF.cpp; menubar + context in Menu.cpp
• Toolbar: speak + dropdown (ShowTtsVoiceMenu); dynamic tooltip/icon in Toolbar.cpp
• Playback bar: ReadAloudPlaybackBar.cpp — ReadAloudPlaybackBarUpdateSession, ReadAloudPlaybackPauseOrResume, ReadAloudPlaybackStop
• Scope: WindowTab::readAloudScope — Smart, Viewport, Selection, Cursor; set in ReadAloudInTab, ReadAloudFromViewportTopInTab, etc.
• Sessions: gReadAloudSessionTab (persists through pause), gReadAloudSourceTab (active TTS)
• Progress: ReadAloudGetProgressPage in ReadAloudHighlight.cpp
• Auto-scroll: ReadAloudUpdateAutoScroll, ReadAloudOnUserViewChanged — disables on user scroll-away
• Document text: ReadAloudHighlightBuildFromDocument, ReadAloudGetViewportStart, ReadAloudGetCursorStart
• Chunking: kReadAloudMaxChunkLen = 1024, ReadAloudSpeakChunk, WM_TTS_EVENT chaining
• Highlight: PaintReadAloudHighlight, highlight timer in ReadAloudHighlight.cpp
• Resume: readAloudText, readAloudResumePos, chunk fields on WindowTab
• Tab switch: LoadModelIntoTab → CloseDocumentInCurrentTab → ResetReadAloudStateForTab (stops TTS, clears session)
• Copy permission: silent return in read-aloud entry paths when Perm::CopySelection denied
• TTS: TextToSpeech.cpp — WinRT + SAPI; ReadAloudVoiceId in settings
• User docs: sumatra-website/www/docs/Accessibility-and-Text-to-Speech.md, sumatra-website/www/docs/Commands.md, version-history 3.7 entry

Temp Investigate Scroll 6154 (`docs/temp-investigate-scroll-6154.md`) Copy Section

Investigate sticky scroll at 180%+ zoom (#6154)

Temp notes for an agent on another machine. Delete when done.

Issue: https://github.com/sumatrapdfreader/sumatrapdf/issues/6154
The useful comment: https://github.com/sumatrapdfreader/sumatrapdf/issues/6154#issuecomment-5591969544

Goal Copy Chapter

Reproduce (or rule out) sticky / not-smooth vertical scrolling at ~180% zoom and above. Reporter says it happens with two-finger touchpad and with the vertical scrollbar, on a light PDF.

Do not "fix" until you have seen it, or have a measurement that shows zoom-dependent hitch that a human would call sticky.

Reporter setup (from the comment + settings file) Copy Chapter

• Pre-release SumatraPDF, Windows 11 Pro, Best Performance
• 3K OLED, Scaling 250%, maximized window 0 0 2880 1800 (WindowState = 3)
• Scroll: Precision touchpad two-finger, later also native vertical scrollbar
• Sample: lorem.pdf (3 pages, ~403 KB)
• Settings: SumatraPDF-settings.txt

Keep copies (already downloaded here):

• C:\Users\kjk\OneDrive\!sumatra\bugs\bug-6154-lorem.pdf
• C:\Users\kjk\OneDrive\!sumatra\bugs\bug-6154-SumatraPDF-settings.txt

If those paths are missing, download the two GitHub attachments again.

Relevant settings (not the whole file):

DefaultDisplayMode = automatic
DefaultZoom = fit content
SmoothScroll = true
ScrollLineAmount = 16
Scrollbars = hidden
MouseWheelTurnsPage = false
ZoomIncrement = 0.01
CustomScreenDPI = 0
WindowPos = 0 0 2880 1800
WindowState = 3

FixedPageUI.UseOverlayScrollbar = true is leftover; live scrollbar mode is Scrollbars = hidden. File history for lorem.pdf had Zoom = 250.917 (matches the tiny ZoomIncrement).

What the first machine could not do Copy Chapter

Ran on a 96 DPI ~1920×1200 box, no interactive desktop, no real touchpad. Injected SendInput is dropped; posted WM_MOUSEWHEEL / WM_VSCROLL work. You cannot feel stickiness there.

If your machine has 250% scaling, a touchpad, and a real desktop, manual repro first. That is the missing piece.

Manual repro (do this first on a 250% / 3K box) Copy Chapter

1. Build: bun cmd/build.ts -dbg → out/dbg64/SumatraPDF.exe
2. Copy reporter settings into a throwaway dir, then:

out\dbg64\SumatraPDF.exe -for-testing -appdata <throwaway> -log -log-to-file <log> -zoom 180 <lorem.pdf>

Maximize. Two-finger scroll. Repeat at 100%, 180%, 250%. Then set Scrollbars = windows and drag the thumb / click the track.

3. Also try SmoothScroll = false. If stickiness vanishes, it is the animation + tile paint, not input.

What "sticky" means here: hitch / catch-up while moving, not "smooth-scroll eases for ~500 ms" (that is kSmoothScrollRate = 15 in src/Canvas.cpp and happens at every zoom).

Log: Slow rendering: N ms fires only if a tile takes >300 ms (src/RenderCache.cpp). Absence of that line does not mean scrolling felt fine.

Why 180% on 250% DPI is special Copy Chapter

zoomReal = zoomVirtual * 0.01 * (screenDPI / 72).

RenderCache::GetTileRes (src/RenderCache.cpp) splits a page when it is larger than maxTileSize (initially SM_CXSCREEN × SM_CYSCREEN). res goes 0 → 1 → 2 as factorAvg grows. On the 96 DPI box, CustomScreenDPI = 240 + 180% was the first case with res=2.

Hypothesis: at 180% × 250% DPI on a 2880×1800 window, each new tile is ~screen-sized; scrolling into uncached tiles hitchs. Once cached, jumps are cheap. Matches "even light PDFs" and "scrollbar too" (both request new tiles).

CustomScreenDPI only fakes the zoom math, not Windows DPI, window pixel size, or touchpad. Prefer a real 250% display.

Measurements already taken (96 DPI machine, 2026-09-11) Copy Chapter

Posted input, full work area, lorem.pdf, continuous, WaitRenderIdle then scroll.

Wheel and scrollbar line/page did not get slower at 180%+ once tiles were ready. The 27 s first-idle at 180%/240 is suspicious but was also inflated by WaitRenderIdle (it InvalidateRect+UpdateWindow every poll — see below).

Earlier 2026-09-08 probe on the same box (tests/tmp/6154-probe.ts, 96 DPI, 100 vs 200%) also saw no zoom-dependent wheel hitch.

Code to read Copy Chapter

• Wheel / smooth scroll: src/Canvas.cpp CanvasOnMouseWheel, OnVScroll, StartOrUpdateSmoothScrollY (kSmoothScrollRate = 15)
• Tile split: src/RenderCache.cpp GetTileRes, slow log durMs > 300
• Idle snapshot (do not treat as "user scroll cost"): src/SumatraControl.cpp SnapshotRenderIdle — invalidates twice per poll
• DPI for zoom: src/SumatraPDF.cpp gSettings->customScreenDPI / DpiGetForHwnd
• Overlay vs hidden: ScrollbarsUseOverlay() / ScrollbarsAreHidden() in src/SumatraPDF.cpp

Instrumented re-run (if you cannot feel it) Copy Chapter

Do not register a suite test. Write tests/tmp/repro-6154.ts (gitignored) or run from a scratch file.

Launch with -for-testing -dbg-control -appdata <dir> -log -log-to-file <log>. Helpers: tests/win-automation.ts launchControlled, tests/control.ts waitForRenderIdle / TestDpi, tests/winapi.ts getScrollInfo / postMessage.

Window pos format is WIDTHxHEIGHT@XxY (e.g. 1872x1200@0x0), not x,y,dx,dy. Use the work area, not the default right-half test window — small viewport understates tile cost.

Compare:

1. Native DPI, zoom 100 / 180 / 250
2. If native DPI is 96, also CustomScreenDPI = 240 at those zooms (math-only stand-in)
3. Input: WM_MOUSEWHEEL delta 120 (mouse), delta 30 (precision pad), WM_VSCROLL SB_LINEDOWN / SB_PAGEDOWN
4. SmoothScroll true vs false
5. Scrollbars = hidden vs windows

Log from waitForRenderIdle: zoomV=… zoomR=… res=… vp=WxH ready=… tile=… cache=…. res jumping 0→2 at the reporter's 180% is the signal.

Time scroll start → first nPos change and time until WaitRenderIdle after a page-sized jump into uncached tiles. Do not wait-for-idle before the jump if you want to see hitch; that pre-warms the cache.

Pitfalls Copy Section

• WaitRenderIdle paints every poll. A long first-idle can be the probe starving render threads, not the user's hitch. Prefer log timestamps / Slow rendering / CPU, or sample GetScrollInfo during a burst of wheel messages without waiting idle first.
• Posted WM_VSCROLL SB_THUMBTRACK does nothing useful: OnVScroll reads si.nTrackPos from GetScrollInfo, which posting does not set. Use SB_PAGEDOWN or drive the overlay/native thumb with mouse messages if the desktop allows it.
• Hidden scrollbars: GetScrollInfo on the canvas can still move (nPos); overlay mode updates via OverlayScrollbarGetInfo.
• -for-testing skips session restore and does not save settings. Portable out/dbg64/SumatraPDF-settings.txt can still load. Use -appdata.
• Command ids: cmdId("Cmd…"), never hardcode.

What would count as a repro Copy Chapter

Any of:

• You feel hitch at ≥180% on 250% scaling, gone or much less at 100%, with touchpad or scrollbar
• Tile render of visible pages regularly >~50–100 ms at that zoom, and scroll motion stalls until the tile lands
• res / zoomR at 180%×250% DPI clearly larger than at 100%, and scrolling into a new tile row hitches

If it is smooth at 250% on a 250% 3K box with their settings, say so; then the report is machine-specific (GPU, touchpad driver, OLED) and not a general tile bug.

Do not Copy Chapter

• Run tests/run-almost-all.ts / run-all.ts
• Commit a fix or a suite test from this doc
• Treat 545 ms smooth-scroll settle as the bug

Todo Maybe (`docs/todo-maybe.md`) Copy Section

epub hyphenation

MuPDF can auto-hyphenate HTML-engine docs (EPUB/MOBI/FB2/HTML) when CSS is
hyphens: auto and the document has a language. Default CSS is
hyphens: manual; soft hyphens (U+00AD) already work without tables.

Sumatra builds MuPDF with FZ_ENABLE_HYPHEN=0 (cmd/deps-build-defs.ts,
vcxproj). Lookup then always returns null and MuPDF warns
no hyphenation table for lang='en' (etc.). That is logged; it is not shown
as "Errors in document" (issue #6109). PDFs are unaffected.

Do not enable FZ_ENABLE_HYPHEN just to silence the warning.

If we want EPUB auto-hyphenation as a feature:

• FZ_ENABLE_HYPHEN=1 and FZ_ENABLE_HYPHEN_ALL=0 (std set includes en)
• embed ext/mupdf/resources/hyphen/hyph-std.zip (~174 KB). hyph-all.zip
  is ~638 KB and is MuPDF's default if FZ_ENABLE_HYPHEN_ALL is left at 1
• Sumatra's build does not link those zips in today (fonts come from
  IDR_EMBEDDED_PAK, see src/mupdf/noto_sumatra.c); flipping the define
  without embedding is a linker error (_binary_hyph_std_zip)
• first use per language unpacks the zip and builds a trie (CPU + RAM)
• books with hyphens: auto would reflow differently (page breaks vs now)
• languages not in the zip still warn

Upside: better reflow in narrow/justified EPUB columns and long compounds
when the book asks for auto hyphenation.

Upgrade Chmdec (`docs/upgrade-chmdec.md`) Copy Section

Upgrading chmdec

How to update SumatraPDF's vendored plain-C CHM reader (ext/chmdec/chm.c +
ext/chmdec/chm.h) from the upstream dist.

Upstream source Copy Chapter

• Repo: https://github.com/kjk/chmdec (main branch)
• Files to copy: dist/chm.c and dist/chm.h only
• Replaces the older ext/libchm vendor (same API family; was
  https://github.com/kjk/libchm).

The amalgamated files are generated upstream by bun cmd/build-dist.ts. Never
edit ext/chmdec/chm.c or ext/chmdec/chm.h by hand in SumatraPDF.

Steps Copy Chapter

1. Fetch latest upstream dist Copy Section

Clone or refresh a shallow copy, then record the commit hash:

git clone --depth 1 https://github.com/kjk/chmdec.git /tmp/chmdec-update
git -C /tmp/chmdec-update rev-parse HEAD

If /tmp/chmdec-update already exists:

git -C /tmp/chmdec-update pull --ff-only

2. Copy dist files into ext/chmdec Copy Section

cp /tmp/chmdec-update/dist/chm.c ext/chmdec/chm.c
cp /tmp/chmdec-update/dist/chm.h ext/chmdec/chm.h

On Windows (PowerShell), use Copy-Item ... -Force — run the two copies as
separate commands (avoid ; chaining in the shell tool).

Optionally refresh the license if it changed:

cp /tmp/chmdec-update/LICENSE.md ext/chmdec/LICENSE.md

Do not clang-format files under ext/chmdec/ (vendored code).

3. Update ext/versions.txt Copy Section

Record the import in ext/versions.txt:

chmdec          dist       YYYY-MM-DD
  https://github.com/kjk/chmdec
  commit <full-upstream-hash>
  amalgamated dist/chm.c + dist/chm.h only

Use today's date for YYYY-MM-DD and the hash from step 1.

4. Check for API changes Copy Section

Diff the new ext/chmdec/chm.h against the previous version.

Pay special attention to:

• New functions — may need export entries and ChmFile.cpp updates
• Removed/renamed functions — update callers and exports
• chm_open buffer lifetime — the in-memory buffer is not copied; it must
  outlive the chm_ctx (SumatraPDF keeps file bytes in ChmFile until
  chm_ctx_free)

Current integration points:

5. Update DLL exports (if API changed) Copy Section

chmdec is linked into libsumatrapdf.dll (and into the static EXE). The DLL build of
SumatraPDF.exe, PdfFilter, and PdfPreview must not also link the
chmdec static lib — they import chm_* from libsumatrapdf.dll via
src/libsumatrapdf.def.

When new public functions are added, append them to the ; chmdec exports
section in src/libsumatrapdf.def.

Current chmdec exports:

chm_ctx_new
chm_ctx_free
chm_open
chm_close
chm_read_entry
chm_get_entries
LZX_test_pretree_make_decode_table

LZX_test_pretree_make_decode_table is a test-only hook used by -test-chm
(src/SumatraTest.cpp); it is defined in chm.c but not declared in chm.h.

6. Build and smoke-test Copy Section

bun cmd/build.ts -dbg
# optional CHM regression (needs a sample .chm):
# out/dbg64/SumatraPDF.exe -for-testing -test-chm path\to\file.chm
# out/dbg64/SumatraPDF.exe -for-testing -dump-chm path\to\file.chm

Also run bun tests/issue-chm-lzx.ts if LZX decode tables changed.

Commit message template Copy Chapter

Update chmdec to kjk/chmdec <short-hash>

Imported dist/chm.c and dist/chm.h from https://github.com/kjk/chmdec @ <full-hash>.

Notes Copy Chapter

• ext/chmdec is a single-file amalgamation (like sqlite / heicdec): compile
  chm.c only; include chm.h from callers.
• The static library project is named chmdec in premake / MSBuild; sources
  keep the historical chm_* C API names.
• Static SumatraPDF-static and test_engines still link chmdec directly
  (no libsumatrapdf.dll). The DLL-split products import via def exports only.

Upgrade Djvudec (`docs/upgrade-djvudec.md`) Copy Section

Upgrading djvudec

How to update SumatraPDF's vendored plain-C DjVu decoder (ext/djvudec/djvu.c +
ext/djvudec/djvu.h) from the upstream dist.

Upstream source Copy Chapter

• Repo: https://github.com/kjk/djvudec (main branch)
• Files to copy: dist/djvu.c and dist/djvu.h only
• Do NOT use https://codeberg.org/ccxvii/djvudec — that is an unrelated,
  older 2011 decoder with a different API (djvudec.h).

The amalgamated files are generated upstream by bun cmd/build-dist.ts. Never
edit ext/djvudec/djvu.c or ext/djvudec/djvu.h by hand in SumatraPDF.

Steps Copy Chapter

1. Fetch latest upstream dist Copy Section

Clone or refresh a shallow copy, then record the commit hash:

git clone --depth 1 https://github.com/kjk/djvudec.git /tmp/djvudec-update
git -C /tmp/djvudec-update rev-parse HEAD

If /tmp/djvudec-update already exists:

git -C /tmp/djvudec-update pull --ff-only

2. Copy dist files into ext/djvudec Copy Section

cp /tmp/djvudec-update/dist/djvu.c ext/djvudec/djvu.c
cp /tmp/djvudec-update/dist/djvu.h ext/djvudec/djvu.h

On Windows (PowerShell), use Copy-Item ... -Force — run the two copies as
separate commands (avoid ; chaining in the shell tool).

Do not clang-format files under ext/djvudec/ (vendored code).

3. Update ext/versions.txt Copy Section

Record the import in ext/versions.txt:

djvudec         main       YYYY-MM-DD
  https://github.com/kjk/djvudec
  commit <full-upstream-hash>
  amalgamated dist/djvu.c + dist/djvu.h only

Use today's date for YYYY-MM-DD and the hash from step 1.

4. Check for API changes Copy Section

Diff the new ext/djvudec/djvu.h against the previous version. The public API
is also documented in upstream src/djvu.h.

Pay special attention to:

• New functions — may need export entries and EngineDjvuDec.cpp updates
• Removed/renamed functions — update src/EngineDjvuDec.cpp and exports
• djvu_init() — must be called once before concurrent decode (bilinear
  scaler table). djvu_doc_open also calls it, but that is not enough when
  render threads race on first open. SumatraPDF guards this in
  EngineDjvuDec.cpp via DjvuDecInitOnce() (SRWLOCK, same pattern as
  EngineDjVu.cpp).

Current integration points:

5. Update DLL exports (if API changed) Copy Section

djvudec is statically linked into libsumatrapdf.dll; SumatraPDF.exe imports
djvu_* symbols from that DLL via src/libsumatrapdf.def.

When new public functions are added, append them to the ; djvudec exports
section in src/libsumatrapdf.def.

Current djvudec exports:

djvu_init
djvu_ctx_new
djvu_ctx_free
djvu_ctx_set_lazy_iw44
djvu_ctx_set_no_compose
djvu_ctx_set_iw_max_chunks
djvu_ctx_set_bgr
djvu_doc_open
djvu_doc_close
djvu_doc_page_count
djvu_doc_page_info
djvu_page_get_type
djvu_page_render
djvu_page_render_info
djvu_page_render_into
djvu_image_destroy
djvu_doc_page_id
djvu_doc_page_title
djvu_doc_page_by_name
djvu_page_text_get_zones
djvu_text_zones_destroy
djvu_doc_outline
djvu_outline_destroy
djvu_page_get_links
djvu_page_links_destroy

6. Update EngineDjvuDec (if needed) Copy Section

Review src/EngineDjvuDec.cpp for any API mismatches. Common cases:

• New init function → ensure a once-guarded call before concurrent use
• New metadata/render helpers → wire up if SumatraPDF should expose them
• Changed struct fields → fix accessors

After editing src/EngineDjvuDec.cpp, run:

clang-format -i src/EngineDjvuDec.cpp

7. Build and smoke-test Copy Section

bun cmd/build.ts -dbg

Test with:

./out/dbg64/SumatraPDF.exe -for-testing <path-to>.djvu

Use a .djvu from C:\Users\kjk\OneDrive\!sumatra\bugs\ if available.

8. Commit message Copy Section

Include the upstream commit hash:

Update djvudec to kjk/djvudec <short-hash>

Imported dist/djvu.c and dist/djvu.h from https://github.com/kjk/djvudec @ <full-hash>.

Append prompt: ... if the change was AI-assisted (per Agents.md).

Architecture notes Copy Chapter

• ext/djvudec is a single-file amalgamation (like sqlite): compile
  djvu.c directly; include djvu.h.
• EngineDjvuDec keeps a single shared djvu_doc (read-only after open);
  djvu_page_render_into / metadata calls are re-entrant on the same doc.
• Thread-safety analysis lives in docs/djvudec-threading.md and upstream
  thread-safety.md.
• djvudec is the only DjVu engine (the libdjvu-based EngineDjVu has been
  removed; EngineCreate.cpp creates EngineDjvuDec for all DjVu files).

Checklist Copy Chapter

• Copied dist/djvu.c and dist/djvu.h from kjk/djvudec
• Updated ext/versions.txt with import date and upstream commit hash
• Checked djvu.h for API changes
• Updated src/libsumatrapdf.def if exports changed
• Updated EngineDjvuDec.cpp if integration changed
• Did not clang-format ext/djvudec/
• bun cmd/build.ts -dbg succeeds
• Smoke-tested a .djvu file

Wishlist (`docs/wishlist.txt`) Copy Section

-- text viewer (high)

Important thing: make it work even with gigantic files by limiting how much of
the file we load in memory (1-10 MB?). We would only build and index for each
line, consisting of:

• position in the file
• length in bytes
• encoding (to support various encodings; but we would start by only supporting
  ascii/utf8)
• measured size of this line

We would build that index for the whole file in the background thread, then
only load the needed part as the user scrolls through the document.

-- hex viewer (high)

-- better looking notifications (med)

Visual style of notifications is dated. Use more modern look e.g. inspired by
Chrome or Android.

-- faster re-layout for eBooks (med, risky)

Layout time is dominated by measuring strings.

Split layout into 2 or 3 phases:

• generate instructions (text fragments, images, font/style changes etc.)
• measure strings, images etc.
• calculating positions of the elements given page dx/dy and break them into pages

When users resizes the window, we would only need to redo phase 3. A small
complication: when a string doesn't fit in a single line, we need to split
it into to string instructions. We would need to be able to do it e.g. by
adding a "compound" instruction, that just contains one or more other instructions.
That way the instruction stream would be almost-immutable, and we could turn
a e.g. a long string into 2 smaller strings by replacing string instruction with
"compound" instructions that points to the original string instructions (so that we
can undo that in the next layout) and 2 or more substrings.

Changing default font would require redoing phase 2 and 3.

-- eBook: re-introduce preserving top of page after re-layout (risky, med)

The code to preserve current top of page after re-layout was so complicated
that I had to remove it in order to implement dual pages in eBook mode.
It would be nice to bring it back in a saner way and without the problem
of breaking the styling.
It would be easier if we implement faster re-layout as described above and
have every element remember its reparse point (instead of having it on a
per-page basis).

That way we would generate instructions just once. A page would just be:
(index of first instruction, number of instructions).

We could avoid breaking styling because now we have access to the whole instruction
stream and we could quickly scan back instructions from any point to find
formatting instructions and recover current styling.

-- manual cropping of margins for PDFs (med, risky)

Screen space is always at premium and most PDFs have very wasteful
margins. Good Reader has a really nice feature for manual cropping of margins
(https://www.goodiware.com/gr-man-view-pdf.html#crop). They have a mode for
manually selecting visible part of the PDF, similar to how many graphics
program implement cropping. Cropping can be set for all pages or separately
for odd/even pages. Cropping can also be reset. After cropping, the program
only shows the non-cropped part. This would be especially valuable for small
screens (netbooks/small laptops).

Note: Automatic cropping is currently implemented as "Fit Content" View mode.
Note to note: it's similar but not really the same. One big difference is that
with this style of cropping, for the purpose of layout and display the cropped
part doesn't exist. Fit Content positions the page so that it's out of the view,
but change zoom and it's really there.
Plus, automatic cropping has limitations. There are many cases where a PDF has
lots of white-space but cannot be cropped because has some small thing there,
like a page number.

-- Editing/saving of PDF forms (high)

-- Integration with web-based backup/viewer system (high)

The idea is that users could easily backup their PDFs on the server. They would
have a convenient access to those PDFs from Sumatra as well as being able to
view them on the web. Basically it would be private Scribd for PDFs only. The
web service would have to be paid (since on-line storage is rather expensive)
but there would be free accounts (with quota, similar to how Dropbox works).

-- Document library management (high)

Similar to how e.g. Picasa manages photos or iTunes manages mp3 files.

User would tell us which directories contain PDF and other supported files
(or, on Win 7, we could use windows search or scan the whole hard-drive to
automatically find all files). We would index the files (their filenames, metadata,
maybe extract text for full-text search), build thumbnails and allow efficient
browsing/searching those files.

This would be a good feature for those who have large collections of PDFs
(compared to using file explorer or open file dialog for locating the file).

-- use pdfium (high)

Google released https://pdfium.googlesource.com/pdfium/ which is Foxit codebase
under BSD license.

It would probably be a bunch of work to integrate this (although at first it
could be done alongside mupdf, since we have necessary abstractions to plug
another engine). So that's the downside.

I've briefly looked at the code and it might have some benefits over mupdf:

• they have hooks for form editing (which should make implementing this much
  easier)
• their printing code looks more efficient
• they probably support some of the more advanced PDF features
• they are probably faster and (thanks to Google) more secure

Writing Docs (`docs/writing-docs.md`) Copy Section

Writing user docs (sumatra-website www/docs)

Pattern for feature pages, modeled on https://outliner.tana.inc/learn/features/sidebar.

Page shape Copy Chapter

1. # Title — the feature name, as it appears in the UI.
2. Summary (1–2 sentences, first thing after the title): what the feature is,
   where it lives in the UI, what you use it for. No version note before it.
3. Version note on its own line after the summary: **Available in version 3.6 or later.**
4. Bold lead sentence naming the most common use, then an at a glance list:
   one bullet per capability, **Name:** what it does, with its shortcut.
5. Task sections, in order of how often people need them.
   • Headings are tasks, not nouns: "Add a favorite", "Collapse the sidebar", not "Favorites".
   • Under each, list every way to do it: mouse / menu, keyboard shortcut,
     Command Palette command, advanced setting, command-line.
6. ## Tips — 3–6 short, practical bullets ("Use X to ...").
7. Reference sections (settings tables, flags, DDE) near the end.
8. ## See also — links to related pages with a few words on why.

Short pages (troubleshooting, one-off how-tos) only need 1, 2 and the content.

Style Copy Chapter

• Second person, present tense, imperative steps: "Press Ctrl + B".
• Shortcuts in code: Ctrl + Shift + N. Menu paths bold: Settings → Advanced Settings....
• Command Palette: Ctrl + K, then Toggle Favorites. Name the command id (CmdFavoriteToggle) once, for rebinding.
• Put the fix right after the problem: "If X, do Y."
• Tips, notes and caveats are one line, prefixed Tip: / Note:. No paragraphs of background.
• Link the first mention of another feature to its page.
• Don't document bugs or history; say how it works now. Keep (ver 3.7+) markers where behavior differs by version.

Videos Copy Chapter

A video goes on its own line, e.g. right after the title:
:video <youtube link> <r2 link> (the R2 link is the web version under
https://files.sumatrapdfreader.org/assets/sumatrapdf/docs/video/). The website and the
in-app manual (gen_docs.render.js) render it as an embedded YouTube player. How to record
and upload one: "Doc videos" in the website's agents.md.

Index Copy Chapter

SumatraPDF-documentation.md groups pages by task (getting started, reading, ...).
Every page link must stay inside a :columns block — the in-app TOC is built from those.
Pages under ## Misc docs (up to ## Downloads) are excluded from the in-app manual.

Test SumatraPDF Settings (`docs/test/SumatraPDF-settings.txt`) Copy Section

For documentation, see https://www.sumatrapdfreader.org/settings/settings3-7.html

DefaultDisplayMode = automatic
DefaultZoom = fit page
DisableJavaScript = false
AllowExternalImages = false
EnableTeXEnhancements = false
EscToExit = false
FullPathInTitle = false
LazyLoading = false
MainWindowBackground = #80fff200
NoHomeTab = false
HomePageSortByFrequentlyRead = false
HomePageViewMode = thumbnails
ThumbnailsType = full
ReloadModifiedDocuments = true
RememberOpenedFiles = true
RememberStatePerDocument = true
RestoreSession = true
ReuseInstance = true
ShowMenubar = true
ShowMenubarWithTabs = false
ShowPageNumberInTabs = false
ShowHomePageReadingProgress = true
ShowChaptersInEbooks = false
ShowTips = true
ShowToolbar = true
Toolbar = show
ToolbarPosition = top
SearchUIFloating = false
ShowFavorites = false
SortFavoritesByName = false
ShowToc = true
AlwaysShowSidebar = false
SidebarOnRight = false
ShowLinks = false
HighlightFormFields = true
ClickEdgeToTurnPage = false
DisableLinks = false
ExplorerQuickLook = false
RememberViewOffsetOnPageTurn = false
MouseWheelTurnsPage = false
ScrollEdgeTurnsPage = true
ShowDocumentFocusIndicator = false
ShowAnnotationNotification = true
ShowFileNavigateHint = true
ShowAnnotationAuthorInTooltip = false
ShowTocPageNumbers = true
AutoGenerateTOC = false
ShowStartPage = true
SidebarDx = 0
Scrollbars = windows
ScrollbarInSinglePage = false
SmoothScroll = true
ScrollLineAmount = 16
SaveMemory = 50
PaddingAfterLastPage = false
IgnoreDestinationZoom = false
HighlightLinkDestination = false
CitationHoverDelay = -1
ReadAloudSpeed = 1
ReadingAutoScrollSpeed = 40
ReadingBar [
Background = #66ffe082
Invert = false
Height = 0
]
FastScrollOverScrollbar = false
PreventSleepInFullscreen = true
TabWidth = 300
Theme = Light
HelpTheme = app
DocumentColorsFollowTheme = off
TocDy = 0
ToolbarShowReadAloud = false
ToolbarSize = 18
TreeFontName = automatic
TreeFontSize = 0
UIFontSize = 0
DisableAntiAlias = false
EngineeringDrawingEnhance = off
DisableAutoLinks = false
UseSysColors = false
UseTabs = true
SelectionToolbar = true
TabsMru = false
CtrlTabSimple = false
ZoomLevels =
ZoomIncrement = 0

FixedPageUI [
Grayscale = false
TextColor = #000000
BackgroundColor = #ffffff
SelectionColor = #ffff00
WindowMargin = 2 4 2 4
PageSpacing = 4 4
PageGrid [
Width = 72
Height = 72
Subdivisions = 4
OffsetX = 0
OffsetY = 0
Color = #8080ff
Style = dots
Units = in
]
]

EBookUI [
FontSize = 0
LineSpacing = 0
LayoutDx = 0
LayoutDy = 0
IgnoreDocumentCSS = false
]

ComicBookUI [
WindowMargin = 0 0 0 0
PageSpacing = 4 4
CbxMangaMode = false
LimitToWindowWidth = false
LimitToWindowHeight = false
AutoRotateWidePages = false
LandscapeAsSpread = true
]

ImageUI [
DefaultZoom = shrink to fit
LimitToWindowWidth = false
LimitToWindowHeight = false
LandscapeAsSpread = true
]

ChmUI [
UseFixedPageUI = false
]

MarkdownUI [
UseFixedPageUI = false
]

HtmlUI [
UseFixedPageUI = false
]

ClaudeCode [
Model = sonnet
Effort = 1
SkipPermissions = false
BgColor = #ffffff
]

GrokBuild [
Model = grok-4.5
Effort = 1
AlwaysApprove = false
BgColor = #ffffff
]

CodexBuild [
Model = gpt-5.5
Sandbox = 1
SkipSandbox = false
BgColor = #ffffff
]

AntiGravity [
Model = gemini-3.8-flash-medium
Effort = 1
AutoApprove = true
BgColor = #ffffff
]

AIChatSidebarDx = 0

Annotations [
HighlightColor = #ffff00
UnderlineColor = #8bf05d
SquigglyColor = #f199d2
StrikeOutColor = #e24745
FreeTextOpacity = 100
FreeTextSize = 12
FreeTextBorderWidth = 1
FreeTextAlignment = left
PresetColors = #ffff00 #8bf05d #99defa #f199d2 #e24745 #ff0000 #0000ff #000000
InkColor = #66ffff00
InkColors = #66ffff00 #668bf05d #6699defa #66f199d2 #66e24745
InkBorderWidth = 16
]

ExternalViewers [
]

ForwardSearch [
HighlightOffset = 0
HighlightWidth = 15
HighlightColor = #6581ff
HighlightPermanent = false
]

PrinterDefaults [
PrintScale = shrink
Collate = default
PrintDpi = 0
]

Fullscreen [
ShowToolbar = false
Toolbar = hide
ShowMenubar = false
]

SelectionHandlers [
]

TextSnippets [
]

Shortcuts [
]

Themes [
]

TabGroups [
]

CustomScreenDPI = 0

You're not expected to change those manually

WindowState = 1
WindowPos = 0 0 0 0
SearchUIWindowPos = 0 0 0 0
AnnotationsWindowShowNote = false
HelpWindowPos = 0 0 0 0
FileStates [
]
SessionData [
]
TimeOfLastUpdateCheck = 0 0
OpenCountWeek = 0
PropWinPos = 0 0
CheckForUpdates = true

Settings below are not recognized by the current version

Test Test (`docs/test/test.md`) Copy Section

Test document

Test data for test_engines -model-toc and the MarkdownModel /
MarkdownToc unit tests. Keep it small and keep the headings: the table of
contents below is what the test prints.

Headings Copy Chapter

Every heading becomes a table-of-contents entry, anchored by its GitHub slug.

A nested heading Copy Section

Text under a level 3 heading.

adc_intr_ctl . TRANS_EN Copy Section

The slug of this one is adc_intr_ctl--trans_en: underscores survive,
punctuation is dropped, each space becomes its own dash.

Links Copy Chapter

A relative link and an external one.

Code Copy Chapter

let n = 1;

A table Copy Chapter

Ext A Freetype Docs FTL (`ext/a-freetype/docs/FTL.TXT`) Copy Section

The FreeType Project LICENSE
----------------------------

2006-Jan-27

                Copyright 1996-2002, 2006 by
      David Turner, Robert Wilhelm, and Werner Lemberg

Introduction

The FreeType Project is distributed in several archive packages;
some of them may contain, in addition to the FreeType font engine,
various tools and contributions which rely on, or relate to, the
FreeType Project.

This license applies to all files found in such packages, and
which do not fall under their own explicit license. The license
affects thus the FreeType font engine, the test programs,
documentation and makefiles, at the very least.

This license was inspired by the BSD, Artistic, and IJG
(Independent JPEG Group) licenses, which all encourage inclusion
and use of free software in commercial and freeware products
alike. As a consequence, its main points are that:

o We don't promise that this software works. However, we will be
  interested in any kind of bug reports. (`as is' distribution)

o You can  use this software for whatever you  want, in parts or
  full form, without having to pay us. (`royalty-free' usage)

o You may not pretend that  you wrote this software.  If you use
  it, or  only parts of it,  in a program,  you must acknowledge
  somewhere  in  your  documentation  that  you  have  used  the
  FreeType code. (`credits')

We specifically permit and encourage the inclusion of this
software, with or without modifications, in commercial products.
We disclaim all warranties covering The FreeType Project and
assume no liability related to The FreeType Project.

Finally, many people asked us for a preferred form for a
credit/disclaimer to use in compliance with this license. We thus
encourage you to use the following text:

"""
Portions of this software are copyright © The FreeType
Project (https://freetype.org). All rights reserved.
"""

Please replace with the value from the FreeType version you
actually use.

Legal Terms

0. Definitions

Throughout this license, the terms package', FreeType Project',
and FreeType archive' refer to the set of files originally distributed by the authors (David Turner, Robert Wilhelm, and Werner Lemberg) as the FreeType Project', be they named as alpha,
beta or final release.

You' refers to the licensee, or person using the project, where using' is a generic term including compiling the project's source
code as well as linking it to form a program' or executable'.
This program is referred to as `a program using the FreeType
engine'.

This license applies to all files distributed in the original
FreeType Project, including all source code, binaries and
documentation, unless otherwise stated in the file in its
original, unmodified form as distributed in the original archive.
If you are unsure whether or not a particular file is covered by
this license, you must contact us to verify this.

The FreeType Project is copyright (C) 1996-2000 by David Turner,
Robert Wilhelm, and Werner Lemberg. All rights reserved except as
specified below.

1. No Warranty

THE FREETYPE PROJECT IS PROVIDED `AS IS' WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. IN NO EVENT WILL ANY OF THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY DAMAGES CAUSED BY THE USE OR THE INABILITY TO
USE, OF THE FREETYPE PROJECT.

2. Redistribution

This license grants a worldwide, royalty-free, perpetual and
irrevocable right and license to use, execute, perform, compile,
display, copy, create derivative works of, distribute and
sublicense the FreeType Project (in both source and object code
forms) and derivative works thereof for any purpose; and to
authorize others to exercise some or all of the rights granted
herein, subject to the following conditions:

o Redistribution of  source code  must retain this  license file
  (`FTL.TXT') unaltered; any  additions, deletions or changes to
  the original  files must be clearly  indicated in accompanying
  documentation.   The  copyright   notices  of  the  unaltered,
  original  files must  be  preserved in  all  copies of  source
  files.

o Redistribution in binary form must provide a  disclaimer  that
  states  that  the software is based in part of the work of the
  FreeType Team,  in  the  distribution  documentation.  We also
  encourage you to put an URL to the FreeType web page  in  your
  documentation, though this isn't mandatory.

These conditions apply to any software derived from or based on
the FreeType Project, not just the unmodified files. If you use
our work, you must acknowledge us. However, no fee need be paid
to us.

3. Advertising

Neither the FreeType authors and contributors nor you shall use
the name of the other for commercial, advertising, or promotional
purposes without specific prior written permission.

We suggest, but do not require, that you use one or more of the
following phrases to refer to this software in your documentation
or advertising materials: FreeType Project', FreeType Engine',
FreeType library', or FreeType Distribution'.

As you have not signed this license, you are not required to
accept it. However, as the FreeType Project is copyrighted
material, only this license, or another one contracted with the
authors, grants you the right to use, distribute, and modify it.
Therefore, by using, distributing, or modifying the FreeType
Project, you indicate that you understand and accept all the terms
of this license.

4. Contacts

There are two mailing lists related to FreeType:

o [email protected]

  Discusses general use and applications of FreeType, as well as
  future and  wanted additions to the  library and distribution.
  If  you are looking  for support,  start in  this list  if you
  haven't found anything to help you in the documentation.

o [email protected]

  Discusses bugs,  as well  as engine internals,  design issues,
  specific licenses, porting, etc.

Our home page can be found at

https://freetype.org

--- end of FTL.TXT ---

Ext A Freetype Docs GPLv2 (`ext/a-freetype/docs/GPLv2.TXT`) Copy Section

GNU GENERAL PUBLIC LICENSE
Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users. This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.) You can apply it to
your programs, too.

When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must show them these terms so they know their
rights.

We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

Finally, any free program is threatened constantly by software
patents. We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary. To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and
modification follow.

GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains
   a notice placed by the copyright holder saying it may be distributed
   under the terms of this General Public License. The "Program", below,
   refers to any such program or work, and a "work based on the Program"
   means either the Program or any derivative work under copyright law:
   that is to say, a work containing the Program or a portion of it,
   either verbatim or with modifications and/or translated into another
   language. (Hereinafter, translation is included without limitation in
   the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's
   source code as you receive it, in any medium, provided that you
   conspicuously and appropriately publish on each copy an appropriate
   copyright notice and disclaimer of warranty; keep intact all the
   notices that refer to this License and to the absence of any warranty;
   and give any other recipients of the Program a copy of this License
   along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion
   of it, thus forming a work based on the Program, and copy and
   distribute such modifications or work under the terms of Section 1
   above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

c) If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)


These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

3. You may copy and distribute the Program (or a work based on it,
   under Section 2) in object code or executable form under the terms of
   Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it. For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable. However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

5. You are not required to accept this License, since you have not
   signed it. However, nothing else grants you permission to modify or
   distribute the Program or its derivative works. These actions are
   prohibited by law if you do not accept this License. Therefore, by
   modifying or distributing the Program (or any work based on the
   Program), you indicate your acceptance of this License to do so, and
   all its terms and conditions for copying, distributing or modifying
   the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the
   Program), the recipient automatically receives a license from the
   original licensor to copy, distribute or modify the Program subject to
   these terms and conditions. You may not impose any further
   restrictions on the recipients' exercise of the rights granted herein.
   You are not responsible for enforcing compliance by third parties to
   this License.

7. If, as a consequence of a court judgment or allegation of patent
   infringement or for any other reason (not limited to patent issues),
   conditions are imposed on you (whether by court order, agreement or
   otherwise) that contradict the conditions of this License, they do not
   excuse you from the conditions of this License. If you cannot
   distribute so as to satisfy simultaneously your obligations under this
   License and any other pertinent obligations, then as a consequence you
   may not distribute the Program at all. For example, if a patent
   license would not permit royalty-free redistribution of the Program by
   all those who receive copies directly or indirectly through you, then
   the only way you could satisfy both it and this License would be to
   refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded. In such case, this License incorporates
the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions
   of the General Public License from time to time. Such new versions will
   be similar in spirit to the present version, but may differ in detail to
   address new problems or concerns.

Each version is given a distinguishing version number. If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation. If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

10. If you wish to incorporate parts of the Program into other free
    programs whose distribution conditions are different, write to the author
    to ask for permission. For software which is copyrighted by the Free
    Software Foundation, write to the Free Software Foundation; we sometimes
    make exceptions for this. Our decision will be guided by the two goals
    of preserving the free status of all derivatives of our free software and
    of promoting the sharing and reuse of software generally.

    text Copy

    NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
    FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
    OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
    PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
    OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
    TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
    PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
    REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
    WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
    REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
    INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
    OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
    TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
    YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
    PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
    POSSIBILITY OF SUCH DAMAGES.

    text Copy

    END OF TERMS AND CONDITIONS

    How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

Gnomovision version 69, Copyright (C) year  name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w' and show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may
be called something other than show w' and show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General
Public License instead of this License.

Ext Mupdf Docs Index (`ext/mupdf/docs/index.rst`) Copy Section

Welcome to MuPDF

.. welcome:
.. image:: images/mupdf-icon.svg
:width: 33%
:align: center
:alt: [MuPDF Logo]
:target: welcome

MuPDF is an open source software framework for viewing and converting PDF, XPS,
and E-book documents. There are viewers for various platforms, several command
line tools, and a software library for building tools and applications.

It is available under either the GNU GPL Affero license <https://www.gnu.org/licenses/agpl-3.0.html>_
or licensed for commercial <https://artifex.com/licensing?utm_source=rtd-mupdf&utm_medium=rtd&utm_content=inline-link#commercial-license>_
use from Artifex Software, Inc <https://artifex.com/?utm_source=rtd-mupdf&utm_medium=rtd&utm_content=inline-link>_.

.. toctree::
:caption: Guides
:maxdepth: 1

guide/what-is-mupdf
license
guide/install
guide/using-with-javascript
guide/using-with-java
guide/using-with-android
tools/index

.. toctree::
:caption: Cookbook
:maxdepth: 1

cookbook/mupdf-explored
cookbook/c/index
cookbook/progressive-loading
cookbook/javascript/index

.. toctree::
:caption: Reference
:maxdepth: 1

reference/common/index
reference/c/index
reference/javascript/index
reference/cxx-and-derived-bindings

.. toctree::
:caption: Other
:maxdepth: 1

other/changes
other/third-party

Ext Mupdf Docs Requirements (`ext/mupdf/docs/requirements.txt`) Copy Section

furo
linkify-it-py
myst-parser
readthedocs-sphinx-search==0.3.2
sphinx==8.2.3
sphinxcontrib-googleanalytics
sphinxcontrib-imagesvg
pipcl

Ext Mupdf Docs Cookbook Mupdf Explored (`ext/mupdf/docs/cookbook/mupdf-explored.md`) Copy Section

MuPDF Explored

Read the
MuPDF Explored
book by Robin Watts for an in depth exploration of MuPDF.

Ext Mupdf Docs Cookbook Progressive Loading (`ext/mupdf/docs/cookbook/progressive-loading.md`) Copy Section

Progressive Loading

What is progressive loading? Copy Chapter

The idea of progressive loading is that as you download a PDF file into a browser, you can display the pages as they appear.

MuPDF can make use of 2 different mechanisms to achieve this. The first relies on the file being "linearized", the second relies on the caller of MuPDF having fine control over the http fetch and on the server supporting byte-range fetches.

For optimum performance a file should be both linearized and be available over a byte-range supporting link, but benefits can still be had with either one of these alone.

Progressive download using "linearized" files Copy Chapter

Adobe defines "linearized" PDFs as being ones that have both a specific layout of objects and a small amount of extra information to help avoid seeking within a file. The stated aim is to deliver the first page of a document in advance of the whole document downloading, whereupon subsequent pages will become available. Adobe also refers to these as "Optimized for fast web view" or "Web Optimized".

In fact, the standard outlines (poorly) a mechanism by which 'hints' can be included that enable the subsequent pages to be found within the file too. Unfortunately this is very poorly supported with many tools, and so the hints have to be treated with suspicion.

MuPDF will attempt to use hints if they are available, but will also use a linear search of the file to discover pages if not. This means that the first page will be displayed quickly, and then subsequent ones will appear with 'incomplete' renderings that improve over time as more and more resources are gradually delivered.

Essentially the file starts with a slightly modified header, and the first object in the file is a special one (the linearization object) that:

• indicates that the file is linearized.
• gives some useful information (like the number of pages in the file).

This object is then followed by all the objects required for the first page, then the "hint stream", then sets of object for each subsequent page in turn, then shared objects required for those pages, then various other random things.

While page 1 is sent with all the objects that it uses, shared or otherwise, subsequent pages do not get shared resources until after all the unshared page objects have been sent.

The Hint Stream Copy Chapter

Adobe intended "Hint Stream" to be useful to facilitate the display of subsequent pages, but it has never used it. Consequently you can't trust people to write it properly - indeed Adobe outputs something that doesn't quite conform to the specification.

Consequently very few people actually use it. MuPDF will use it after sanity checking the values, and should cope with illegal/incorrect values.

So how does MuPDF handle progressive loading? Copy Chapter

MuPDF has made various extensions to its mechanisms for handling progressive loading.

Progressive streams Copy Section

At its lowest level MuPDF reads file data from a fz_stream, using the fz_open_document_with_stream call. (fz_open_document is implemented by calling this). We have extended the fz_stream slightly, giving the system a way to ask for meta information (or perform meta operations) on a stream.

Using this mechanism MuPDF can query:

• whether a stream is progressive or not (i.e. whether the entire stream is accessible immediately).
• what the length of a stream should ultimately be (which an http fetcher should know from the Content-Length header).

With this information MuPDF can decide whether to use its normal object reading code, or whether to make use of a linearized object. Knowing the length enables us to check with the length value given in the linearized object - if these differ, the assumption is that an incremental save has taken place, thus the file is no longer linearized.

When data is pulled from a progressive stream, if we attempt to read data that is not currently available, the stream should throw a FZ_ERROR_TRYLATER error. This particular error code will be interpreted by the caller as an indication that it should retry the parsing of the current objects at a later time.

When a MuPDF call is made on a progressive stream, such as fz_open_document_with_stream, or fz_load_page, the caller should be prepared to handle a FZ_ERROR_TRYLATER error as meaning that more data is required before it can continue. No indication is directly given as to exactly how much more data is required, but as the caller will be implementing the progressive fz_stream that it has passed into MuPDF to start with, it can reasonably be expected to figure out an estimate for itself.

Progress Cookie Copy Section

Once a page has been loaded, if its contents are to be 'run' as normal (using e.g. fz_run_page) any error (such as failing to read a font, or an image, or even a content stream belonging to the page) will result in a rendering that aborts with an FZ_ERROR_TRYLATER error. The caller can catch this and display a placeholder instead.

If each pages data was entirely self-contained and sent in sequence this would perhaps be acceptable, with each page appearing one after the other. Unfortunately, the linearization procedure as laid down by Adobe does not do this: objects shared between multiple pages (other than the first) are not sent with the pages themselves, but rather after all the pages have been sent.

This means that a document that has a title page, then contents that share a font used on pages 2 onwards, will not be able to correctly display page 2 until after the font has arrived in the file, which will not be until all the page data has been sent.

To mitigate against this, MuPDF provides a way whereby callers can indicate that they are prepared to accept an 'incomplete' rendering of the file (perhaps with missing images, or with substitute fonts).

Callers prepared to tolerate such renderings should set the incomplete_ok flag in the cookie, then call fz_run_page etc. as normal. If a FZ_ERROR_TRYLATER error is thrown at any point during the page rendering, the error will be swallowed, the 'incomplete' field in the cookie will become non-zero and rendering will continue. When control returns to the caller the caller can check the value of the 'incomplete' field and know that the rendering it received is not authoritative.

Progressive loading using byte range requests Copy Chapter

If the caller has control over the http fetch, then it is possible to use byte range requests to fetch the document 'out of order'. This enables non-linearized files to be progressively displayed as they download, and fetches complete renderings of pages earlier than would otherwise be the case. This process requires no changes within MuPDF itself, but rather in the way the progressive stream learns from the attempts MuPDF makes to fetch data.

Consider, for example, an attempt to fetch a hypothetical file from a server.

• The initial http request for the document is sent with a "Range:" header to pull down the first (say) 4k of the file.

• As soon as we get the header in from this initial request, we can respond to meta stream operations to give the length, and whether byte requests are accepted.

• If the header indicates that byte ranges are acceptable the stream proceeds to go into a loop fetching chunks of the file at a time (not necessarily in-order). Otherwise the server will ignore the Range: header, and just serve the whole file.

• If the header indicates a content-length, the stream returns that.

• MuPDF can then decide how to proceed based upon these flags and whether the file is linearized or not. (If the file contains a linearized object, and the content length matches, then the file is considered to be linear, otherwise it is not).

If the file is linear: Copy Section

• We proceed to read objects out of the file as it downloads. This will provide us the first page and all its resources. It will also enable us to read the hint streams (if present).

• Once we have read the hint streams, we unpack (and sanity check) them to give us a map of where in the file each object is predicted to live, and which objects are required for each page. If any of these values are out of range, we treat the file as if there were no hint streams.

• If we have hints, any attempt to load a subsequent page will cause MuPDF to attempt to read exactly the objects required. This will cause a sequence of seeks in the fz_stream followed by reads. If the stream does not have the data to satisfy that request yet, the stream code should remember the location that was fetched (and fetch that block in the background so that future retries will succeed) and should raise an FZ_ERROR_TRYLATER error.

Typically therefore when we jump to a page in a linear file on a byte request capable link, we will quickly see a rough rendering, which will improve fairly fast as images and fonts arrive.

• Regardless of whether we have hints or byte requests, on every fz_load_page call MuPDF will attempt to process more of the stream (that is assumed to be being downloaded in the background). As linearized files are guaranteed to have pages in order, pages will gradually become available. In the absence of byte requests and hints however, we have no way of getting resources early, so the renderings for these pages will remain incomplete until much more of the file has arrived.

Typically therefore when we jump to a page in a linear file on a non byte request capable link, we will see a rough rendering for that page as soon as data arrives for it (which will typically take much longer than would be the case with byte range capable downloads), and that will improve much more slowly as images and fonts may not appear until almost the whole file has arrived.

• When the whole file has arrived, then we will attempt to read the outlines for the file.

For a non-linearized PDF on a byte request capable stream: Copy Section

• MuPDF will immediately seek to the end of the file to attempt to read the trailer. This will fail with a FZ_ERROR_TRYLATER due to the data not being here yet, but the stream code should remember that this data is required and it should be prioritized in the background fetch process.

• Repeated attempts to open the stream should eventually succeed therefore. As MuPDF jumps through the file trying to read first the xrefs, then the page tree objects, then the page contents themselves etc., the background fetching process will be driven by the attempts to read the file in the foreground.

Typically therefore the opening of a non-linearized file will be slower than a linearized one, as the xrefs/page trees for a non-linear file can be 20%+ of the file data. Once past this initial point however, pages and data can be pulled from the file almost as fast as with a linearized file.

For a non-linearized PDF on a non-byte request capable stream: Copy Section

• MuPDF will immediately seek to the end of the file to attempt to read the trailer. This will fail with a FZ_ERROR_TRYLATER due to the data not being here yet. Subsequent retries will continue to fail until the whole file has arrived, whereupon the whole file will be instantly available.

This is the worst case situation - nothing at all can be displayed until the entire file has downloaded.

A typical structure for a fetcher process (see curl-stream.c, mupdf-curl in platform/win32/mupdf-curl.vcxproj) as an example) might therefore look like this:

• We consider the file as an (initially empty) buffer which we are filling by making requests. In order to ensure that we make maximum use of our download link, we ensure that whenever one request finishes, we immediately launch another. Further, to avoid the overheads for the request/response headers being too large, we may want to divide the file into 'chunks', perhaps 4 or 32k in size.

• We can then have a receiver process that sits there in a loop requesting chunks to fill this buffer. In the absence of any other impetus the receiver should request the next 'chunk' of data from the file that it does not yet have, following the last fill point. Initially we start the fill point at the beginning of the file, but this will move around based on the requests made of the progressive stream.

• Whenever MuPDF attempts to read from the stream, we check to see if we have data for this area of the file already. If we do, we can return it. If not, we remember this as the next "fill point" for our receiver process and throw a FZ_ERROR_TRYLATER error.

Ext Mupdf Docs Guide Install (`ext/mupdf/docs/guide/install.md`) Copy Section

Installing

Download Copy Chapter

Either download a release or clone the latest
source from the Git repository:

git clone git://git.ghostscript.com/mupdf.git

You will also need to initialize the submodules if you cloned from git:

git submodule update --init --depth 1

Build on Windows Copy Chapter

For Windows use the Visual Studio solution file in platform/win32/mupdf.sln.

Build on MacOS Copy Chapter

MacOS should be buildable in the same way as for Linux, but the exact set of
required libraries may vary. No viewer option is available as standard.

Build on Linux (and BSD and macOS) Copy Chapter

Use the GNU makefile to build on Linux or the BSDs.

make

The viewers require the X11 (and OpenGL for mupdf-gl) headers and libraries to build.
Install these packages (the exact package names may vary depending on your distro of choice):

sudo apt install xorg-dev libxcursor-dev libxrandr-dev libxinerama-dev
sudo apt install mesa-common-dev libgl1-mesa-dev libglu1-mesa-dev

Alternatively, if you only want to build the MuPDF library command line tools:

make tools

Testing the build Copy Chapter

The steps above will put the libraries and binaries in the build/release/ directory.

The tools and viewers are portable executables that don't need any auxiliary
files, so can be run from anywhere. To make sure that everything works, you can
run them directly from the build directory:

./build/release/mutool -v

Install on Linux Copy Chapter

You can safely copy the binaries to any directory in your path.

cp ./build/release/mutool ~/.local/bin/mutool

Or, if you prefer you can install the binaries, libraries, and headers system wide:

make prefix=/usr/local install

Good luck!

Ext Mupdf Docs Guide Using With Android (`ext/mupdf/docs/guide/using-with-android.md`) Copy Section

Using with Android

Introduction Copy Chapter

This document outlines the steps necessary to use the MuPDF Android Library in various ways.

First, we show you how to embed MuPDF in your app. Then, we explain how to
customize the viewer if you need to change how it looks or behaves. Finally, we
tell you where to go if you need to do work on the library itself.

Embedding the viewer in your app provides an activity that you can start to
view PDF documents from within your app. This should be enough for most use
cases.

Acquire a valid license Copy Chapter

Open Source license Copy Section

If your software is open source, you may use MuPDF under the terms of the
GNU Affero General Public License.

This means that all of the source code for your complete app must be
released under a compatible open source license!

It also means that you may not use any proprietary closed source libraries or
components in your app. This includes (but is not limited to):

• Google Play Services
• Google Mobile Services
• AdMob by Google
• Crashlytics
• Answers
• etc.

Just because a library ships with Android or is made by Google does not make it AGPL compatible!

If you cannot or do not want to comply with these restrictions, you must acquire a commercial license instead.

Commercial license Copy Section

If your software is not open source, Artifex Software can sell you a license to use MuPDF in closed source software.

Fill out the
MuPDF product inquiry form
for commercial licensing terms and pricing.

Add the MuPDF Library to your project Copy Chapter

The MuPDF library uses the Gradle build system.
In order to include MuPDF in your app, you also need to use Gradle.
The Eclipse and Ant build systems are not supported.

The MuPDF library needs Android version 4.1 or newer.
Make sure that the minSdkVersion in your app's build.gradle is at least 16.

android {
	defaultConfig {
		minSdkVersion 16
		...
	}
	...
}

The MuPDF library can be retrieved as a pre-built artifact from our Maven repository.
In your project's top build.gradle, add the line to the repositories section:

allprojects {
	repositories {
		jcenter()
			maven { url 'http://maven.ghostscript.com' }
		...
	}
}

Then add the MuPDF viewer library to your app's dependencies.
In your app's build.gradle, add the line to the dependencies section:

dependencies {
	api 'com.artifex.mupdf:viewer:1.15.+'
	...
}

Invoke the document viewer activity Copy Chapter

Once this has been done, you have access to the MuPDF viewer activity.
You can now open a document viewing activity by launching an Intent,
passing the URI of the document you wish to view.

import com.artifex.mupdf.viewer.DocumentActivity;

public void startMuPDFActivity(Uri documentUri) {
	Intent intent = new Intent(this, DocumentActivity.class);
	intent.setAction(Intent.ACTION_VIEW);
	intent.setData(documentUri);
	startActivity(intent);
}

How to customize the viewer Copy Chapter

If you've already tried embedding the viewer in your app, but are unhappy with some
aspect of the look or behavior and want to modify it in some way, this section should
point you in the right direction.

Decide which viewer to base your customizations on Copy Section

In order to customize the viewer UI, you will need to modify the existing Android viewer activity.
There are two separate code bases you can start with:

• mupdf-android-viewer
  The main viewer app. This code is difficult to work with, but has the most
  features and pre-renders neighboring pages into a page cache for faster page
  turning performance.

• mupdf-android-viewer-mini
  This is a minimalist viewer which has fewer features but is designed to be
  easy to understand and modify. It does not (currently) have high-resolution
  zooming, and it does not use the swipe gesture to flip pages (it requires the
  user to tap on the side of the screen to flip pages).

If all you want to do is brand the UI with your own colors and icons, you are
welcome to use whichever code base you prefer. However, if you want to do
extensive modifications, we suggest you base your code on the mini viewer.

Check out the chosen project Copy Section

When you have decided which project to base your modifications on, you should check out
the corresponding git repository:

$ git clone git://git.ghostscript.com/mupdf-android-viewer.git
$ git clone git://git.ghostscript.com/mupdf-android-viewer-mini.git

Inside the checked out project you will find two modules: app and lib.
The app module is a file chooser activity that lets the user open files from the external storage.
The lib module is the viewer activity, which provides the com.artifex.mupdf:viewer
package that you're already using.

The lib module is the one you want; ignore everything else in this project.

Copy the viewer library module into your project Copy Section

Copy the 'lib' directory to your project, renaming it to something appropriate.
The following instructions assume you called the directory 'mupdf-lib'.

Don't forget to include the module in the settings.gradle file:

include ':app'
include ':mupdf-lib'
...

You'll also want to change your app's dependencies to now depend on your local
copy rather than the official MuPDF viewer package. In your app build.gradle:

dependencies {
	api project(':mupdf-lib')
	...
}

The lib module depends on the JNI library com.artifex.mupdf:fitz, so do
not remove the Maven repository from your top build.gradle.

Edit the viewer activity Copy Section

If all has gone well, you can now build your project with the local viewer library,
and access the MuPDF viewer activity just as you used to.

You're now free to customize the resources in mupdf-lib/src/main/res and behavior in
mupdf-lib/src/main/java as you desire.

Working on the MuPDF Library Copy Chapter

If you want to work on the library itself, rather than just use it, you will need
to check out the following git repositories.

• mupdf.git
  This repository contains the low-level "fitz" C library and the JNI bindings.

• mupdf-android-fitz.git
  This repository contains an Android project to build the C library and JNI bindings.
  It uses mupdf.git as a Git submodule.

• mupdf-android-viewer.git
  This repository contains the Android viewer library and app.
  It uses mupdf-android-fitz.git as either a Maven artifact or Git submodule.

• mupdf-android-viewer-mini.git
  This repository contains the minimalist Android viewer library and app.
  It uses mupdf-android-fitz.git as either a Maven artifact or Git submodule.

These repositories are set up with Git submodules. If you're a Git expert,
you can clone one of the viewer repositories recursively and get the fitz
and mupdf git repositories all at once.

If you only want to work with one of the viewer repositories, you can clone it
non-recursively and use the Maven artifact for the JNI bindings library and not
worry about the mupdf.git and mupdf-android-fitz.git repositories.

Ext Mupdf Docs Guide Using With Java (`ext/mupdf/docs/guide/using-with-java.md`) Copy Section

Using with Java

There is also a Java library, which uses JNI to provide access to the C
library. The Java classes provide an interface very similar to that available
to Javascript. This Java library also powers the Android versions of MuPDF.

Android Copy Chapter

If you want to build an application for Android, you have several options. You
can base it off one of the existing viewers, or build a new app using the Java
library directly.

See the "Using with Android" section to get started using the MuPDF library for
Android.

Building Copy Chapter