@vysmo/flipbook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maesto LLC
+
+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

@@ -0,0 +1,100 @@
+# @vysmo/flipbook
+
+WebGL flipbook driven by the [`@vysmo/transitions`](https://www.npmjs.com/package/@vysmo/transitions) page-curl mesh shader. Click halves, keyboard nav, **drag corners to scrub mid-flip** — the page-curl shader's `progress` follows your pointer, release past 50% to commit the flip, less to revert. Drop-in component or headless API.
+
+[Live demo + playground](https://vysmo.com/flipbook) · [Source](https://github.com/vysmodev)
+
+## Install
+
+```bash
+pnpm add @vysmo/flipbook @vysmo/transitions @vysmo/animations @vysmo/easings
+```
+
+(Peers ship separately so you can pin them per-project. They're transitive deps; `npm install @vysmo/flipbook` pulls them in automatically — just add to your own `package.json` if you want explicit version control.)
+
+## Quick start
+
+```ts
+import { createFlipbook } from "@vysmo/flipbook";
+
+const flip = createFlipbook({
+  container: document.querySelector("#book")!,
+  pages: [
+    "/p1.jpg",
+    "/p2.jpg",
+    "/p3.jpg",
+    "/p4.jpg",
+  ],
+  axis: "horizontal", // or "vertical"
+  loop: true,
+});
+
+// Click halves / drag corners / arrow keys are all wired by default.
+flip.next();
+flip.prev();
+flip.goTo(2);
+```
+
+## Pages
+
+`pages` accepts:
+- Image URLs (string)
+- `HTMLImageElement` (already-loaded)
+- `HTMLCanvasElement` / `OffscreenCanvas`
+- `HTMLVideoElement`
+- Any other `TextureSource` (per [`@vysmo/transitions`](https://www.npmjs.com/package/@vysmo/transitions))
+
+The flipbook resolves URL strings into images for you and uploads each page to the GPU via `TextureCache`.
+
+## Drag-scrub
+
+The signature feature: when you drag a corner of the book mid-flip, the page-curl shader's `progress` follows your pointer in real time. Release past 50% to commit; less to revert with a spring tween back to the previous page. This is what differentiates the component from a CSS-only flipbook — there's no equivalent without the shader.
+
+Disable with `enableDrag: false` if you only want click + keyboard navigation.
+
+## Options
+
+```ts
+// @no-check
+type FlipbookOptions = {
+  container: HTMLElement;
+  pages: PageSource[];
+  axis?: "horizontal" | "vertical";   // default "horizontal"
+  loop?: boolean;                     // wrap last → first
+  duration?: number;                  // ms per flip (default 900)
+  ease?: EasingFn;                    // default cubicInOut
+  radius?: number;                    // page-curl radius (default 0.35)
+  tilt?: number;                      // page-curl tilt (default 0.12)
+  backColor?: [number, number, number]; // back-of-page tint (default warm white)
+  enableDrag?: boolean;               // default true
+  dragCommit?: number;                // 0..1 — release threshold (default 0.5)
+  enableKeyboard?: boolean;           // default true
+  autoplay?: boolean | number;        // true → 4s; number → custom ms
+  // ... and a few more
+};
+```
+
+## Events
+
+```ts
+flip.on("change", (current, previous) => /* … */);
+flip.on("flipstart", (from, to) => /* … */);
+flip.on("flipend", (from, to) => /* … */);
+```
+
+## Disposal
+
+```ts
+flip.dispose(); // releases GPU resources, removes listeners
+```
+
+## Characteristics
+
+- **DOM-only.** Requires `HTMLCanvasElement` and pointer / keyboard events.
+- **WebGL2 only** (transitive — driven by `@vysmo/transitions`).
+- **SSR-safe at module load.** Module imports cleanly in Node; constructing requires a live DOM.
+- **Bundle:** ~3 KB gzipped (peers external).
+
+## License
+
+MIT.

package/dist/create.d.ts

@@ -0,0 +1,18 @@
+import type { FlipbookHandle, FlipbookOptions } from "./types.js";
+/**
+ * Create a WebGL flipbook around the page-curl mesh transition.
+ *
+ * Pass a container element + an array of page sources (image URLs,
+ * `HTMLImageElement`s, canvases, or videos) and you get a fully wired
+ * flipbook: click halves to flip, arrow keys for keyboard nav, drag the
+ * corner mid-flip to scrub the curl manually (release past 50% to commit,
+ * less to revert), optional autoplay with pause-on-hover.
+ *
+ * The handle exposes `.next()`, `.prev()`, `.goTo(index)`, `.play()`,
+ * `.pause()`, `.dispose()`, plus `.on(event, listener)` for lifecycle
+ * (`change`, `flipstart`, `flipend`).
+ *
+ * @throws Error if `options.pages` is empty.
+ */
+export declare function createFlipbook(options: FlipbookOptions): FlipbookHandle;
+//# sourceMappingURL=create.d.ts.map

package/dist/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIV,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AAiBpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc,CAolBvE"}