@vysmo/flipbook 0.1.0

package/dist/loader.js

@@ -0,0 +1,26 @@
+/**
+ * Normalise a single page source into an element the `Runner` can use
+ * as a `TextureSource`. Strings are loaded into a new `Image`; existing
+ * image elements are awaited on; canvases pass through instantly.
+ */
+export async function resolvePage(source) {
+    if (typeof source === "string") {
+        const img = new Image();
+        img.crossOrigin = "anonymous";
+        img.src = source;
+        await img.decode();
+        return img;
+    }
+    if (source instanceof HTMLCanvasElement) {
+        return source;
+    }
+    // HTMLImageElement — wait for it if it's not yet complete.
+    if (source.complete && source.naturalWidth > 0)
+        return source;
+    await source.decode();
+    return source;
+}
+export function resolveAll(sources) {
+    return Promise.all(sources.map(resolvePage));
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAkB;IAClD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC;QAC9B,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC;QACjB,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,MAAM,YAAY,iBAAiB,EAAE,CAAC;QACxC,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,2DAA2D;IAC3D,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,YAAY,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC;IAC9D,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC;IACtB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CACxB,OAA8B;IAE9B,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,120 @@
+import type { EasingFn } from "@vysmo/easings";
+/**
+ * A single page. URL strings are decoded into images; `HTMLImageElement`
+ * / `HTMLCanvasElement` are used as-is. Rich-DOM pages are out of scope
+ * for v1 — pre-render to a canvas if you need them.
+ */
+export type PageSource = string | HTMLImageElement | HTMLCanvasElement;
+export type FlipbookAxis = "horizontal" | "vertical";
+export interface FlipbookOptions {
+    /**
+     * Host element. The flipbook creates its WebGL canvas inside this
+     * container. Size the container via CSS — the canvas fills 100% of it.
+     */
+    container: HTMLElement;
+    /** Page sources. Order matters: index 0 is the cover unless `initialPage` says otherwise. */
+    pages: readonly PageSource[];
+    /** Starting page index in [0, pages.length). Default 0. */
+    initialPage?: number;
+    /**
+     * Curl axis. `"horizontal"` peels the right edge leftward like an
+     * English book (pinned spine on the left). `"vertical"` peels the
+     * bottom edge upward like a wall calendar (pinned binding at the top).
+     * Default `"horizontal"`.
+     */
+    axis?: FlipbookAxis;
+    /**
+     * Hinge tilt in radians, **added on top of the axis baseline** (0 for
+     * horizontal, π/2 for vertical). Tilts the curl line away from a clean
+     * vertical/horizontal sweep. Default 0.12.
+     */
+    tilt?: number;
+    /** Page-back colour passed straight to the page-curl transition. */
+    backColor?: readonly [number, number, number];
+    /** Flip duration in milliseconds. Default 900. */
+    flipDuration?: number;
+    /** Easing for the flip progress. Default `cubicInOut` from `@vysmo/easings`. */
+    ease?: EasingFn;
+    /** Wrap from last → first (and vice versa). Default false — books have ends. */
+    loop?: boolean;
+    /**
+     * Click anywhere to flip: left half = prev, right half = next (vertical
+     * axis: top half = prev, bottom half = next). Default true.
+     */
+    clickNavigation?: boolean;
+    /**
+     * Pointer-drag scrubbing: drag in the flip direction to peel the page
+     * mid-curl. Release past `dragCommitThreshold` commits; below reverts.
+     * Default true.
+     */
+    dragNavigation?: boolean;
+    /**
+     * Drag commit threshold in [0, 1]. Released drag past this progress
+     * commits the flip; below reverts. Default 0.5. Lower (0.3) makes
+     * flips "sticky" — easier to commit. Higher (0.7) requires a more
+     * deliberate drag.
+     */
+    dragCommitThreshold?: number;
+    /**
+     * Keyboard navigation: `ArrowRight`/`ArrowDown` → next, `ArrowLeft`/
+     * `ArrowUp` → prev, `Home`/`End` → first/last. Default true.
+     */
+    keyboardNavigation?: boolean;
+    /**
+     * Auto-advance pages on a timer. `true` uses default 4000ms interval;
+     * pass `{ intervalMs }` to set your own. Pauses while the user is
+     * dragging or while the page lacks focus. Off by default. Use
+     * `play()` / `pause()` on the handle to toggle at runtime.
+     */
+    autoplay?: boolean | {
+        intervalMs: number;
+    };
+    /** Accessible label exposed via `aria-label`. Default `"Flipbook"`. */
+    ariaLabel?: string;
+}
+export interface FlipOptions {
+    /**
+     * Skip the curl animation and snap directly to the target page. Still
+     * emits `change` but not `flipstart` / `flipend`.
+     */
+    instant?: boolean;
+}
+export type FlipbookEvent = "change" | "flipstart" | "flipend";
+export interface FlipbookHandle {
+    readonly current: number;
+    readonly length: number;
+    readonly isFlipping: boolean;
+    /**
+     * Resolves when every string / image source has finished decoding.
+     * Canvas sources resolve instantly. Safe to call `next()` etc. before
+     * this resolves — they queue until the first frame is ready.
+     */
+    readonly ready: Promise<void>;
+    /** Advance to the next page. No-op while a flip is already in flight. */
+    next(): Promise<void>;
+    /** Retreat to the previous page. No-op while a flip is already in flight. */
+    prev(): Promise<void>;
+    /** Flip directly to a specific index. No-op if already there. */
+    goTo(index: number, options?: FlipOptions): Promise<void>;
+    /**
+     * Drive the current flip's progress externally. `progress` in [0, 1]
+     * scrubs from the current page to the next. Useful for scroll-driven
+     * flipbooks: pipe `@vysmo/scroll` progress straight in. Calling `seek`
+     * cancels any in-flight tween.
+     *
+     * Reaching 1 commits the flip; reaching 0 reverts to the current page.
+     * Other values hold the page mid-curl.
+     */
+    seek(progress: number): void;
+    /** Start auto-advance. Idempotent — no-op if already playing. */
+    play(): void;
+    /** Stop auto-advance. Idempotent — no-op if already paused. */
+    pause(): void;
+    /** True when autoplay is active (started + not paused). */
+    readonly isPlaying: boolean;
+    on(event: "change", cb: (current: number, previous: number) => void): () => void;
+    on(event: "flipstart", cb: (from: number, to: number) => void): () => void;
+    on(event: "flipend", cb: (from: number, to: number) => void): () => void;
+    destroy(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAEvE,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,UAAU,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,SAAS,EAAE,WAAW,CAAC;IACvB,6FAA6F;IAC7F,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7B,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,gFAAgF;IAChF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,iEAAiE;IACjE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;;;;OAQG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iEAAiE;IACjE,IAAI,IAAI,IAAI,CAAC;IACb,+DAA+D;IAC/D,KAAK,IAAI,IAAI,CAAC;IACd,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACjF,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3E,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACzE,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vysmo/flipbook",
+  "version": "0.1.0",
+  "description": "WebGL flipbook driven by the @vysmo/transitions page-curl mesh shader. Click halves, keyboard nav, drag corners to scrub mid-flip. Drop-in component or headless API.",
+  "license": "MIT",
+  "keywords": [
+    "flipbook",
+    "page-flip",
+    "page-curl",
+    "webgl",
+    "transitions",
+    "drag-scrub",
+    "headless"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@vysmo/animations": "0.1.0",
+    "@vysmo/transitions": "0.1.0",
+    "@vysmo/easings": "0.1.0"
+  },
+  "devDependencies": {
+    "@vitest/browser": "^3.2.4",
+    "esbuild": "^0.28.0",
+    "playwright": "^1.59.1",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:browser": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest",
+    "size": "node scripts/check-bundle-size.mjs"
+  }
+}

package/src/__tests__/create.test.ts

@@ -0,0 +1,465 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createFlipbook, type FlipbookHandle } from "../index.js";
+
+let container: HTMLElement;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  container.style.width = "400px";
+  container.style.height = "300px";
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  container.remove();
+});
+
+function makePage(color: string): HTMLCanvasElement {
+  const c = document.createElement("canvas");
+  c.width = 80;
+  c.height = 60;
+  const ctx = c.getContext("2d")!;
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, 80, 60);
+  return c;
+}
+
+async function mountReady(
+  pages: HTMLCanvasElement[],
+  overrides?: Partial<Parameters<typeof createFlipbook>[0]>,
+): Promise<FlipbookHandle> {
+  const f = createFlipbook({
+    container,
+    pages,
+    flipDuration: 30,
+    ...overrides,
+  });
+  await f.ready;
+  return f;
+}
+
+describe("createFlipbook: structure", () => {
+  it("mounts a wrapper + canvas + aria-live status into the container", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    const wrapper = container.querySelector("[data-page-flip-wrapper]");
+    expect(wrapper).toBeTruthy();
+    expect(wrapper!.getAttribute("role")).toBe("region");
+    expect(wrapper!.getAttribute("aria-roledescription")).toBe("flipbook");
+    expect(wrapper!.getAttribute("aria-label")).toBe("Flipbook");
+    expect(wrapper!.querySelector("[data-page-flip-canvas]")).toBeTruthy();
+    const live = wrapper!.querySelector('[aria-live="polite"]');
+    expect(live).toBeTruthy();
+    f.destroy();
+  });
+
+  it("starts at index 0 by default; initialPage overrides", async () => {
+    const a = await mountReady([makePage("red"), makePage("green")]);
+    expect(a.current).toBe(0);
+    a.destroy();
+    container.innerHTML = "";
+    const b = await mountReady(
+      [makePage("red"), makePage("green"), makePage("blue")],
+      { initialPage: 2 },
+    );
+    expect(b.current).toBe(2);
+    b.destroy();
+  });
+
+  it("length reflects the number of pages", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    expect(f.length).toBe(3);
+    f.destroy();
+  });
+
+  it("throws when pages array is empty", () => {
+    expect(() => createFlipbook({ container, pages: [] })).toThrow(
+      /at least one page/,
+    );
+  });
+
+  it("respects a custom ariaLabel", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")], {
+      ariaLabel: "Magazine",
+    });
+    const wrapper = container.querySelector("[data-page-flip-wrapper]");
+    expect(wrapper!.getAttribute("aria-label")).toBe("Magazine");
+    f.destroy();
+  });
+});
+
+describe("createFlipbook: navigation", () => {
+  it("next() advances the current index", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    await f.next();
+    expect(f.current).toBe(1);
+    await f.next();
+    expect(f.current).toBe(2);
+    f.destroy();
+  });
+
+  it("next() stops at last when loop=false (default)", async () => {
+    const f = await mountReady(
+      [makePage("red"), makePage("green")],
+      { initialPage: 1 },
+    );
+    await f.next();
+    expect(f.current).toBe(1);
+    f.destroy();
+  });
+
+  it("next() wraps last → first when loop=true", async () => {
+    const f = await mountReady(
+      [makePage("red"), makePage("green")],
+      { initialPage: 1, loop: true },
+    );
+    await f.next();
+    expect(f.current).toBe(0);
+    f.destroy();
+  });
+
+  it("prev() stops at first when loop=false", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    await f.prev();
+    expect(f.current).toBe(0);
+    f.destroy();
+  });
+
+  it("prev() wraps first → last when loop=true", async () => {
+    const f = await mountReady(
+      [makePage("red"), makePage("green"), makePage("blue")],
+      { loop: true },
+    );
+    await f.prev();
+    expect(f.current).toBe(2);
+    f.destroy();
+  });
+
+  it("goTo(index) flips to a specific page", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    await f.goTo(2);
+    expect(f.current).toBe(2);
+    f.destroy();
+  });
+
+  it("goTo(index, { instant: true }) snaps without playing the curl", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    const starts: number[] = [];
+    f.on("flipstart", () => starts.push(1));
+    await f.goTo(2, { instant: true });
+    expect(f.current).toBe(2);
+    expect(starts).toHaveLength(0);
+    f.destroy();
+  });
+
+  it("goTo(currentIndex) is a no-op", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    const starts: number[] = [];
+    f.on("flipstart", () => starts.push(1));
+    await f.goTo(0);
+    expect(starts).toHaveLength(0);
+    f.destroy();
+  });
+
+  it("clamps out-of-range indices on instant goTo", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    await f.goTo(99, { instant: true });
+    expect(f.current).toBe(2);
+    await f.goTo(-5, { instant: true });
+    expect(f.current).toBe(0);
+    f.destroy();
+  });
+});
+
+describe("createFlipbook: events", () => {
+  it("fires flipstart + change + flipend in order on next()", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    const events: string[] = [];
+    f.on("flipstart", (from, to) => events.push(`start:${from}->${to}`));
+    f.on("change", (cur, prev) => events.push(`change:${prev}->${cur}`));
+    f.on("flipend", (from, to) => events.push(`end:${from}->${to}`));
+    await f.next();
+    expect(events).toEqual(["start:0->1", "change:0->1", "end:0->1"]);
+    f.destroy();
+  });
+
+  it("instant goTo emits change but not flipstart/end", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    const events: string[] = [];
+    f.on("flipstart", () => events.push("start"));
+    f.on("change", () => events.push("change"));
+    f.on("flipend", () => events.push("end"));
+    await f.goTo(2, { instant: true });
+    expect(events).toEqual(["change"]);
+    f.destroy();
+  });
+
+  it("unsubscribe callback stops further events", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    const seen: number[] = [];
+    const off = f.on("change", (c) => seen.push(c));
+    await f.next();
+    off();
+    await f.prev();
+    expect(seen).toEqual([1]);
+    f.destroy();
+  });
+});
+
+describe("createFlipbook: keyboard", () => {
+  it("ArrowRight advances; ArrowLeft retreats", async () => {
+    const f = await mountReady([
+      makePage("red"),
+      makePage("green"),
+      makePage("blue"),
+    ]);
+    const wrapper = container.querySelector(
+      "[data-page-flip-wrapper]",
+    ) as HTMLElement;
+    wrapper.focus();
+    const firstChange = new Promise<number>((resolve) => {
+      const off = f.on("change", (cur) => {
+        off();
+        resolve(cur);
+      });
+    });
+    wrapper.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }),
+    );
+    expect(await firstChange).toBe(1);
+    f.destroy();
+  });
+
+  it("Home jumps to first page; End jumps to last", async () => {
+    const f = await mountReady(
+      [makePage("a"), makePage("b"), makePage("c"), makePage("d")],
+      { initialPage: 1 },
+    );
+    const wrapper = container.querySelector(
+      "[data-page-flip-wrapper]",
+    ) as HTMLElement;
+    wrapper.focus();
+
+    const endChange = new Promise<number>((resolve) => {
+      const off = f.on("change", (cur) => {
+        off();
+        resolve(cur);
+      });
+    });
+    wrapper.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "End", bubbles: true }),
+    );
+    expect(await endChange).toBe(3);
+
+    const homeChange = new Promise<number>((resolve) => {
+      const off = f.on("change", (cur) => {
+        off();
+        resolve(cur);
+      });
+    });
+    wrapper.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Home", bubbles: true }),
+    );
+    expect(await homeChange).toBe(0);
+    f.destroy();
+  });
+});
+
+describe("createFlipbook: pointer", () => {
+  it("click on right half triggers next; left half triggers prev", async () => {
+    const f = await mountReady(
+      [makePage("a"), makePage("b"), makePage("c")],
+      { initialPage: 1 },
+    );
+    const wrapper = container.querySelector(
+      "[data-page-flip-wrapper]",
+    ) as HTMLElement;
+    const rect = wrapper.getBoundingClientRect();
+
+    function clickAt(x: number, y: number): void {
+      const id = 1;
+      wrapper.dispatchEvent(
+        new PointerEvent("pointerdown", {
+          pointerId: id,
+          clientX: x,
+          clientY: y,
+          button: 0,
+          bubbles: true,
+        }),
+      );
+      wrapper.dispatchEvent(
+        new PointerEvent("pointerup", {
+          pointerId: id,
+          clientX: x,
+          clientY: y,
+          bubbles: true,
+        }),
+      );
+    }
+
+    const rightChange = new Promise<number>((resolve) => {
+      const off = f.on("change", (cur) => {
+        off();
+        resolve(cur);
+      });
+    });
+    clickAt(rect.left + rect.width * 0.85, rect.top + rect.height / 2);
+    expect(await rightChange).toBe(2);
+
+    const leftChange = new Promise<number>((resolve) => {
+      const off = f.on("change", (cur) => {
+        off();
+        resolve(cur);
+      });
+    });
+    clickAt(rect.left + rect.width * 0.15, rect.top + rect.height / 2);
+    expect(await leftChange).toBe(1);
+
+    f.destroy();
+  });
+
+  it("drag past 50% commits forward; release under 50% reverts", async () => {
+    const f = await mountReady([makePage("a"), makePage("b"), makePage("c")]);
+    const wrapper = container.querySelector(
+      "[data-page-flip-wrapper]",
+    ) as HTMLElement;
+    const rect = wrapper.getBoundingClientRect();
+
+    function dragRelease(dx: number): Promise<number | null> {
+      return new Promise((resolve) => {
+        const id = 2;
+        const startX = rect.left + rect.width * 0.7;
+        const y = rect.top + rect.height / 2;
+        let resolved = false;
+        const off = f.on("change", (cur) => {
+          off();
+          resolved = true;
+          resolve(cur);
+        });
+        wrapper.dispatchEvent(
+          new PointerEvent("pointerdown", {
+            pointerId: id,
+            clientX: startX,
+            clientY: y,
+            button: 0,
+            bubbles: true,
+          }),
+        );
+        wrapper.dispatchEvent(
+          new PointerEvent("pointermove", {
+            pointerId: id,
+            clientX: startX + dx,
+            clientY: y,
+            bubbles: true,
+          }),
+        );
+        wrapper.dispatchEvent(
+          new PointerEvent("pointerup", {
+            pointerId: id,
+            clientX: startX + dx,
+            clientY: y,
+            bubbles: true,
+          }),
+        );
+        // Resolve null after a short window if no change fires (revert path).
+        setTimeout(() => {
+          if (!resolved) {
+            off();
+            resolve(null);
+          }
+        }, 80);
+      });
+    }
+
+    // Drag left by 80% of width — should commit forward.
+    const after = await dragRelease(-rect.width * 0.8);
+    expect(after).toBe(1);
+    expect(f.current).toBe(1);
+
+    // Drag left by 20% — should revert. f.current stays 1.
+    const noop = await dragRelease(-rect.width * 0.2);
+    expect(noop).toBeNull();
+    expect(f.current).toBe(1);
+
+    f.destroy();
+  });
+
+  it("drag at first page in backward direction is a no-op (loop=false)", async () => {
+    const f = await mountReady([makePage("a"), makePage("b")]);
+    const wrapper = container.querySelector(
+      "[data-page-flip-wrapper]",
+    ) as HTMLElement;
+    const rect = wrapper.getBoundingClientRect();
+    const id = 3;
+    wrapper.dispatchEvent(
+      new PointerEvent("pointerdown", {
+        pointerId: id,
+        clientX: rect.left + rect.width / 2,
+        clientY: rect.top + rect.height / 2,
+        button: 0,
+        bubbles: true,
+      }),
+    );
+    wrapper.dispatchEvent(
+      new PointerEvent("pointermove", {
+        pointerId: id,
+        clientX: rect.left + rect.width * 1.2,
+        clientY: rect.top + rect.height / 2,
+        bubbles: true,
+      }),
+    );
+    wrapper.dispatchEvent(
+      new PointerEvent("pointerup", {
+        pointerId: id,
+        clientX: rect.left + rect.width * 1.2,
+        clientY: rect.top + rect.height / 2,
+        bubbles: true,
+      }),
+    );
+    // No flip should commit; current stays at 0.
+    await new Promise((r) => setTimeout(r, 60));
+    expect(f.current).toBe(0);
+    f.destroy();
+  });
+});
+
+describe("createFlipbook: destroy", () => {
+  it("removes the wrapper from the container", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    expect(container.querySelector("[data-page-flip-wrapper]")).toBeTruthy();
+    f.destroy();
+    expect(container.querySelector("[data-page-flip-wrapper]")).toBeNull();
+  });
+
+  it("stops delivering events after destroy", async () => {
+    const f = await mountReady([makePage("red"), makePage("green")]);
+    const seen: number[] = [];
+    f.on("change", (c) => seen.push(c));
+    f.destroy();
+    await f.next().catch(() => {});
+    expect(seen).toEqual([]);
+  });
+});