fleuron 0.1.1 → 0.2.0

package/dist/preview.d.ts

@@ -2,7 +2,7 @@
  * A preview, mounted: markdown in, a page on screen.
  *
  * The worker, the module, the postcard buffer and the display structure
- * are what this is built out of, not what it asks a caller to hold.
+ * are what this is built out of, not what it asks a caller to supply.
  * A host that wants them keeps having them, since the client, the
  * protocol, the reader and the painter are all still exported. A host
  * that only wants to see the book says where to put it and hands over
@@ -16,7 +16,7 @@
  * one, and an engine with nothing to do repaints straight away. A
  * host that wants a fixed delay puts one in front of these calls.
  */
-import type { Metadata, Op, Source } from './protocol.js';
+import { type Metadata, type Op, type Sheet, type Source } from './protocol.js';
 import type { Asset, LayoutOutput, Warning } from './wire.js';
 /** How a preview is set up. */
 export interface PreviewOptions {
@@ -70,7 +70,13 @@ export interface PreviewOptions {
      * {@link PreviewOptions.images} supplied.
      */
     asset?: (asset: Asset, index: number) => string | null | undefined;
-    /** Called after every render that reached the screen. */
+    /**
+     * Called after every render that reached the screen, with the
+     * reply the page on screen came from. `output.pages` is that page
+     * alone, not the whole book: `output.bookPages` is the book's own
+     * length, and `output.fonts`/`output.assets`/`output.warnings` are
+     * the whole run's regardless.
+     */
     onRender?: (output: LayoutOutput) => void;
 }
 /**
@@ -87,9 +93,55 @@ export declare class Preview {
     private readonly client;
     private readonly options;
     private readonly faces;
-    /** A blob url per image the host handed over, by its own url. */
+    /**
+     * Every image's own bytes, by url, kept independent of the transfer
+     * that moved the ones sent across the wall: a copy taken before the
+     * op went out, since the buffer handed to the engine is empty on
+     * this side afterwards.
+     */
+    private readonly imageBytes;
+    /**
+     * A blob url per image currently drawn by a held page, by its own
+     * url. Built and revoked by {@link syncAssetCache}: a book with
+     * more images than are ever on screen at once does not keep a blob
+     * open, and its decode, for every one of them.
+     */
     private readonly pixels;
-    private output;
+    /**
+     * The pages this preview currently keeps decoded, by folio. Bounded
+     * to a window around the page on screen rather than the whole
+     * book: what makes a page turn instant is prefetching a neighbour
+     * before it is asked for, not holding every page there is.
+     */
+    private readonly held;
+    /**
+     * The generation `held` was built under. A reply for a different
+     * generation means an edit landed, and drops whatever was held
+     * before inserting: a page from the book before the edit is not
+     * one to paint over it.
+     */
+    private heldGeneration;
+    /**
+     * Pages currently being asked for from the worker, whether the
+     * page turned to or a background prefetch of a neighbour, to the
+     * generation they were asked for under. Asking again for one
+     * already here — including a page left and come back to before its
+     * first request landed — joins it rather than opening a second
+     * request for the same page.
+     *
+     * Keyed on generation, not just the folio, so a fetch left over
+     * from the generation before an edit cannot clear the marker a
+     * fresh fetch for the same folio placed under the new one when the
+     * old one finally lands and finds itself answering a book that no
+     * longer stands.
+     */
+    private readonly pending;
+    /** The whole run's tables and diagnostics, which ride every reply
+     * regardless of which pages it carried. */
+    private fonts;
+    private assets;
+    private bookWarnings;
+    private bookPages;
     private showing;
     private scale;
     private constructor();
@@ -112,8 +164,9 @@ export declare class Preview {
     /** Drops one source and leaves the rest of the book standing. */
     remove(name: string): Promise<void>;
     /**
-     * Names the book. Only the PDF export reads this, so it costs no
-     * layout.
+     * Names the book. The PDF export reads the name, and layout reads
+     * `extra.language`, which chooses the hyphenation patterns, so a
+     * rename alone costs no layout.
      */
     setMetadata(metadata: Metadata): Promise<void>;
     /**
@@ -126,8 +179,13 @@ export declare class Preview {
      * add a file to a book already open.
      */
     edit(name: string, text: string): Promise<void>;
-    /** Sets the author stylesheet, cascading over the built-in one. */
-    setStyle(css: string): Promise<void>;
+    /**
+     * Sets the author styling, cascading over the built-in sheet:
+     * one sheet as CSS text, or the layers a host built its styling
+     * out of, in cascade order. Later sheets win, and a warning names
+     * the sheet its declaration was written in.
+     */
+    setStyle(css: string | Sheet[]): Promise<void>;
     /** Registers a face for the session's life. */
     addFont(bytes: Uint8Array): Promise<void>;
     /**
@@ -138,7 +196,11 @@ export declare class Preview {
      * and a page with nothing where the image was.
      */
     addImage(url: string, bytes: Uint8Array): Promise<void>;
-    /** Lays the book out again and repaints. */
+    /**
+     * Lays the book out again and repaints, asking only for the page on
+     * screen rather than the whole book. An edit drops whatever pages
+     * were held, since the book they came from no longer stands.
+     */
     render(ops?: Op[]): Promise<void>;
     /** How many pages the book set to. */
     get pages(): number;
@@ -155,8 +217,8 @@ export declare class Preview {
     /** Everything the run had to complain about. */
     get warnings(): Warning[];
     /**
-     * The markup on screen, or a page that is not on screen. Empty
-     * before the first render.
+     * The markup on screen, or a page that is not held. Empty before
+     * the first render, and for a page outside the held window.
      */
     svg(number?: number): string;
     /**
@@ -167,19 +229,91 @@ export declare class Preview {
     /** Closes the worker and gives the element back. */
     destroy(): void;
     /**
-     * Keeps a blob url over an image's bytes and hands the same bytes
-     * to the engine.
+     * Keeps a copy of an image's bytes and hands the original to the
+     * engine.
      *
-     * The blob is made before the op is sent, because the bytes move
+     * The copy is taken before the op is sent, because the bytes move
      * across the wall rather than being copied and the buffer is empty
-     * on this side afterwards.
+     * on this side afterwards. No blob is made here: {@link
+     * syncAssetCache} makes one only once a held page actually draws
+     * this url, which for most images in a book-sized manuscript is
+     * never at the same time as every other one.
      */
-    private hold;
+    private keepImage;
+    /**
+     * Fetches one page not already pending, absorbing it and painting
+     * it if it is — or by the time it lands, has become — the page on
+     * screen. Shared by a page turn and a neighbour prefetch, so
+     * whichever of them asks first, the other joins it rather than
+     * opening a second request for the same page: what the request was
+     * *for* is decided when it lands, by whether `showing` still names
+     * it, not by which caller happened to start it.
+     *
+     * Errors are swallowed the way a missing face is elsewhere:
+     * nothing here is awaited by a caller that could catch one, and the
+     * frame simply stays as it was, retried the next time this page is
+     * asked for.
+     */
+    private fetchPage;
+    /**
+     * Warms the pages either side of the one on screen, so a page turn
+     * in either direction paints from what is already held rather than
+     * asking the worker.
+     */
+    private prefetchNeighbours;
+    /**
+     * Folds a reply into the held pages, keyed by folio rather than by
+     * its position in the reply. A reply for a generation `held` was
+     * not built under drops whatever was held before inserting: an
+     * edit is not undone by a page fetched against the book before it.
+     */
+    private absorb;
+    /** Drops whatever is held outside the window around the page on screen. */
+    private prune;
+    /**
+     * Blobs every image a held page draws that does not have one yet,
+     * and revokes every blob no held page draws any more. Run after
+     * {@link prune}, over `held` as a whole rather than page by page:
+     * an asset two held pages share is not revoked for one of them
+     * dropping out while the other still stands.
+     *
+     * A url the host has not supplied bytes for is simply absent from
+     * `imageBytes`, the same gap the painter's asset resolver already
+     * falls back from — this adds no failure mode of its own, only an
+     * eviction of what was already optional.
+     */
+    private syncAssetCache;
     private paint;
+    /**
+     * Copies the selection layer's own text, reconstructed from the
+     * range's own boundaries rather than trusted to the browser's
+     * default serialization across `<text>` siblings — SVG text
+     * elements are not block boxes, and nothing guarantees a browser
+     * puts a line break between two of them the way it would between
+     * paragraphs. This is the pdf.js pattern: the layer under the
+     * pointer draws nothing, and copy answers from what it holds.
+     */
+    private readonly onCopy;
+    /**
+     * The selection's own text, one line's slice per line it touches,
+     * joined in reading order. `null` for a selection with nothing in
+     * it, or one that lies outside this preview altogether — a host's
+     * own text elsewhere on the page is not this preview's to answer
+     * for.
+     */
+    private selectedText;
+    /**
+     * Calls {@link PreviewOptions.onRender}, if the page on screen is
+     * held: built fresh from `held` and the run's tables rather than
+     * threaded through from whichever fetch put it there, so a host
+     * hears about every page that reaches the screen the same way,
+     * cached or just arrived.
+     */
+    private notify;
     private painting;
     /**
-     * Loads the faces the run drew with, from the same files the
-     * engine shaped with.
+     * Loads the faces the held pages draw with, from the same files
+     * the engine shaped with.
      *
      * The bundled face is why this asks the module rather than the
      * network: it is inside the module, and there is no URL to fetch

package/dist/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../src/preview.ts"],"names":[],"mappings":"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"}