postext-folio 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# postext-folio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A 3D book viewer for [postext](https://www.npmjs.com/package/postext) documents and page images.**
+
+`postext-folio` sets a book out on the screen in spreads and lets the reader turn its pages: with the ‹ › buttons, the arrow keys, a swipe, a click on a page, or by taking a page by its edge and dragging it over. Each leaf curls in [three.js](https://threejs.org/) and casts a real shadow on the pages under it. The WebGL canvas draws the book still and turning alike, so a page never changes look when it lands; the DOM pages under it (images or canvases) are the textures' sources and the pages' text alternatives. A right-bound book (Chinese, Japanese, Arabic) lies mirrored and turns leftward. Without WebGL2, or when the reader asks for reduced motion, the spreads simply change.
+
+**Website:** [postext.dev](https://postext.dev/) · **Docs:** [A 3D book](https://postext.dev/en/docs/configuration#a-3d-book-postext-folio)
+
+## Install
+
+```bash
+npm install postext postext-folio three
+```
+
+`postext` and `three` are peer dependencies. Or import everything straight from a CDN:
+
+```js
+import { buildDocument } from 'https://esm.sh/postext';
+import { createFolioFromDocument } from 'https://esm.sh/postext-folio';
+```
+
+## A postext document as a book
+
+```ts
+import { buildDocument } from 'postext';
+import { createFolioFromDocument } from 'postext-folio';
+
+// Postext measures text with the fonts the browser has loaded.
+await document.fonts.load('16px "EB Garamond"');
+
+const doc = buildDocument({ markdown }, {
+  page: { sizePreset: '17x24' },
+  bodyText: { fontFamily: 'EB Garamond' },
+});
+
+const book = createFolioFromDocument(document.getElementById('book')!, doc, {
+  onChange: ({ pages }) => console.log('showing pages', pages),
+});
+
+// After an edit: the same viewer, on the same page.
+book.setDocument(buildDocument({ markdown: edited }, config));
+```
+
+Pages are painted with `renderPageToCanvas` at exactly the device pixels of a page slot, so WebGL shows them texel for pixel, as sharp as the canvas preview, and only around the open spread (`window`, three spreads either side by default). Pages that fall out of that window are freed, so a book of a thousand pages costs the memory of a few. Turning to a far page paints that spread first. Pages a long turn sweeps past show as blank paper while they are in the air.
+
+The container sets the size: the book fills it, with the ‹ › buttons and the page count in the margins. Give it a height. A resize paints the pages again at the new size.
+
+## Page images
+
+`createFolio` takes any pages: image URLs, `<canvas>` or `<img>` elements, `""` for a blank page.
+
+```ts
+import { createFolio } from 'postext-folio';
+
+const book = createFolio(container, {
+  pages: ['p01.webp', 'p02.webp', 'p03.webp', { src: 'p04.webp', alt: 'Plate II' }],
+  firstPageRecto: true, // page 1 opens alone, on the right
+  binding: 'left',
+});
+book.goToPage(2);
+```
+
+## API
+
+<table>
+<thead><tr><th>Export</th><th>What it does</th></tr></thead>
+<tbody>
+<tr><td><code>createFolio(container, options)</code></td><td>The viewer over any pages. Options: <code>pages</code>, <code>firstPageRecto</code> (default true), <code>binding</code> (<code>'left'</code> | <code>'right'</code>), <code>at</code> (page to open on), <code>mode</code> (<code>'auto'</code> | <code>'single'</code> | <code>'double'</code>; auto shows one page at a time below 560 px), <code>paper</code> (blank-page colour), <code>animate</code>, <code>controls</code>, <code>showCount</code> (false keeps the count for screen readers only), <code>labels</code>, <code>onChange</code>, <code>onTarget</code>, <code>onLayout</code>. One page at a time the book is WebGL too: the spine runs along the page's inner edge and the leaf turns over it; a drag towards the spine turns forward, a swipe away from it goes back, a tap turns.</td></tr>
+<tr><td><code>createFolioFromDocument(container, doc, options)</code></td><td>The same over a postext <code>VDTDocument</code>, painted lazily. Spreads, binding and paper come from the document. Adds <code>scale</code>, <code>window</code>, <code>singleInk</code>, <code>pageNegative</code>, <code>alt</code>, and <code>setDocument(doc)</code> on the viewer.</td></tr>
+<tr><td>viewer</td><td><code>goToPage(i, { instant })</code>, <code>goToSpread(i, { instant })</code> (instant opens there without turning), <code>next()</code>, <code>prev()</code>, <code>setPages(pages, opts)</code>, <code>setLabels(labels)</code>, <code>state</code> (<code>{ spread, pages }</code>), <code>element</code>, <code>dispose()</code>.</td></tr>
+<tr><td><code>PageFlipper</code>, <code>canFlip()</code></td><td>The three.js engine alone, for a host that lays out its own spread DOM (as the postext Cookbook does): a canvas over the spread, <code>go(i)</code>, <code>grab</code>/<code>drag</code>/<code>release</code> for the hand, <code>setBook</code>, <code>clear</code>, <code>dispose</code>; <code>{ persistent: true }</code> draws the book at rest too, <code>turnAt</code> sets how far a leaf let go must be to turn over.</td></tr>
+<tr><td><code>spreadsOf(count, firstPageRecto)</code></td><td>The <code>[verso, recto]</code> pairs of a book.</td></tr>
+<tr><td><code>FOLIO_CSS</code></td><td>The viewer's styles (injected once on first use). Restyle with <code>--postext-folio-accent</code> and <code>--postext-folio-nav-border</code> on the container.</td></tr>
+</tbody>
+</table>
+
+The viewer takes the keyboard when focused: ←/→ (mirrored for a right-bound book), Page Up/Down, Home and End. Its labels default to English; pass `labels` (`region`, `prev`, `next`, `count`) to translate them.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { PageFlipper, canFlip } from "./pageFlip";
+export type { PageSource, SpreadSrc } from "./pageFlip";
+export { spreadsOf, spreadOfPage } from "./spreads";
+export type { Spread } from "./spreads";
+export { createFolio } from "./viewer";
+export type { FolioLabels, FolioOptions, FolioPage, FolioState, FolioViewer } from "./viewer";
+export { createFolioFromDocument, firstPageIsRecto } from "./postext";
+export type { FolioDocumentOptions, FolioDocumentViewer } from "./postext";
+export { FOLIO_CSS } from "./styles";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACpD,YAAY,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC9F,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { PageFlipper, canFlip } from "./pageFlip";
+export { spreadsOf, spreadOfPage } from "./spreads";
+export { createFolio } from "./viewer";
+export { createFolioFromDocument, firstPageIsRecto } from "./postext";
+export { FOLIO_CSS } from "./styles";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAEtE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC"}

package/dist/pageFlip.d.ts

@@ -0,0 +1,137 @@
+/** A page: an image URL, or a canvas or a decoded image to draw; "" is a
+ *  blank page (drawn as paper), null no page at all. */
+export type PageSource = string | HTMLCanvasElement | HTMLImageElement | null;
+/** A spread: [verso, recto]. */
+export type SpreadSrc = [PageSource, PageSource];
+/**
+ * Turns the pages of the light table's DOM spread. The book is a stack of
+ * leaves: leaf k has spread k's recto on its front and spread k + 1's verso
+ * on its back. `go(n)` sends every leaf before spread n to the left and
+ * the rest to the right; each turns on its own, following the one before
+ * it at a short remove, so several pages can be in the air at once. At
+ * rest the canvas is transparent and the <img> pages show; while leaves
+ * move it draws the spread, lit, with the lifted leaves' shadows.
+ *
+ * The book is modelled bound on the left. A right-bound one is the same
+ * book seen in a mirror (the DOM spread's `dir="rtl"`): the stage is
+ * mirrored, so the verso lies on the right and the leaves turn from left
+ * to right, while the page images, the pointer and the light are mirrored
+ * back to read as they are on the desk.
+ */
+export declare class PageFlipper {
+    private canvas;
+    private spread;
+    private book;
+    private onSettle;
+    /** The reader's hand turned the book to another spread. */
+    private onTarget;
+    private renderer;
+    private scene;
+    private camera;
+    private left;
+    private right;
+    private desk;
+    /** Everything on the desk, in the book's own coordinates (mirrored for a
+     *  right-bound book). */
+    private stage;
+    /** 1 for a left-bound book, −1 for a right-bound one. */
+    private sign;
+    /** Towards the light, in the book's coordinates. */
+    private light;
+    private shadowScene;
+    private shadowCamera;
+    private shadowTarget;
+    private casterMaterial;
+    private leaves;
+    private loader;
+    private textures;
+    private ready;
+    private W;
+    private H;
+    /** Leaf k lies on the left. */
+    private turned;
+    private turns;
+    private target;
+    private raf;
+    private starting;
+    private disposed;
+    /** The spread last reported settled (the one the DOM shows). */
+    private reported;
+    private persistent;
+    private turnAt;
+    /** A redraw of the book at rest is queued. */
+    private still;
+    constructor(canvas: HTMLCanvasElement, spread: HTMLElement, book: SpreadSrc[], at: number, onSettle: (index: number) => void, 
+    /** The reader's hand turned the book to another spread. */
+    onTarget: (index: number) => void, 
+    /** The edge the book is bound on. */
+    binding?: "left" | "right", 
+    /** `persistent`: the canvas draws the book at rest too (the DOM pages
+     *  are hidden by the host and serve only as texture sources and text
+     *  alternatives), so a page looks the same lying still and turning. */
+    /** `turnAt`: how far through its turn (0 … 1) a leaf let go of turns
+     *  over rather than falling back. Default 0.5. */
+    { persistent, turnAt }?: {
+        persistent?: boolean;
+        turnAt?: number;
+    });
+    /** Fits the camera so the z = 0 plane maps onto the DOM spread 1:1.
+     *  Sizes are read unrounded and the drawing buffer covers the canvas's
+     *  device pixels exactly, so a page lying flat is drawn texel for pixel,
+     *  as the DOM shows it. */
+    private layout;
+    private flat;
+    /** The colour of the book's paper (0 … 1), for its blank pages. */
+    setPaper(r: number, g: number, b: number): void;
+    /** Starts loading the pages of these spreads as textures. */
+    preload(indexes: number[]): void;
+    private texture;
+    /**
+     * Replaces the book's pages (after a relayout, or once more pages are
+     * painted), keeping the open spread when `at` is left out. Leaves at
+     * rest take their new pages at once; textures no page uses any more are
+     * freed. A book of another length starts afresh at `at`.
+     */
+    setBook(book: SpreadSrc[], at?: number): void;
+    private assign;
+    private leaf;
+    /** Turns the pages until spread `index` lies open. */
+    go(index: number): void;
+    /** The spread open when no leaf is in the air. */
+    private settledAt;
+    /** A new turn by the virtual hand, from the bottom corner (or the
+     *  point clicked) over to its mirror image. */
+    private lift;
+    private frame;
+    private settle;
+    /** The pointer on the z = 0 plane, in the book's coordinates (x
+     *  mirrored for a right-bound book). */
+    private toWorld;
+    /** Takes hold of the page under the pointer; false when there is none
+     *  to turn (or pages are already in the air). */
+    grab(event: {
+        clientX: number;
+        clientY: number;
+    }): boolean;
+    /** Carries the held point to the pointer. */
+    drag(event: {
+        clientX: number;
+        clientY: number;
+    }): void;
+    /** Lets go. A click turns the page over from where it was taken; a drag
+     *  carries on over if the page is past halfway or thrown that way, and
+     *  falls back otherwise. */
+    release(click?: boolean): void;
+    private draw;
+    /** Back to a transparent canvas (the DOM spread shows), unless leaves
+     *  are moving again. A persistent book is drawn at rest instead. */
+    clear(): void;
+    /** Draws the book at rest again (a page painted, the box resized) on the
+     *  next frame; leaves in the air are drawn by their own frames. Only for
+     *  a persistent book: the other one shows the DOM at rest. */
+    redraw(): void;
+    dispose(): void;
+}
+/** WebGL is there and the reader has not asked for less motion. */
+export declare function canFlip(): boolean;
+//# sourceMappingURL=pageFlip.d.ts.map

package/dist/pageFlip.d.ts.map

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