@zinejs/core 0.8.2 → 0.9.1

package/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,8 +1,10 @@
 # @zinejs/core
 
-Framework-agnostic flipbook engine: turn images or PDFs into a page-flipping book. Zero dependencies. Ships a **CSS renderer** (works everywhere, no GPU) and a **WebGL2 renderer** (page-curl, auto-selected where a GPU is available), behind one API — you never choose a renderer.
+Framework-agnostic flipbook engine for the web. Turn a list of images (or a PDF, via [`@zinejs/pdf`](https://www.npmjs.com/package/@zinejs/pdf)) into a page-flip book. Zero dependencies.
 
-> Pre-1.0 and under active development. Licensed **PolyForm Noncommercial 1.0.0** (free for non-commercial use).
+Where WebGL2 is available it uses the GPU renderer (page-curl, lighting). Elsewhere it falls back to CSS on its own.
+
+> **Docs, live demos, and guides:** [zinejs.com/docs](https://zinejs.com/docs/) · [examples](https://zinejs.com/examples)
 
 ## Install
 
@@ -10,79 +12,55 @@ 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.js` (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.
+Also ships a **UMD** build at `dist/index.umd.js` (global `ZineJS`) for [CDN / `<script>` hosts](https://zinejs.com/examples/html-cdn). The ESM build code-splits the CSS and WebGL2 renderers (and the toolbar); the UMD build inlines the renderers so a single script is enough.
 
 ## Image book
 
 ```js
-import { Zine, ImageSource } from '@zinejs/core';
+import { Zine, ImageSource } from '@zinejs/core'
 
-const book = new Zine(document.getElementById('book'), {
+new Zine(document.getElementById('book'), {
   source: new ImageSource([
     'page-01.png',
     'page-02.png',
     'page-03.png',
     'page-04.png',
   ]),
-});
+})
 ```
 
-Give the container a size (e.g. `#book { width: 900px; height: 560px; }`). Flip by dragging a corner or clicking near an edge; zoom with double-click, Ctrl/⌘+wheel, or pinch.
+Drag a corner or click near an edge to turn. Double-click, pinch, or Ctrl/Cmd+wheel to zoom.
 
 ## PDF book
 
-Install the plugin (see [`@zinejs/pdf`](https://www.npmjs.com/package/@zinejs/pdf)):
+Install [`@zinejs/pdf`](https://www.npmjs.com/package/@zinejs/pdf) as well:
 
 ```js
-import { Zine } from '@zinejs/core';
-import { PdfSource } from '@zinejs/pdf';
+import { Zine } from '@zinejs/core'
+import { PdfSource } from '@zinejs/pdf'
 
 new Zine(document.getElementById('book'), {
   source: new PdfSource('document.pdf'),
-});
-```
-
-## Options
-
-```ts
-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 (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] },
-  renderer: 'auto',          // 'auto' | 'css' | 'webgl2' | a custom Renderer
-  controls: true,            // built-in toolbar; false for none, or { position, items, … }
-});
+})
 ```
 
-## Controls
-
-A toolbar (paging, page number, zoom, search, share, a `⋮` menu with download, and fullscreen)
-is rendered below the book by default. Turn it off with `controls: false`, move it with
-`controls: { position: 'top' }`, float it over the book with `controls: { docked: false }`, or
-choose the buttons with `controls: { items: [...] }`. Register your own with `defineControl`.
+See [PdfSource](https://zinejs.com/docs) for worker setup, `legacy`, and CDN.
 
-The toolbar and its icons load as a separate chunk, so a book with `controls: false` never
-downloads them. See the [full docs](https://github.com/awecode/zinejs#controls).
+## Options and API
 
-See the [root README](../../README.md#curl-models) for what each curl model does.
-## Methods & events
+Only `source` is required. Common options: `spreadMode`, `curl` (`'cone'` or `'simple'` by name; other curls from `@zinejs/core/curls`), `zoom`, `controls`, `renderer` (`'auto'` prefers GPU). A JSON Schema is at `@zinejs/core/options.schema.json`.
 
 ```js
-book.flipNext(); book.flipPrev(); book.flipTo(12);
-book.getPage(); book.getPageCount();
-book.setZoom(2); book.resetZoom();
-book.update(); book.destroy();
-
-book.on('ready' | 'pageChanged' | 'flipStart' | 'flipEnd' | 'zoomChanged' | 'sourceError' | 'rendererFallback', handler);
+const zine = new Zine(el, {
+  source,
+  spreadMode: 'cover',
+  zoom: { max: 4 },
+})
+
+await zine.ready
+zine.on('pageChanged', ({ page }) => console.log(page))
+zine.flipNext()
+zine.flipTo(12)
 ```
 
-A JSON Schema for the options is published at `@zinejs/core/options.schema.json`.
+The toolbar loads as a separate chunk, so `controls: false` never downloads it. Full options, methods, events, and curl models: [zinejs.com/docs](https://zinejs.com/docs/) and the [GitHub README](https://github.com/awecode/zinejs#readme).

package/dist/{bundled-Cp43MIt0.js → bundled-ESapkNsS.js}

@@ -25,45 +25,45 @@ function n(e) {
 }
 //#endregion
 //#region src/geometry/curls/cone.ts
-var r = 30 * Math.PI / 180, i = 44 * Math.PI / 180, a = 1.35, o = .7, s = 1.85, c = 1.15, l = .42, u = 1.08;
-function d(e, t, d, f, p) {
-	let m = e.cols + 1, h = e.rows + 1, g = e.positions, _ = !!p.fill, v = Math.sin(Math.PI * f) ** .85, y = _ ? i : r, b = Math.PI / 2 - v * (Math.PI / 2 - y), x = Math.sin(b), S = Math.cos(b), C = 1 / Math.max(x, 1e-6), w = _ ? s : a, T = d * (w + ((_ ? c : o) - w) * v), E = (p.y - .5) * 2, D = E >= 0, O = Math.min(1, Math.abs(E) / l), k = 1 - O, A = D ? d + T : -T, j = Math.hypot(t, .5 * d - A), M = Math.max(j * x, t / Math.PI), N = _ ? f ** +u : f, P = -Math.PI * N, F = Math.cos(P), I = Math.sin(P);
-	if (v < 1e-4) {
-		for (let n = 0; n < h; n++) {
-			let r = n / e.rows * d;
-			for (let i = 0; i < m; i++) {
-				let a = i / e.cols * t, o = (n * m + i) * 3;
-				g[o] = a * F, g[o + 1] = r, g[o + 2] = -a * I;
+var r = 30 * Math.PI / 180, i = 1.35, a = .7, o = .42, s = .84, c = .88;
+function l(e, t, l, u, d) {
+	let f = e.cols + 1, p = e.rows + 1, m = e.positions, h = u >= s ? 1 : u / s, g = Math.sin(Math.PI * h), _ = Math.PI / 2 - g * (Math.PI / 2 - r), v = Math.sin(_), y = Math.cos(_), b = 1 / Math.max(v, 1e-6), x = l * (i + (a - i) * g), S = (d.y - .5) * 2, C = S >= 0, w = Math.min(1, Math.abs(S) / o), T = 1 - w, E = C ? l + x : -x, D = Math.hypot(t, .5 * l - E), O = Math.max(D * v, t / Math.PI), k = Math.min(1, u / c), A = -Math.PI * k, j = Math.cos(A), M = Math.sin(A);
+	if (g < 1e-4) {
+		for (let n = 0; n < p; n++) {
+			let r = n / e.rows * l;
+			for (let i = 0; i < f; i++) {
+				let a = i / e.cols * t, o = (n * f + i) * 3;
+				m[o] = a * j, m[o + 1] = r, m[o + 2] = -a * M;
 			}
 		}
 		n(e);
 		return;
 	}
-	for (let n = 0; n < h; n++) {
-		let r = n / e.rows * d;
-		for (let i = 0; i < m; i++) {
+	for (let n = 0; n < p; n++) {
+		let r = n / e.rows * l;
+		for (let i = 0; i < f; i++) {
 			let a = i / e.cols * t, o = a, s = r, c = 0;
-			if (O > 1e-5) {
-				let e = D ? d - r : r, t = -T, n = Math.hypot(a, e - t);
+			if (w > 1e-5) {
+				let e = C ? l - r : r, t = -x, n = Math.hypot(a, e - t);
 				if (n > 1e-8) {
-					let e = n * x, r = Math.asin(Math.min(1, Math.max(0, a / n))) * C, i = 1 - Math.cos(r), l = n + t - e * i * x;
-					o = e * Math.sin(r), s = D ? d - l : l, c = e * i * S;
+					let e = n * v, r = Math.asin(Math.min(1, Math.max(0, a / n))) * b, i = 1 - Math.cos(r), u = n + t - e * i * v;
+					o = e * Math.sin(r), s = C ? l - u : u, c = e * i * y;
 				}
 			}
-			let l = o, u = s, f = c;
-			if (k > 1e-5) {
-				let e = a / M, t = M * Math.sin(e), n = M * (1 - Math.cos(e));
-				l = O * o + k * t, u = O * s + k * r, f = O * c + k * n;
+			let u = o, d = s, p = c;
+			if (T > 1e-5) {
+				let e = a / O, t = O * Math.sin(e), n = O * (1 - Math.cos(e));
+				u = w * o + T * t, d = w * s + T * r, p = w * c + T * n;
 			}
-			let p = (n * m + i) * 3;
-			g[p] = l * F + f * I, g[p + 1] = u, g[p + 2] = -l * I + f * F;
+			let h = (n * f + i) * 3;
+			m[h] = u * j + p * M, m[h + 1] = d, m[h + 2] = -u * M + p * j;
 		}
 	}
 	n(e);
 }
 //#endregion
 //#region src/geometry/curls/simple.ts
-function f(e, t, r, i) {
+function u(e, t, r, i) {
 	let a = e.cols + 1, o = e.rows + 1, s = e.positions, c = i * Math.PI, l = Math.cos(c), u = Math.sin(c);
 	for (let n = 0; n < a; n++) {
 		let i = n / e.cols * t, c = i * l, d = i * u;
@@ -76,25 +76,25 @@ function f(e, t, r, i) {
 }
 //#endregion
 //#region src/geometry/curls/bundled.ts
-var p = {
-	deform: d,
+var d = {
+	deform: l,
 	anchored: !0
-}, m = {
-	deform: f,
+}, f = {
+	deform: u,
 	anchored: !1,
 	flat: !0,
 	gloss: !1
-}, h = {
-	cone: p,
-	simple: m
+}, p = {
+	cone: d,
+	simple: f
 };
-function g(t) {
+function m(t) {
 	if (typeof t != "string") return t;
-	let n = h[t];
+	let n = p[t];
 	if (n) return n;
 	throw e.includes(t) ? Error(`Zine: the '${t}' curl is not bundled. Import it and pass the model: import { ${t} } from '@zinejs/core/curls'  →  curl: ${t}`) : Error(`Zine: unknown curl ${JSON.stringify(t)}.`);
 }
 //#endregion
-export { n as a, m as i, p as n, t as o, g as r, h as t };
+export { n as a, f as i, d as n, t as o, m as r, p as t };
 
-//# sourceMappingURL=bundled-Cp43MIt0.js.map
+//# sourceMappingURL=bundled-ESapkNsS.js.map

package/dist/bundled-ESapkNsS.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled-ESapkNsS.js","names":[],"sources":["../src/geometry/curls/mesh.ts","../src/geometry/curls/cone.ts","../src/geometry/curls/simple.ts","../src/geometry/curls/bundled.ts"],"sourcesContent":["/**\n * Shared grid mesh + normal utilities for the page-curl models.\n *\n * A curl model fills `positions`/`normals` in place each frame; UVs are static grid\n * coordinates (no texture swimming). All models bend the same (cols+1)×(rows+1) grid.\n */\n\nexport interface PageMesh {\n  readonly cols: number;\n  readonly rows: number;\n  /** ((cols+1)*(rows+1))*2 — static grid UVs (u across width, v down height). */\n  readonly uvs: Float32Array;\n  /** *3 — deformed positions, updated by the curl model. */\n  readonly positions: Float32Array;\n  /** *3 — per-vertex normals, updated by the curl model. */\n  readonly normals: Float32Array;\n}\n\n/** Allocate a (cols+1)×(rows+1) grid mesh with static UVs (positions/normals filled by a curl). */\nexport function createPageMesh(cols: number, rows: number): PageMesh {\n  const nx = cols + 1;\n  const ny = rows + 1;\n  const count = nx * ny;\n  const uvs = new Float32Array(count * 2);\n  for (let j = 0; j < ny; j++) {\n    for (let i = 0; i < nx; i++) {\n      const k = j * nx + i;\n      uvs[k * 2] = i / cols;\n      uvs[k * 2 + 1] = j / rows;\n    }\n  }\n  return {\n    cols,\n    rows,\n    uvs,\n    positions: new Float32Array(count * 3),\n    normals: new Float32Array(count * 3),\n  };\n}\n\n/** Per-vertex normals from central differences of the deformed grid (front = +z when flat). */\nexport function computeNormals(mesh: PageMesh): void {\n  const nx = mesh.cols + 1;\n  const ny = mesh.rows + 1;\n  const pos = mesh.positions;\n  const nrm = mesh.normals;\n\n  for (let j = 0; j < ny; j++) {\n    for (let i = 0; i < nx; i++) {\n      const iPrev = i > 0 ? i - 1 : i;\n      const iNext = i < nx - 1 ? i + 1 : i;\n      const jPrev = j > 0 ? j - 1 : j;\n      const jNext = j < ny - 1 ? j + 1 : j;\n\n      const a = (j * nx + iNext) * 3;\n      const b = (j * nx + iPrev) * 3;\n      const c = (jNext * nx + i) * 3;\n      const e = (jPrev * nx + i) * 3;\n\n      const tuX = pos[a]! - pos[b]!;\n      const tuY = pos[a + 1]! - pos[b + 1]!;\n      const tuZ = pos[a + 2]! - pos[b + 2]!;\n      const tvX = pos[c]! - pos[e]!;\n      const tvY = pos[c + 1]! - pos[e + 1]!;\n      const tvZ = pos[c + 2]! - pos[e + 2]!;\n\n      let nx0 = tuY * tvZ - tuZ * tvY;\n      let ny0 = tuZ * tvX - tuX * tvZ;\n      let nz0 = tuX * tvY - tuY * tvX;\n      const l = Math.hypot(nx0, ny0, nz0) || 1;\n      nx0 /= l;\n      ny0 /= l;\n      nz0 /= l;\n\n      const k = (j * nx + i) * 3;\n      nrm[k] = nx0;\n      nrm[k + 1] = ny0;\n      nrm[k + 2] = nz0;\n    }\n  }\n}\n","import { computeNormals, type PageMesh } from './mesh';\nimport type { CurlAnchor } from './types';\n\n/**\n * Cone angle at peak curl. π/2 is flat; smaller values wind the sheet tighter.\n * ~30° gives a soft, paper-like ridge without self-intersection on typical page\n * aspect ratios (Hong / Nuon / Project Austin all land in the 18–35° band).\n */\nconst THETA_MIN = (30 * Math.PI) / 180;\n\n/**\n * How far past the page the cone apex sits, as a fraction of height, at rest.\n * Closer mid-turn sharpens the diagonal; farther reads more cylindrical.\n * Kept moderately distant so the sheet stays page-like without cloth-y sliding.\n */\nconst APEX_REST = 1.35;\nconst APEX_PEAK = 0.7;\n\n/**\n * Above this |anchor.y − 0.5| the deform is a pure cone; at the mid-edge it\n * blends fully to a cylinder (Project Austin’s conicContribution).\n */\nconst CORNER_PURE = 0.42;\n\n/**\n * Curl envelope ends before t=1 so the last stretch is a flat spine settle.\n * Holding sin(πt) curl into the 0.9s left a tall residual ridge that deflated\n * while the free edge was already nearly home — that read as a rebound bounce.\n */\nconst CURL_END = 0.84;\n\n/**\n * Spine rotation reaches ±π before t=1 and holds. Flip easing decelerates hard into\n * the end (a near-still tail after PAGE_LEAD); finishing the flop early keeps that\n * tail from slowly dropping the leaf into place (the settle/rebound feel).\n * Same schedule for lone pages: the dissolve then covers a still, landed sheet\n * rather than a late whip off the hinge.\n */\nconst RHO_END = 0.88;\n\n/**\n * Natural conical page curl — the Xerox PARC / iBooks model.\n *\n * The leaf wraps an imaginary right circular cone whose apex rides the spine and\n * whose opening angle θ breathes over the turn (Hong, Card & Chen, 2004). A corner\n * grab yields a diagonal cone; a mid-edge grab blends toward a cylinder so the\n * free edge lifts as one. The curled sheet then rotates about the spine and settles\n * flat on the far side. Arc length from the apex is preserved, so the paper never\n * stretches — the motion reads as stiff, premium stock rather than cloth.\n *\n * Lone pages (`anchor.fill`) use the same cone and flop as a spread half; the\n * renderer hinges at the container edge and dissolves the leaf as it finishes.\n * Softening or delaying the fill path made single-page turns read as a peel-fade\n * instead of a page turn.\n */\nexport function deformCone(mesh: PageMesh, W: number, H: number, t: number, anchor: CurlAnchor): void {\n  const nx = mesh.cols + 1;\n  const ny = mesh.rows + 1;\n  const pos = mesh.positions;\n\n  // Curl envelope: 0 at the ends (flat), 1 near mid-turn. Span ends at CURL_END\n  // so the ridge is gone before the spine holds the landed pose through the ease tail.\n  const curlT = t >= CURL_END ? 1 : t / CURL_END;\n  const curl = Math.sin(Math.PI * curlT);\n\n  // θ: π/2 (identity) → THETA_MIN (pronounced curl) → π/2.\n  const theta = Math.PI / 2 - curl * (Math.PI / 2 - THETA_MIN);\n  const sinTheta = Math.sin(theta);\n  const cosTheta = Math.cos(theta);\n  const invSinTheta = 1 / Math.max(sinTheta, 1e-6);\n\n  // Apex distance: pulled in as the curl develops for a tighter diagonal.\n  const apexDist = H * (APEX_REST + (APEX_PEAK - APEX_REST) * curl);\n\n  // Corner bias: −1 = top edge, +1 = bottom. Near 0 → cylinder blend.\n  const bias = (anchor.y - 0.5) * 2;\n  const fromBottom = bias >= 0;\n  const absBias = Math.abs(bias);\n  let conic = Math.min(1, absBias / CORNER_PURE);\n  const cylWeight = 1 - conic;\n\n  // Cylinder radius matched to the cone’s free-edge cross-section (Austin), so\n  // the blend is continuous as the grab slides from corner to mid-edge.\n  // Apex sits past the *leading* edge (below for a bottom grab, above for top).\n  const AyRef = fromBottom ? H + apexDist : -apexDist;\n  const cylR = Math.hypot(W, 0.5 * H - AyRef);\n  const cylRadius = Math.max(cylR * sinTheta, W / Math.PI);\n\n  // Spine rotation: concurrent with the cone so the page flops while it curls.\n  // Same x–z convention as `roll` (ρ: 0 → −π). Finish by RHO_END and hold so the\n  // ease-out / dissolve tail stays still (spread land or lone fade alike).\n  // `anchor.fill` is a renderer concern; geometry matches a spread half.\n  const rhoT = Math.min(1, t / RHO_END);\n  const rho = -Math.PI * rhoT;\n  const cosR = Math.cos(rho);\n  const sinR = Math.sin(rho);\n\n  // Near the rests the cone is the identity plane. A finite-radius cylinder blend\n  // still carries a tiny residual arc — skip it and rotate the flat sheet.\n  if (curl < 1e-4) {\n    for (let j = 0; j < ny; j++) {\n      const y = (j / mesh.rows) * H;\n      for (let i = 0; i < nx; i++) {\n        const x0 = (i / mesh.cols) * W;\n        const k = (j * nx + i) * 3;\n        pos[k] = x0 * cosR;\n        pos[k + 1] = y;\n        pos[k + 2] = -x0 * sinR;\n      }\n    }\n    computeNormals(mesh);\n    return;\n  }\n\n  for (let j = 0; j < ny; j++) {\n    const y0 = (j / mesh.rows) * H;\n    for (let i = 0; i < nx; i++) {\n      const x0 = (i / mesh.cols) * W;\n\n      let cx = x0;\n      let cy = y0;\n      let cz = 0;\n\n      if (conic > 1e-5) {\n        // Canonical cone: apex above the page (A < 0) makes the *near* edge lead.\n        // In our y-down leaf, that means the top. For a bottom grab we flip into\n        // that space, deform, then flip back — one code path for both corners.\n        const yIn = fromBottom ? H - y0 : y0;\n        const A = -apexDist;\n        const R = Math.hypot(x0, yIn - A);\n        if (R > 1e-8) {\n          const r = R * sinTheta;\n          const beta = Math.asin(Math.min(1, Math.max(0, x0 / R))) * invSinTheta;\n          const oneCos = 1 - Math.cos(beta);\n          const yCone = R + A - r * oneCos * sinTheta;\n          cx = r * Math.sin(beta);\n          cy = fromBottom ? H - yCone : yCone;\n          cz = r * oneCos * cosTheta;\n        }\n      }\n\n      let bx = cx;\n      let by = cy;\n      let bz = cz;\n\n      if (cylWeight > 1e-5) {\n        const beta = x0 / cylRadius;\n        const sx = cylRadius * Math.sin(beta);\n        const sz = cylRadius * (1 - Math.cos(beta));\n        bx = conic * cx + cylWeight * sx;\n        by = conic * cy + cylWeight * y0;\n        bz = conic * cz + cylWeight * sz;\n      }\n\n      const k = (j * nx + i) * 3;\n      pos[k] = bx * cosR + bz * sinR;\n      pos[k + 1] = by;\n      pos[k + 2] = -bx * sinR + bz * cosR;\n    }\n  }\n\n  computeNormals(mesh);\n}\n","import { computeNormals, type PageMesh } from './mesh';\n\n/**\n * Flat page turn — the plainest flip, matching the CSS renderer. The leaf stays a rigid\n * flat sheet and rotates around the spine (angle 0→π), going edge-on at the midpoint. No\n * cylinder bend; GPU-rendered here with the shared perspective so it reads like the CSS fold.\n */\nexport function deformSimple(mesh: PageMesh, W: number, H: number, t: number): void {\n  const nx = mesh.cols + 1;\n  const ny = mesh.rows + 1;\n  const pos = mesh.positions;\n\n  const angle = t * Math.PI;\n  const cosA = Math.cos(angle);\n  const sinA = Math.sin(angle);\n\n  for (let i = 0; i < nx; i++) {\n    const x0 = (i / mesh.cols) * W; // distance from the spine\n    const X = x0 * cosA;\n    const Z = x0 * sinA;\n    for (let j = 0; j < ny; j++) {\n      const k = (j * nx + i) * 3;\n      pos[k] = X;\n      pos[k + 1] = (j / mesh.rows) * H;\n      pos[k + 2] = Z;\n    }\n  }\n\n  computeNormals(mesh);\n}\n","import { deformCone } from './cone';\nimport { deformSimple } from './simple';\nimport { IMPORTABLE_CURLS, type CurlModel, type CurlSpec, type CurlType } from './types';\n\n/**\n * The curl models carried in the bundle, and the only ones nameable by string.\n *\n * Kept apart from `./index` so importing them does not drag in the other four: the barrel names\n * every model, which is right for a caller picking one but wrong for the renderer, which must\n * only ever pull these two.\n */\nexport const cone: CurlModel = { deform: deformCone, anchored: true };\nexport const simple: CurlModel = {\n  deform: deformSimple,\n  anchored: false,\n  flat: true,\n  gloss: false,\n};\n\nexport const BUNDLED_CURLS: Record<CurlType, CurlModel> = { cone, simple };\n\n/**\n * Turn a `curl` option into a model. Strings name a bundled curl; anything else is already a\n * model, imported from `@zinejs/core/curls` or written by the caller.\n */\nexport function resolveCurl(spec: CurlSpec): CurlModel {\n  if (typeof spec !== 'string') return spec;\n  const model = BUNDLED_CURLS[spec];\n  if (model) return model;\n  // Reached only when validation was bypassed (a renderer used directly, say), so name the fix\n  // rather than the mistake: these curls are real, they just are not bundled.\n  if (IMPORTABLE_CURLS.includes(spec)) {\n    throw new Error(\n      `Zine: the '${spec}' curl is not bundled. Import it and pass the model: ` +\n        `import { ${spec} } from '@zinejs/core/curls'  →  curl: ${spec}`,\n    );\n  }\n  throw new Error(`Zine: unknown curl ${JSON.stringify(spec)}.`);\n}\n"],"mappings":";;AAmBA,SAAgB,EAAe,GAAc,GAAwB;CACnE,IAAM,IAAK,IAAO,GACZ,IAAK,IAAO,GACZ,IAAQ,IAAK,GACb,IAAM,IAAI,aAAa,IAAQ,CAAC;CACtC,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KACtB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;EAC3B,IAAM,IAAI,IAAI,IAAK;EAEnB,AADA,EAAI,IAAI,KAAK,IAAI,GACjB,EAAI,IAAI,IAAI,KAAK,IAAI;CACvB;CAEF,OAAO;EACL;EACA;EACA;EACA,WAAW,IAAI,aAAa,IAAQ,CAAC;EACrC,SAAS,IAAI,aAAa,IAAQ,CAAC;CACrC;AACF;AAGA,SAAgB,EAAe,GAAsB;CACnD,IAAM,IAAK,EAAK,OAAO,GACjB,IAAK,EAAK,OAAO,GACjB,IAAM,EAAK,WACX,IAAM,EAAK;CAEjB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KACtB,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;EAC3B,IAAM,IAAQ,IAAI,IAAI,IAAI,IAAI,GACxB,IAAQ,IAAI,IAAK,IAAI,IAAI,IAAI,GAC7B,IAAQ,IAAI,IAAI,IAAI,IAAI,GACxB,IAAQ,IAAI,IAAK,IAAI,IAAI,IAAI,GAE7B,KAAK,IAAI,IAAK,KAAS,GACvB,KAAK,IAAI,IAAK,KAAS,GACvB,KAAK,IAAQ,IAAK,KAAK,GACvB,KAAK,IAAQ,IAAK,KAAK,GAEvB,IAAM,EAAI,KAAM,EAAI,IACpB,IAAM,EAAI,IAAI,KAAM,EAAI,IAAI,IAC5B,IAAM,EAAI,IAAI,KAAM,EAAI,IAAI,IAC5B,IAAM,EAAI,KAAM,EAAI,IACpB,IAAM,EAAI,IAAI,KAAM,EAAI,IAAI,IAC5B,IAAM,EAAI,IAAI,KAAM,EAAI,IAAI,IAE9B,IAAM,IAAM,IAAM,IAAM,GACxB,IAAM,IAAM,IAAM,IAAM,GACxB,IAAM,IAAM,IAAM,IAAM,GACtB,IAAI,KAAK,MAAM,GAAK,GAAK,CAAG,KAAK;EAGvC,AAFA,KAAO,GACP,KAAO,GACP,KAAO;EAEP,IAAM,KAAK,IAAI,IAAK,KAAK;EAGzB,AAFA,EAAI,KAAK,GACT,EAAI,IAAI,KAAK,GACb,EAAI,IAAI,KAAK;CACf;AAEJ;;;ACxEA,IAAM,IAAa,KAAK,KAAK,KAAM,KAO7B,IAAY,MACZ,IAAY,IAMZ,IAAc,KAOd,IAAW,KASX,IAAU;AAiBhB,SAAgB,EAAW,GAAgB,GAAW,GAAW,GAAW,GAA0B;CACpG,IAAM,IAAK,EAAK,OAAO,GACjB,IAAK,EAAK,OAAO,GACjB,IAAM,EAAK,WAIX,IAAQ,KAAK,IAAW,IAAI,IAAI,GAChC,IAAO,KAAK,IAAI,KAAK,KAAK,CAAK,GAG/B,IAAQ,KAAK,KAAK,IAAI,KAAQ,KAAK,KAAK,IAAI,IAC5C,IAAW,KAAK,IAAI,CAAK,GACzB,IAAW,KAAK,IAAI,CAAK,GACzB,IAAc,IAAI,KAAK,IAAI,GAAU,IAAI,GAGzC,IAAW,KAAK,KAAa,IAAY,KAAa,IAGtD,KAAQ,EAAO,IAAI,MAAO,GAC1B,IAAa,KAAQ,GAEvB,IAAQ,KAAK,IAAI,GADL,KAAK,IAAI,CACD,IAAU,CAAW,GACvC,IAAY,IAAI,GAKhB,IAAQ,IAAa,IAAI,IAAW,CAAC,GACrC,IAAO,KAAK,MAAM,GAAG,KAAM,IAAI,CAAK,GACpC,IAAY,KAAK,IAAI,IAAO,GAAU,IAAI,KAAK,EAAE,GAMjD,IAAO,KAAK,IAAI,GAAG,IAAI,CAAO,GAC9B,IAAM,CAAC,KAAK,KAAK,GACjB,IAAO,KAAK,IAAI,CAAG,GACnB,IAAO,KAAK,IAAI,CAAG;CAIzB,IAAI,IAAO,MAAM;EACf,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;GAC3B,IAAM,IAAK,IAAI,EAAK,OAAQ;GAC5B,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;IAC3B,IAAM,IAAM,IAAI,EAAK,OAAQ,GACvB,KAAK,IAAI,IAAK,KAAK;IAGzB,AAFA,EAAI,KAAK,IAAK,GACd,EAAI,IAAI,KAAK,GACb,EAAI,IAAI,KAAK,CAAC,IAAK;GACrB;EACF;EACA,EAAe,CAAI;EACnB;CACF;CAEA,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;EAC3B,IAAM,IAAM,IAAI,EAAK,OAAQ;EAC7B,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;GAC3B,IAAM,IAAM,IAAI,EAAK,OAAQ,GAEzB,IAAK,GACL,IAAK,GACL,IAAK;GAET,IAAI,IAAQ,MAAM;IAIhB,IAAM,IAAM,IAAa,IAAI,IAAK,GAC5B,IAAI,CAAC,GACL,IAAI,KAAK,MAAM,GAAI,IAAM,CAAC;IAChC,IAAI,IAAI,MAAM;KACZ,IAAM,IAAI,IAAI,GACR,IAAO,KAAK,KAAK,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,IAAK,CAAC,CAAC,CAAC,IAAI,GACrD,IAAS,IAAI,KAAK,IAAI,CAAI,GAC1B,IAAQ,IAAI,IAAI,IAAI,IAAS;KAGnC,AAFA,IAAK,IAAI,KAAK,IAAI,CAAI,GACtB,IAAK,IAAa,IAAI,IAAQ,GAC9B,IAAK,IAAI,IAAS;IACpB;GACF;GAEA,IAAI,IAAK,GACL,IAAK,GACL,IAAK;GAET,IAAI,IAAY,MAAM;IACpB,IAAM,IAAO,IAAK,GACZ,IAAK,IAAY,KAAK,IAAI,CAAI,GAC9B,IAAK,KAAa,IAAI,KAAK,IAAI,CAAI;IAGzC,AAFA,IAAK,IAAQ,IAAK,IAAY,GAC9B,IAAK,IAAQ,IAAK,IAAY,GAC9B,IAAK,IAAQ,IAAK,IAAY;GAChC;GAEA,IAAM,KAAK,IAAI,IAAK,KAAK;GAGzB,AAFA,EAAI,KAAK,IAAK,IAAO,IAAK,GAC1B,EAAI,IAAI,KAAK,GACb,EAAI,IAAI,KAAK,CAAC,IAAK,IAAO,IAAK;EACjC;CACF;CAEA,EAAe,CAAI;AACrB;;;AC3JA,SAAgB,EAAa,GAAgB,GAAW,GAAW,GAAiB;CAClF,IAAM,IAAK,EAAK,OAAO,GACjB,IAAK,EAAK,OAAO,GACjB,IAAM,EAAK,WAEX,IAAQ,IAAI,KAAK,IACjB,IAAO,KAAK,IAAI,CAAK,GACrB,IAAO,KAAK,IAAI,CAAK;CAE3B,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;EAC3B,IAAM,IAAM,IAAI,EAAK,OAAQ,GACvB,IAAI,IAAK,GACT,IAAI,IAAK;EACf,KAAK,IAAI,IAAI,GAAG,IAAI,GAAI,KAAK;GAC3B,IAAM,KAAK,IAAI,IAAK,KAAK;GAGzB,AAFA,EAAI,KAAK,GACT,EAAI,IAAI,KAAM,IAAI,EAAK,OAAQ,GAC/B,EAAI,IAAI,KAAK;EACf;CACF;CAEA,EAAe,CAAI;AACrB;;;AClBA,IAAa,IAAkB;CAAE,QAAQ;CAAY,UAAU;AAAK,GACvD,IAAoB;CAC/B,QAAQ;CACR,UAAU;CACV,MAAM;CACN,OAAO;AACT,GAEa,IAA6C;CAAE;CAAM;AAAO;AAMzE,SAAgB,EAAY,GAA2B;CACrD,IAAI,OAAO,KAAS,UAAU,OAAO;CACrC,IAAM,IAAQ,EAAc;CAC5B,IAAI,GAAO,OAAO;CASlB,MANI,EAAiB,SAAS,CAAI,IACtB,MACR,cAAc,EAAK,gEACL,EAAK,yCAAyC,GAC9D,IAEQ,MAAM,sBAAsB,KAAK,UAAU,CAAI,EAAE,EAAE;AAC/D"}

package/dist/controls/contextMenu.d.ts

@@ -0,0 +1,16 @@
+import type { ContextMenuOptions } from './types';
+import type { Zine } from '../zine';
+/**
+ * A right-click menu of reading controls, opened at the cursor over the book.
+ *
+ * It reuses the toolbar's control definitions and its {@link ControlMenu} body, so the same icons
+ * and actions appear whether a reader reaches them from the toolbar or a right-click. It is opt-in
+ * (`contextMenu` off by default), because overriding the browser's own menu is a real cost to pay
+ * only when asked. Works with `controls: false` too, which is the point: a bare book with no
+ * toolbar can still offer a right-click menu.
+ */
+export declare class ContextMenu {
+    #private;
+    constructor(zine: Zine, container: HTMLElement, options?: ContextMenuOptions, hidden?: ReadonlySet<string>);
+    destroy(): void;
+}

package/dist/controls/controls.d.ts

@@ -1,8 +1,8 @@
-import type { ControlsOptions } from './types';
+import type { ContextMenuOptions, ControlsOptions } from './types';
 import type { Zine } from '../zine';
 export { defineControl, getControl, DEFAULT_ITEMS } from './registry';
 export { ICONS, createIcon } from './icons';
-export type { ControlContext, ControlDef, ControlItem, ControlsColorScheme, ControlsOptions, ControlsPosition, } from './types';
+export type { ContextMenuOptions, ControlContext, ControlDef, ControlItem, ControlsColorScheme, ControlsOptions, ControlsPosition, } from './types';
 /**
  * Build the toolbar inside `container` and return its teardown.
  *
@@ -11,4 +11,11 @@ export type { ControlContext, ControlDef, ControlItem, ControlsColorScheme, Cont
  * named `controls.ts` rather than `index.ts` so the emitted chunk is `controls-<hash>.js`, which
  * is what the size-limit budget watches.
  */
-export declare function mountControls(zine: Zine, container: HTMLElement, options?: ControlsOptions): () => void;
+export declare function mountControls(zine: Zine, container: HTMLElement, options?: ControlsOptions, hidden?: ReadonlySet<string>): () => void;
+/**
+ * Attach the right-click menu to `container` and return its teardown.
+ *
+ * Shares this lazy chunk with {@link mountControls}, so a book that wants only the context menu
+ * (`controls: false`, `contextMenu: true`) still reuses the same icons and control definitions.
+ */
+export declare function mountContextMenu(zine: Zine, container: HTMLElement, options?: ContextMenuOptions, hidden?: ReadonlySet<string>): () => void;

package/dist/controls/icons.d.ts

@@ -18,9 +18,9 @@ export declare const ICONS: {
     first: string;
     /** chevrons-right */
     last: string;
-    /** zoom-in */
+    /** circle-plus: zoom in. A plus, not a magnifier, so it never reads as a third "search". */
     zoomIn: string;
-    /** zoom-out */
+    /** circle-minus: zoom out, paired with zoomIn. */
     zoomOut: string;
     /** search */
     search: string;
@@ -46,6 +46,10 @@ export declare const ICONS: {
     download: string;
     /** x */
     close: string;
+    /** volume-2: sound on */
+    soundOn: string;
+    /** volume-x: muted */
+    soundOff: string;
 };
 /** Build an `<svg>` for one of the {@link ICONS}, or null if the name is unknown. */
 export declare function createIcon(doc: Document, markup: string): SVGSVGElement;

package/dist/controls/menu.d.ts

@@ -0,0 +1,68 @@
+import type { ControlContext, ControlDef, ControlItem } from './types';
+/**
+ * Drop every control whose id is in `hidden`, the one filter behind the top-level `hideControls`
+ * option. Applied at each build point so a named control disappears from the toolbar, its overflow
+ * menu and the right-click menu at once. Separators are left in place; menus drop them anyway and
+ * the toolbar tidies its own runs after filtering.
+ */
+export declare function filterHidden(items: readonly ControlItem[], hidden: ReadonlySet<string>): readonly ControlItem[];
+/**
+ * The shared menu machinery.
+ *
+ * A `.zine-controls-menu` is built the same way in two places: the toolbar's overflow (the ⋮
+ * button) and the right-click context menu. Rather than let those drift, both build their items,
+ * read their state, and run their actions through the helpers here, so a menu looks and behaves
+ * identically wherever it is anchored. Placement and dismissal stay with each owner, because a
+ * popover hanging off a toolbar button and one opening at the cursor differ only there.
+ */
+/** A control's label, which may depend on the current state. */
+export declare function titleOf(def: ControlDef, ctx: ControlContext): string;
+/** A control's glyph, which may likewise depend on state (an RTL mirror, say). */
+export declare function iconOf(def: ControlDef, ctx: ControlContext): string | undefined;
+/** The element itself if it can be disabled, else any inputs/buttons it wraps. */
+export declare function formFields(el: HTMLElement): (HTMLButtonElement | HTMLInputElement)[];
+/** Toggle the pending-action state on a button: a trailing spinner, disabled while it spins. */
+export declare function setBusy(btn: HTMLButtonElement, busy: boolean): void;
+/**
+ * Run a control's action, holding the button busy while a slow one (a cross-origin file fetched to
+ * save or print) settles. `onAfter` re-reads state once the action has run, and again when a
+ * pending one finishes. A disabled or already-busy button does nothing.
+ */
+export declare function activateControl(def: ControlDef, trigger: HTMLButtonElement, ctx: ControlContext, onAfter: () => void): void;
+/**
+ * A control button. Bar buttons are icon-only with the title as tooltip; menu items and any
+ * control without an icon also carry a visible label. `onActivate` is left to the caller so the
+ * toolbar can route a press through its submenu logic while a menu item just acts.
+ */
+export declare function buildControlButton(doc: Document, def: ControlDef, className: string, ctx: ControlContext, onActivate: (def: ControlDef, btn: HTMLButtonElement) => void, withLabel?: boolean): HTMLButtonElement;
+/**
+ * Re-read one control's state after the book changes and reflect it on its element.
+ *
+ * Applies to custom `render` widgets as well as plain buttons: the predicates live on `ControlDef`,
+ * so a widget may be any element and each piece of state is applied however that element supports
+ * it. `visible` overrides the `isVisible` predicate for a control whose visibility is decided
+ * elsewhere (a submenu shown only when it has visible children).
+ */
+export declare function applyControlItemState(el: HTMLElement, def: ControlDef, ctx: ControlContext, doc: Document, visible?: boolean): void;
+/**
+ * A `.zine-controls-menu`: a column of control items with `role=menu`. Owns the items it builds so
+ * it can re-read their state and clean up after itself. The owner supplies the context (whose
+ * `close()` dismisses this menu) and drives when to build, refresh, and destroy; where the menu is
+ * placed and how it is dismissed are the owner's business.
+ */
+export declare class ControlMenu {
+    #private;
+    readonly el: HTMLElement;
+    constructor(doc: Document, context: () => ControlContext, onAfterAction: () => void, hidden?: ReadonlySet<string>);
+    /** Fill the menu from a list of controls, dropping separators and anything not applicable. */
+    build(children: readonly ControlItem[]): void;
+    /** Re-read every item's state. */
+    refresh(): void;
+    /** Whether the menu (or something inside it) contains `node`. */
+    contains(node: Node | null): boolean;
+    focusFirst(): void;
+    destroy(): void;
+}
+/** A submenu is only worth showing if something inside it is. Keeps a menu trigger from opening
+ *  onto nothing when every entry has hidden itself. */
+export declare function hasVisibleChildren(def: ControlDef, ctx: ControlContext, hidden?: ReadonlySet<string>): boolean;

package/dist/controls/search.d.ts

@@ -1,5 +1,16 @@
 import { type PanelOptions } from './sidebar';
-import type { Zine } from '../zine';
+import type { SearchHit, Zine } from '../zine';
+/** The query and its results, so a closed panel can be reopened where the reader left it rather
+ *  than blank. Held by the toolbar (which outlives the panel) and handed back on reopen. */
+export interface SearchState {
+    query: string;
+    results: SearchHit[];
+}
+/** Panel options plus the optional state to reopen with. */
+export interface SearchOptions extends PanelOptions {
+    /** Query and results from a previous open, put back so the reader continues where they left off. */
+    state?: SearchState;
+}
 /**
  * Full-text search beside the book: a query field over its results.
  *
@@ -11,6 +22,8 @@ export declare class Search {
     #private;
     /** The panel's themed root, so the toolbar can stamp its colour scheme. */
     readonly root: HTMLElement;
-    constructor(zine: Zine, container: HTMLElement, options?: PanelOptions);
+    constructor(zine: Zine, container: HTMLElement, options?: SearchOptions);
+    /** The query and results as they stand, for the toolbar to stash across a close. */
+    getState(): SearchState;
     destroy(): void;
 }