@zinejs/core 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,8 @@ Framework-agnostic flipbook engine: turn images or PDFs into a page-flipping boo
 npm install @zinejs/core
 ```
 
+Also ships a **UMD** build at `dist/index.umd.cjs` (global `ZineJS`) for CDN / `<script>` hosts. The ESM build code-splits the CSS and WebGL2 renderers; the UMD build inlines both so a single script is enough.
+
 ## Image book
 
 ```js
@@ -47,11 +49,12 @@ new Zine(container, {
   source,                    // ImageSource | PdfSource (required)
   direction: 'ltr',          // 'ltr' | 'rtl'
   spreadMode: 'cover',       // 'double' | 'single' | 'cover' (lone first page) | 'book' (lone first & last)
+  curl: 'cone',              // WebGL2 only: 'cone' | 'roll' | 'leaf' | 'flick' | 'silk' | 'simple'
   frontCover: 'front.jpg',   // optional image prepended as a lone front cover
   backCover: 'back.jpg',     // optional image appended as a lone back cover
   pages: { 4: 'ad.jpg' },    // optional: replace source pages with images (0-based; -1 = last)
   startPage: 0,
-  flipDuration: 800,         // ms
+  flipDuration: 800,         // ms (spread timing; a lone page stretches it and eases out)
   singlePageThreshold: 640,  // px: below this, show one page at a time
   clickToFlip: 'edge',       // 'edge' | 'half' | 'off'
   zoom: { enabled: true, max: 4, wheel: true, doubleClick: [1, 2, 4] },
@@ -59,6 +62,7 @@ new Zine(container, {
 });
 ```
 
+See the [root README](../../README.md#curl-models) for what each curl model does.
 ## Methods & events
 
 ```js

package/dist/geometry/curls/cone.d.ts

@@ -0,0 +1,17 @@
+import { type PageMesh } from './mesh';
+import type { CurlAnchor } from './types';
+/**
+ * Natural conical page curl — the Xerox PARC / iBooks model.
+ *
+ * The leaf wraps an imaginary right circular cone whose apex rides the spine and
+ * whose opening angle θ breathes over the turn (Hong, Card & Chen, 2004). A corner
+ * grab yields a diagonal cone; a mid-edge grab blends toward a cylinder so the
+ * free edge lifts as one. The curled sheet then rotates about the spine and settles
+ * flat on the far side. Arc length from the apex is preserved, so the paper never
+ * stretches — the motion reads as stiff, premium stock rather than cloth.
+ *
+ * On a full-width lone page (`anchor.fill`) the hinge is the container edge with no
+ * facing half to land on: the cone softens, the flop is delayed so the peel stays
+ * over the page longer, and the renderer dissolves the sheet as it finishes.
+ */
+export declare function deformCone(mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor): void;

package/dist/geometry/curls/flick.d.ts

@@ -0,0 +1,20 @@
+import { type PageMesh } from './mesh';
+import type { CurlAnchor } from './types';
+/**
+ * Inertial follow-through page flick.
+ *
+ * The leaf is a cantilever clamped at the spine and driven through a rotation
+ * ρ(t) = πt. Paper inertia (the Euler force, ∝ −ρ̈) bends the sheet opposite the
+ * angular acceleration with a first-mode-like profile — zero curvature at the
+ * clamped spine, maximal at the free edge. Under an eased turn the acceleration
+ * changes sign at mid-flight, so the free edge trails while the turn winds up,
+ * swings through vertical, then overtakes and settles as the turn slows: the
+ * follow-through/overlapping-action principle, grounded in base-rotated
+ * cantilever dynamics. Tangent angles are integrated along the width, so the
+ * sheet never stretches, and the curvature direction reversing over the turn is
+ * what none of the wrap-style curls do.
+ *
+ * Rows far from the grabbed corner lag slightly more than the driven row, so a
+ * corner grab pulls a soft living diagonal across the sheet.
+ */
+export declare function deformFlick(mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor): void;

package/dist/geometry/curls/leaf.d.ts

@@ -0,0 +1,19 @@
+import { type PageMesh } from './mesh';
+import type { CurlAnchor } from './types';
+/**
+ * Traveling smooth-curvature leaf curl.
+ *
+ * Inspired by rolling-cylinder page curls and modern developable-surface book
+ * simulations, but with a compact raised-cosine curvature wave instead of a
+ * constant-radius cylinder. The sheet has three regions:
+ *
+ *  1. untouched paper before the wave,
+ *  2. an isometric bend whose curvature smoothly rises and falls,
+ *  3. a flat, reflected flap after the wave.
+ *
+ * The wave travels from the free edge to just beyond the spine while its width grows
+ * and collapses. Integrating a unit tangent preserves material length exactly; straight
+ * ruling lines preserve distance along the curl axis. Curvature reaches zero at both
+ * seams, eliminating the hard crease shared by circular/fold models.
+ */
+export declare function deformLeaf(mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor): void;

package/dist/geometry/curls/silk.d.ts

@@ -0,0 +1,27 @@
+import { type PageMesh } from './mesh';
+import type { CurlAnchor } from './types';
+/**
+ * Silk — hand-turned S-curve page.
+ *
+ * This is not a traveling contact wave (`leaf`), not a cone wrap (`cone`), not a
+ * cylinder roll (`roll`), and not a single-mode inertial cantilever (`flick`).
+ *
+ * Real paper turned by hand takes an S-shaped cross-section: a main bend through
+ * the near half and a reverse bend through the far half (the flap over the
+ * fingers). The sheet is a developable strip clamped at the spine and driven
+ * through a base rotation ρ(t) = πt. Along the width the tangent is:
+ *
+ *   θ(u) = ρ + env·S·sin(2πu) + peel(t)·u²
+ *
+ * where:
+ *  - sin(2πu) is a full-period S (zero net at spine and free edge, opposite
+ *    bends in the two halves) — a true inflection that none of the other
+ *    models produce mid-turn,
+ *  - u² is an early peel lead that lifts the free edge first, then releases.
+ *
+ * env = sin(πt) holds the S through the middle and forces exact flat rests.
+ * Rows far from the tap lag so a corner grab draws a living diagonal.
+ * Arc length is integrated with the unit tangent (trapezoid per grid cell), so
+ * the paper never stretches.
+ */
+export declare function deformSilk(mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor): void;

package/dist/geometry/curls/simple.d.ts

@@ -5,11 +5,3 @@ import { type PageMesh } from './mesh';
  * cylinder bend; GPU-rendered here with the shared perspective so it reads like the CSS fold.
  */
 export declare function deformSimple(mesh: PageMesh, W: number, H: number, t: number): void;
-/**
- * Bent page flip: the single-page (fill) form for spine curls whose spread shape assumes a
- * centered spine or a neighbour (roll). The leaf rotates about its spine edge (0→π) like the
- * flat turn, but the sheet also curves into a shallow arc that peaks mid-flip and flattens at
- * both ends, so the paper visibly bends as it turns instead of staying rigid. Reduces to the
- * flat turn when the bend is zero; arc length across the width is preserved.
- */
-export declare function deformBentFlip(mesh: PageMesh, W: number, H: number, t: number): void;

package/dist/geometry/curls/types.d.ts

@@ -7,16 +7,19 @@ import type { PageMesh } from './mesh';
 /** Where a corner-anchored curl folds from: y in [0,1], 0 = top edge, 1 = bottom edge. */
 export interface CurlAnchor {
     y: number;
+    /**
+     * Full-width lone page (single-page mode). The leaf hinges at the container edge and
+     * has no facing half to land on — deforms may soften and delay the flop so the curl
+     * reads naturally before the renderer dissolves the sheet.
+     */
+    fill?: boolean;
 }
 export type CurlDeform = (mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor) => void;
 export interface CurlModel {
     readonly deform: CurlDeform;
-    /** Single-page (fill) variant for curls whose spread form assumes a centered spine or a
-     *  neighbouring page. Used in fill mode when present; otherwise `deform` is used as-is. */
-    readonly deformFill?: CurlDeform;
     /** True when the fold originates at a corner (`anchor.y`) rather than the whole edge. */
     readonly anchored: boolean;
 }
-export type CurlType = 'roll' | 'simple' | 'fold' | 'peel';
+export type CurlType = 'roll' | 'cone' | 'leaf' | 'flick' | 'silk' | 'simple';
 export declare const CURL_TYPES: CurlType[];
 export declare const DEFAULT_CURL: CurlType;