@makefully/fancifully 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +50 -12
  2. package/LICENSE +21 -21
  3. package/README.md +245 -147
  4. package/dist/Storybook.d.ts +106 -3
  5. package/dist/Storybook.d.ts.map +1 -1
  6. package/dist/fancifully.css +1 -1
  7. package/dist/fancifully.iife.js +4 -8
  8. package/dist/fancifully.js +3538 -1999
  9. package/dist/flip/DefaultFlipStyle.d.ts +11 -0
  10. package/dist/flip/DefaultFlipStyle.d.ts.map +1 -0
  11. package/dist/flip/FlipStyle.d.ts +47 -0
  12. package/dist/flip/FlipStyle.d.ts.map +1 -0
  13. package/dist/flip/index.d.ts +4 -0
  14. package/dist/flip/index.d.ts.map +1 -0
  15. package/dist/index.d.ts +11 -4
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/interop/fabricLike.d.ts +124 -0
  18. package/dist/interop/fabricLike.d.ts.map +1 -0
  19. package/dist/layout/layoutUnits.d.ts +43 -0
  20. package/dist/layout/layoutUnits.d.ts.map +1 -0
  21. package/dist/load/fanciFile.d.ts +6 -0
  22. package/dist/load/fanciFile.d.ts.map +1 -0
  23. package/dist/load/loadEpub.d.ts.map +1 -1
  24. package/dist/nav/Pager.d.ts +27 -5
  25. package/dist/nav/Pager.d.ts.map +1 -1
  26. package/dist/nav/hardback.d.ts +24 -0
  27. package/dist/nav/hardback.d.ts.map +1 -0
  28. package/dist/nav/layoutMode.d.ts +51 -4
  29. package/dist/nav/layoutMode.d.ts.map +1 -1
  30. package/dist/pack/packFanci.d.ts +16 -0
  31. package/dist/pack/packFanci.d.ts.map +1 -0
  32. package/dist/render/SpreadView.d.ts +67 -3
  33. package/dist/render/SpreadView.d.ts.map +1 -1
  34. package/dist/render/blocks/TextBlock.d.ts.map +1 -1
  35. package/dist/schema/story.d.ts +160 -17
  36. package/dist/schema/story.d.ts.map +1 -1
  37. package/dist/ui/iconifyIcon.d.ts +21 -0
  38. package/dist/ui/iconifyIcon.d.ts.map +1 -0
  39. package/package.json +76 -74
package/CHANGELOG.md CHANGED
@@ -1,12 +1,50 @@
1
- # Changelog
2
-
3
- All notable changes to this project will be documented in this file.
4
-
5
- ## [0.1.0]
6
-
7
- ### Added
8
-
9
- - Initial `@makefully/fancifully` release: DOM storybook engine with JSON / `.fanci` / EPUB loading
10
- - Unified two-leaf spread paging (single viewport uses blank offscreen mate)
11
- - SpringRoll volume/pause/captions binding and load `progress` / `loading` / delayed `loaded`
12
- - VO↔text sync via WebVTT or inline cues; text, image, and hotspot blocks
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ ## [0.3.0]
6
+
7
+ ### Added
8
+
9
+ - Reader layout on the host: `StorybookOptions.layoutMode` / `singleBreakpoint`, `setLayoutMode`, and `layoutPreference` (default `auto`)
10
+ - Authoring fields: `coverSize`, `guides`, cover `innerColor`, and text `fontWeight` / `fontStyle`
11
+ - Fabric-like page and spread interop, plus layout helpers (`boxToPixels`, `scaleBlocksToPageSize`)
12
+ - Package and page APIs: `packFanci`, `downloadFanci`, `addPage`, cover/hardback setters, and `setStageZoom`
13
+
14
+ ### Changed
15
+
16
+ - Single vs two-page presentation is a reader setting. Stories store pages only; a legacy `layout` object in story JSON is ignored.
17
+ - The Maker UI and demo app left this package. Fabric is no longer a dependency.
18
+ - Chrome buttons use Iconify icons.
19
+
20
+ ### Removed
21
+
22
+ - In-repo editor and demo (`src/editor`, `vite.demo.config.ts`)
23
+
24
+ ## [0.2.0]
25
+
26
+ ### Added
27
+
28
+ - Story `hardback` flag: larger front/back cover boards with a visible cover rim when interior pages are open
29
+ - Chrome theming: CSS vars for captions/buttons, image-button hooks (`--fc-btn-*-image` + `.fc-chrome--images`)
30
+ - `StorybookOptions.chrome` for labels, aria-labels, className, and hidden chrome
31
+ - Prev/next disable at first/last spread
32
+ - Layout modes: dedicated one-page spreads, `responsive` (orientation), remapping across mode flips
33
+ - `frontCover` / `backCover` story flags: closed centered covers; open/close via page-flip to interior (covers excluded from open spreads)
34
+ - Extensible `FlipStyle` API: `StorybookOptions.flipStyle` / `flipSpeed`, `registerFlipStyle`, built-in `DefaultFlipStyle`
35
+ - Optional `editor: true` host mode (Fabric page editing, cover toggles, `.fanci` download)
36
+
37
+ ### Changed
38
+
39
+ - Flip style/speed are host-only (`StorybookOptions` / `setFlipStyle` / `setFlipSpeed`); removed from story JSON
40
+ - `single` builds one spread per story page (blank mate); `two-page` keeps facing pairs
41
+ - `auto` remains the width-breakpoint resolver; prefer `responsive` for device orientation
42
+
43
+ ## [0.1.0]
44
+
45
+ ### Added
46
+
47
+ - Initial `@makefully/fancifully` release: DOM storybook engine with JSON / `.fanci` / EPUB loading
48
+ - Unified two-leaf spread paging (single viewport uses blank offscreen mate)
49
+ - SpringRoll volume/pause/captions binding and load `progress` / `loading` / delayed `loaded`
50
+ - VO↔text sync via WebVTT or inline cues; text, image, and hotspot blocks
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Makefully Studios
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Makefully Studios
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,147 +1,245 @@
1
- # @makefully/fancifully
2
-
3
- DOM-based interactive storybook engine with SpringRoll-friendly audio buses, VO↔text cue sync, hotspots, and a unified two-leaf page flip (single-page mode keeps a blank leaf offscreen so turns animate the same way).
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm install @makefully/fancifully
9
- # optional peer for host mute/volume/captions
10
- npm install springroll
11
- ```
12
-
13
- ## Publishing (maintainers)
14
-
15
- Releases match other Makefully packages (`@makefully/platypus`, `@makefully/notefully`):
16
-
17
- 1. Bump `version` in `package.json` and add a `## [x.y.z]` section in `CHANGELOG.md`.
18
- 2. Merge to `main` (or run the **Release** workflow manually).
19
- 3. GitHub Actions tests, builds, publishes to npm via **OIDC trusted publisher**, and creates a GitHub release.
20
-
21
- One-time npm setup (org owner): on [npmjs.com](https://www.npmjs.com) → `@makefully` → **Trusted Publishers** → add GitHub Actions for repo `Makefully-Studios/fancifully`, workflow `release.yml`, environment blank / as configured.
22
-
23
- Local dry-run: `npm run pack:check`
24
-
25
- ## Quick start (standalone)
26
-
27
- ```ts
28
- import { Storybook } from '@makefully/fancifully';
29
- import '@makefully/fancifully/fancifully.css';
30
-
31
- const book = await Storybook.create(document.getElementById('app')!, {
32
- story: './stories/demo/story.json', // or './book.fanci' / './book.epub' / File
33
- baseUrl: './stories/demo/', // used for loose JSON + relative assets
34
- });
35
-
36
- book.next();
37
- book.prev();
38
- book.playReadAloud();
39
- book.setLayoutMode('auto'); // 'single' | 'two-page' | 'auto'
40
- ```
41
-
42
- ## Embed with SpringRoll (Platypus-like)
43
-
44
- ```ts
45
- import { Application } from 'springroll';
46
- import { Storybook } from '@makefully/fancifully';
47
- import '@makefully/fancifully/fancifully.css';
48
-
49
- const app = new Application({
50
- features: {
51
- sound: true,
52
- soundVolume: true,
53
- vo: true,
54
- voVolume: true,
55
- sfx: true,
56
- captions: true,
57
- },
58
- });
59
-
60
- const book = await Storybook.create(container, {
61
- story: myStoryObject, // or URL
62
- baseUrl: '/books/hill/',
63
- springroll: app,
64
- });
65
-
66
- book.on('pagechange', ({ pageIds, index, layoutMode }) => {
67
- console.log(pageIds, index, layoutMode);
68
- });
69
- ```
70
-
71
- If `springroll` is omitted, Fancifully creates an `Application` (when the peer is available) and **holds SpringRoll `loaded` / `state.ready` until the story package is unpacked and assets are loaded** — same idea as Platypus waiting on preload before the container hides its loading UI.
72
-
73
- While loading, Fancifully reports:
74
-
75
- | Bellhop event | Payload |
76
- |---------------|---------|
77
- | `progress` | `number` 0–1 (classic Container loading bar) |
78
- | `loading` | `{ stage, progress, count?, total?, detail? }` |
79
-
80
- ```ts
81
- await Storybook.create(el, {
82
- story: './book.fanci',
83
- onProgress: ({ stage, progress }) => console.log(stage, progress),
84
- });
85
- ```
86
-
87
- ## Story formats
88
-
89
- | Input | Extension | Notes |
90
- |-------|-----------|--------|
91
- | Fancifully JSON | `.json` | Full fidelity; `baseUrl` resolves relative assets |
92
- | Fancifully package | **`.fanci`** | ZIP of `story.json` + images/audio/vtt/fonts (relative paths). (`.fan` is already used by other software.) |
93
- | EPUB | `.epub` | Import subset: spine pages, images, fonts/audio when present, Media Overlays → cues. No hotspots. |
94
-
95
- ```ts
96
- // Packaged book
97
- await Storybook.create(el, { story: './tales/hill.fanci' });
98
-
99
- // EPUB (read-aloud if Media Overlays exist)
100
- await Storybook.create(el, { story: fileInput.files[0], storyName: fileInput.files[0].name });
101
- ```
102
-
103
- Pack a folder into `.fanci`:
104
-
105
- ```bash
106
- npm run pack:fanci
107
- # or: node scripts/pack-fanci.mjs path/to/story-dir out.fanci
108
- ```
109
-
110
- ## Story JSON
111
-
112
- Stories are JSON packages (not a single HTML document). Text may embed HTML; images/audio/vtt are asset references.
113
-
114
- | Field | Purpose |
115
- |-------|---------|
116
- | `pageSize` | Authoring pixel size per leaf |
117
- | `layout.mode` | `single` \| `two-page` \| `auto` |
118
- | `layout.singleBreakpoint` | Width where `auto` switches to two-page |
119
- | `assets` | Map of image / audio / vtt / html |
120
- | `pages[].blocks` | `text`, `image`, `hotspot` with `layout` boxes |
121
- | `pages[].readAloud` | `{ audio, cues }` — cues are a VTT asset id or inline `{id,start,end}[]` |
122
-
123
- ### Layout modes
124
-
125
- - **Always** a left+right spread under the hood.
126
- - **`two-page`**: both leaves visible.
127
- - **`single`**: leading blank leaf stays offscreen; same flip animation.
128
- - **`auto`**: picks by container width.
129
-
130
- Cover is blank+cover; interior pages pair; a final orphan gets a blank mate.
131
-
132
- ### VO ↔ text
133
-
134
- Put stable `id`s on spans in text HTML. WebVTT cue identifiers should match those ids. While VO plays, matching spans get `is-active` / `is-read`. A separate captions line respects SpringRoll `captionsMuted`.
135
-
136
- ## Scripts
137
-
138
- ```bash
139
- npm install
140
- npm test
141
- npm run dev # demo (Vite; default port 5174, or next free port)
142
- npm run build # dist library + types
143
- ```
144
-
145
- ## License
146
-
147
- MIT
1
+ # @makefully/fancifully
2
+
3
+ DOM-based interactive storybook engine with SpringRoll-friendly audio buses, VO↔text cue sync, hotspots, and a unified two-leaf page flip (single-page mode keeps a blank leaf offscreen so turns animate the same way).
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @makefully/fancifully
9
+ # optional peer for host mute/volume/captions
10
+ npm install springroll
11
+ ```
12
+
13
+ ## Publishing (maintainers)
14
+
15
+ Releases match other Makefully packages (`@makefully/platypus`, `@makefully/notefully`):
16
+
17
+ 1. Bump `version` in `package.json` and add a `## [x.y.z]` section in `CHANGELOG.md`.
18
+ 2. Merge to `main` (or run the **Release** workflow manually).
19
+ 3. GitHub Actions tests, builds, publishes to npm via **OIDC trusted publisher**, and creates a GitHub release.
20
+
21
+ One-time npm setup (org owner): on [npmjs.com](https://www.npmjs.com) → `@makefully` → **Trusted Publishers** → add GitHub Actions for repo `Makefully-Studios/fancifully`, workflow `release.yml`, environment blank / as configured.
22
+
23
+ Local dry-run: `npm run pack:check`
24
+
25
+ ## Quick start (standalone)
26
+
27
+ ```ts
28
+ import { Storybook } from '@makefully/fancifully';
29
+ import '@makefully/fancifully/fancifully.css';
30
+
31
+ const book = await Storybook.create(document.getElementById('app')!, {
32
+ story: './stories/demo/story.json', // or './book.fanci' / './book.epub' / File
33
+ baseUrl: './stories/demo/', // used for loose JSON + relative assets
34
+ });
35
+
36
+ book.next();
37
+ book.prev();
38
+ book.playReadAloud();
39
+ book.setLayoutMode('responsive'); // reader setting: 'single' | 'two-page' | 'responsive' | 'auto'
40
+ book.setFlipSpeed(300);
41
+ book.setFlipStyle('default');
42
+ ```
43
+
44
+ ### Flip style & speed
45
+
46
+ Page turns go through a `FlipStyle` implementation. Flip style and speed are **host settings** on `Storybook.create` / the instance — not fields in story JSON.
47
+
48
+ | API | Role |
49
+ |-----|------|
50
+ | `StorybookOptions.flipStyle` | Id (`"default"`), `FlipStyle` subclass, or instance |
51
+ | `StorybookOptions.flipSpeed` | Duration in ms (default `400`) |
52
+ | `registerFlipStyle(id, Ctor)` | Expose a custom class for string lookup |
53
+ | `book.setFlipStyle` / `setFlipSpeed` | Change at runtime |
54
+
55
+ ```ts
56
+ import { Storybook, FlipStyle, registerFlipStyle, type FlipContext } from '@makefully/fancifully';
57
+
58
+ class InstantFlipStyle extends FlipStyle {
59
+ static id = 'instant';
60
+ play(_ctx: FlipContext) {
61
+ return Promise.resolve(); // no animation
62
+ }
63
+ }
64
+
65
+ registerFlipStyle('instant', InstantFlipStyle);
66
+
67
+ await Storybook.create(el, {
68
+ story: './story.json',
69
+ flipStyle: InstantFlipStyle, // or 'instant' or new InstantFlipStyle()
70
+ flipSpeed: 200,
71
+ });
72
+ ```
73
+
74
+ Built-in: `DefaultFlipStyle` (`"default"`) — CSS 3D leaf turn. The engine uses the same `FlipStyle` base class for built-ins so new styles stay consistent.
75
+
76
+ ### Reader layout
77
+
78
+ Single page vs facing spread is a **host setting**, like flip style. Stories store a list of pages. The reader decides how to pair them. Legacy `layout` objects in story JSON are ignored.
79
+
80
+ | API | Role |
81
+ |-----|------|
82
+ | `StorybookOptions.layoutMode` | `single`, `two-page`, `responsive`, or `auto` (default) |
83
+ | `StorybookOptions.singleBreakpoint` | Width where `auto` switches to two-page (default `900`) |
84
+ | `book.setLayoutMode` | Change at runtime |
85
+ | `book.layoutPreference` | The host mode, before it resolves |
86
+ | `book.layoutMode` | Resolved `single` or `two-page` |
87
+
88
+ - **`two-page`**: facing pairs. With a front cover, open spreads start after the cover.
89
+ - **`single`**: one story page per turn, with a blank mate kept offscreen so the flip stays the same.
90
+ - **`responsive`**: landscape (width ≥ height) → two-page; portrait → single.
91
+ - **`auto`**: two-page when the stage is at least `singleBreakpoint` wide.
92
+
93
+ When the resolved mode changes, spreads rebuild and the view jumps to the spread that contains the current page.
94
+
95
+ ## Chrome theming
96
+
97
+ Built-in Prev / Read / Next live under `.fc-chrome`. Customize via CSS variables on `.fc-root` (or a host class) and optional `chrome` options:
98
+
99
+ ```ts
100
+ await Storybook.create(el, {
101
+ story: './stories/demo/story.json',
102
+ baseUrl: './stories/demo/',
103
+ chrome: {
104
+ className: 'my-theme fc-chrome--images', // image mode hides button text
105
+ labels: { prev: 'Prev', read: 'Read', next: 'Next' },
106
+ ariaLabels: { prev: 'Previous page', read: 'Read aloud', next: 'Next page' },
107
+ // hidden: true, // host-owned nav calling book.prev() / next() / playReadAloud()
108
+ },
109
+ });
110
+ ```
111
+
112
+ | Variable | Role |
113
+ |----------|------|
114
+ | `--fc-chrome-bg` / `--fc-chrome-fg` | Chrome bar colors |
115
+ | `--fc-captions-bg` / `--fc-captions-fg` / `--fc-captions-bottom` | Caption line |
116
+ | `--fc-btn-border` / `--fc-btn-hover-bg` | Text button chrome |
117
+ | `--fc-btn-read-bg` / `--fc-btn-read-fg` | Read button fill |
118
+ | `--fc-btn-prev-image` / `--fc-btn-next-image` / `--fc-btn-read-image` | `url("…")` for image buttons |
119
+ | `--fc-btn-image-size` | Hit target when using `.fc-chrome--images` |
120
+
121
+ Prev/next disable at the first/last spread (`disabled` + `.is-disabled`).
122
+
123
+ ## Authoring / editor
124
+
125
+ This package is the **player + story API** (load/render/playback, programmatic page mutations, `packFanci`, fabric-like JSON ingest). The Maker UI (Fabric overlays, page list, themes) lives in sibling [`@makefully/fancifully-editor`](../fancifully-editor):
126
+
127
+ ```ts
128
+ import { Storybook } from '@makefully/fancifully';
129
+ import { attachEditor } from '@makefully/fancifully-editor';
130
+ import '@makefully/fancifully/fancifully.css';
131
+ import '@makefully/fancifully-editor/editor.css';
132
+
133
+ const book = await Storybook.create(el, { story });
134
+ attachEditor(book, { enter: true });
135
+ ```
136
+
137
+ Write helpers on `Storybook` include `addPage`, `removePage`, `reorderPages`, `setFrontCover` / `setBackCover` / `setHardback`, `updatePage`, `replaceStory`, `downloadFanci`, plus leaf-host APIs for overlays (`getEditableLeaves`, `setPageViewsHidden`, `setNavLocked`).
138
+
139
+ ## Embed with SpringRoll (Platypus-like)
140
+
141
+ ```ts
142
+ import { Application } from 'springroll';
143
+ import { Storybook } from '@makefully/fancifully';
144
+ import '@makefully/fancifully/fancifully.css';
145
+
146
+ const app = new Application({
147
+ features: {
148
+ sound: true,
149
+ soundVolume: true,
150
+ vo: true,
151
+ voVolume: true,
152
+ sfx: true,
153
+ captions: true,
154
+ },
155
+ });
156
+
157
+ const book = await Storybook.create(container, {
158
+ story: myStoryObject, // or URL
159
+ baseUrl: '/books/hill/',
160
+ springroll: app,
161
+ });
162
+
163
+ book.on('pagechange', ({ pageIds, index, layoutMode }) => {
164
+ console.log(pageIds, index, layoutMode);
165
+ });
166
+ ```
167
+
168
+ If `springroll` is omitted, Fancifully creates an `Application` (when the peer is available) and **holds SpringRoll `loaded` / `state.ready` until the story package is unpacked and assets are loaded** — same idea as Platypus waiting on preload before the container hides its loading UI.
169
+
170
+ While loading, Fancifully reports:
171
+
172
+ | Bellhop event | Payload |
173
+ |---------------|---------|
174
+ | `progress` | `number` 0–1 (classic Container loading bar) |
175
+ | `loading` | `{ stage, progress, count?, total?, detail? }` |
176
+
177
+ ```ts
178
+ await Storybook.create(el, {
179
+ story: './book.fanci',
180
+ onProgress: ({ stage, progress }) => console.log(stage, progress),
181
+ });
182
+ ```
183
+
184
+ ## Story formats
185
+
186
+ | Input | Extension | Notes |
187
+ |-------|-----------|--------|
188
+ | Fancifully JSON | `.json` | Full fidelity; `baseUrl` resolves relative assets |
189
+ | Fancifully package | **`.fanci`** | ZIP of `story.json` + images/audio/vtt/fonts (relative paths). (`.fan` is already used by other software.) |
190
+ | EPUB | `.epub` | Import subset: spine pages, images, fonts/audio when present, Media Overlays → cues. No hotspots. |
191
+
192
+ ```ts
193
+ // Packaged book
194
+ await Storybook.create(el, { story: './tales/hill.fanci' });
195
+
196
+ // EPUB (read-aloud if Media Overlays exist)
197
+ await Storybook.create(el, { story: fileInput.files[0], storyName: fileInput.files[0].name });
198
+ ```
199
+
200
+ Pack a folder into `.fanci`:
201
+
202
+ ```bash
203
+ npm run pack:fanci -- path/to/story-dir [out.fanci]
204
+ # or: node scripts/pack-fanci.mjs path/to/story-dir out.fanci
205
+ ```
206
+
207
+ ## Story JSON
208
+
209
+ Stories are JSON packages (not a single HTML document). Text may embed HTML; images/audio/vtt are asset references.
210
+
211
+ | Field | Purpose |
212
+ |-------|---------|
213
+ | `pageSize` | Authoring pixel size per leaf |
214
+ | `frontCover` | If true, first page is a closed cover (centered); opens with a tween; no blank to its left |
215
+ | `backCover` | If true, last page is a back cover (no blank to its right); can close centered at the end |
216
+ | `hardback` | If true (with a cover flag), cover boards are larger than interior pages so open spreads show a cover rim |
217
+ | `assets` | Map of image / audio / vtt / html |
218
+ | `pages[].blocks` | `text`, `image`, `hotspot` with `layout` boxes |
219
+ | `pages[].readAloud` | `{ audio, cues }` — cues are a VTT asset id or inline `{id,start,end}[]` |
220
+
221
+ `pages` is always a flat list. Facing pages are a reader presentation, not a stored spread.
222
+
223
+ ### Covers (`frontCover` / `backCover` / `hardback`)
224
+
225
+ - **Unset (default):** book starts open with a blank mate beside the first page (`[blank, p0]`) and a trailing blank after an orphan last page.
226
+ - **`frontCover: true`:** starts closed (cover centered). Next **page-flips** to the first interior spread (cover is not kept on screen). Open spreads omit the cover page.
227
+ - **`backCover: true`:** last page is omitted from open spreads; Next from the last interior spread **page-flips** to a centered back cover.
228
+ - **`hardback: true`:** cover boards are slightly larger than `pageSize` (~3.5% per edge). Closed covers use that larger board; when open, cover art stays behind the interior spread so a rim remains visible.
229
+
230
+ ### VO ↔ text
231
+
232
+ Put stable `id`s on spans in text HTML. WebVTT cue identifiers should match those ids. While VO plays, matching spans get `is-active` / `is-read`. A separate captions line respects SpringRoll `captionsMuted`.
233
+
234
+ ## Scripts
235
+
236
+ ```bash
237
+ npm install
238
+ npm test
239
+ npm run dev # demo app (Vite)
240
+ npm run build # dist library + types
241
+ ```
242
+
243
+ ## License
244
+
245
+ MIT
@@ -1,8 +1,29 @@
1
+ import type { FlipStyleInput } from './flip/index.js';
2
+ import { findFanciFile } from './load/fanciFile.js';
3
+ import { type LoadedAssets } from './load/loadStory.js';
1
4
  import type { StorySource } from './load/packageTypes.js';
5
+ import type { LayoutMode } from './nav/layoutMode.js';
2
6
  import { type PagerEvents } from './nav/Pager.js';
3
- import type { LayoutMode, Story } from './schema/story.js';
7
+ import { type StageZoom } from './render/SpreadView.js';
8
+ import type { Story, StoryPage } from './schema/story.js';
4
9
  import { type SpringrollLike } from './springroll/bindApplication.js';
5
10
  import { type LoadProgress } from './springroll/loading.js';
11
+ export type StorybookChromeOptions = {
12
+ /** Hide built-in chrome (host can call next/prev/playReadAloud). */
13
+ hidden?: boolean;
14
+ /** Extra class(es) on `.fc-chrome` (e.g. `goldipup-chrome fc-chrome--images`). */
15
+ className?: string;
16
+ labels?: {
17
+ prev?: string;
18
+ read?: string;
19
+ next?: string;
20
+ };
21
+ ariaLabels?: {
22
+ prev?: string;
23
+ read?: string;
24
+ next?: string;
25
+ };
26
+ };
6
27
  export type StorybookOptions = {
7
28
  /** JSON URL/object, `.fanci` / `.epub` URL, or File/Blob/ArrayBuffer */
8
29
  story: StorySource | Story;
@@ -14,6 +35,28 @@ export type StorybookOptions = {
14
35
  autoPlayReadAloud?: boolean;
15
36
  /** Extra progress listener (SpringRoll Container also receives progress/loading). */
16
37
  onProgress?: (progress: LoadProgress) => void;
38
+ /** Built-in Prev / Read / Next chrome labels and visibility. */
39
+ chrome?: StorybookChromeOptions;
40
+ /**
41
+ * Page-flip style: registered id (`"default"`), a {@link FlipStyle} subclass,
42
+ * or an instance. Host setting (not part of story JSON).
43
+ */
44
+ flipStyle?: FlipStyleInput;
45
+ /** Flip duration in milliseconds. Host setting (not part of story JSON). */
46
+ flipSpeed?: number;
47
+ /**
48
+ * How pages are presented: one at a time, facing pairs, by orientation, or
49
+ * by stage width. Host setting (not part of story JSON). Default `auto`.
50
+ */
51
+ layoutMode?: LayoutMode;
52
+ /** Stage width in px where `auto` switches to two-page. Default 900. */
53
+ singleBreakpoint?: number;
54
+ };
55
+ export type EditableLeaf = {
56
+ side: 'left' | 'right';
57
+ pageIndex: number;
58
+ pageId: string;
59
+ slot: HTMLElement;
17
60
  };
18
61
  type StorybookEvents = PagerEvents & {
19
62
  ready: {
@@ -40,22 +83,82 @@ export declare class Storybook {
40
83
  private resizeObserver;
41
84
  private listeners;
42
85
  private destroyed;
86
+ private btnPrev;
87
+ private btnRead;
88
+ private btnNext;
89
+ private chromeHiddenByOptions;
90
+ /** Extra zip paths → bytes (fonts/images added by hosts/editors) for packFanci. */
91
+ private extraFiles;
92
+ private defaultFontFamily;
93
+ /** When true, swipe/keyboard/chrome nav and read-aloud are locked (editor overlay). */
94
+ private navLocked;
43
95
  private constructor();
44
96
  static create(container: HTMLElement, options: StorybookOptions): Promise<Storybook>;
45
97
  get story(): Story;
46
- get layoutMode(): import("./schema/story.js").ResolvedLayoutMode;
98
+ get assets(): LoadedAssets;
99
+ get baseUrl(): string;
100
+ /** Mutable list of blob URLs owned by the loaded package (hosts may push). */
101
+ get blobUrls(): string[];
102
+ get layoutMode(): import("./index.js").ResolvedLayoutMode;
103
+ /** Host preference (`auto`, `responsive`, …) before it resolves to single or two-page. */
104
+ get layoutPreference(): LayoutMode;
47
105
  get pageIds(): string[];
48
106
  get spreadIndex(): number;
107
+ get isNavLocked(): boolean;
108
+ getDefaultFontFamily(): string | null;
109
+ setDefaultFontFamily(family: string | null): void;
110
+ getExtraFiles(): Record<string, Uint8Array>;
111
+ putExtraFile(path: string, bytes: Uint8Array): void;
112
+ /**
113
+ * Lock player navigation (swipe/keys/chrome) for overlay editors.
114
+ * When locked, also hides book chrome unless the host already hid it.
115
+ */
116
+ setNavLocked(locked: boolean): void;
117
+ /** Visible content leaves for overlay editors (Fabric, etc.). */
118
+ getEditableLeaves(): EditableLeaf[];
119
+ /** The `.fc-spread` book element — host for a spread-wide editor overlay. */
120
+ getSpreadElement(): HTMLElement;
121
+ get bookState(): import("./index.js").BookState;
122
+ /** Left/right content pages for the current spread (`null` = blank leaf). */
123
+ getSpreadPages(): {
124
+ left: StoryPage | null;
125
+ right: StoryPage | null;
126
+ };
127
+ setPageViewsHidden(hidden: boolean): void;
128
+ remountCurrent(): void;
49
129
  on<K extends keyof StorybookEvents>(event: K, fn: Listener<K>): () => void;
50
130
  next(): Promise<void>;
51
131
  prev(): Promise<void>;
52
132
  goTo(pageId: string): Promise<void>;
133
+ /** Editor-only. Does not change single vs two-page layout. */
134
+ setStageZoom(zoom: StageZoom): void;
53
135
  setLayoutMode(mode: LayoutMode): void;
136
+ setFlipStyle(style: FlipStyleInput): void;
137
+ setFlipSpeed(speedMs: number): void;
54
138
  playReadAloud(): Promise<void>;
55
139
  pause(): void;
56
140
  resume(): void;
141
+ /** Replace the loaded story from a File / URL / Story object. */
142
+ replaceStory(source: StorySource | Story, storyName?: string): Promise<void>;
143
+ /** Open a `.fanci` File (validates extension/MIME). */
144
+ openFanciFile(file: File): Promise<void>;
145
+ /** Replace a page in-place and remount the current spread. */
146
+ updatePage(page: StoryPage): Promise<void>;
147
+ setPages(pages: StoryPage[], preferPageId?: string | null): Promise<void>;
148
+ addPage(): Promise<StoryPage>;
149
+ removePage(pageId: string): Promise<void>;
150
+ reorderPages(fromIndex: number, toIndex: number): Promise<void>;
151
+ setFrontCover(enabled: boolean): Promise<void>;
152
+ setBackCover(enabled: boolean): Promise<void>;
153
+ setHardback(enabled: boolean): Promise<void>;
154
+ /** Apply a font family to every text block in the story. */
155
+ applyFontToAllText(family: string): void;
156
+ packToBlob(): Promise<Blob>;
157
+ downloadFanci(filename?: string): Promise<void>;
57
158
  destroy(): void;
159
+ private navigate;
58
160
  private wireChrome;
161
+ private syncChromeNavState;
59
162
  private wirePager;
60
163
  private wireSpringroll;
61
164
  private wireResize;
@@ -65,5 +168,5 @@ export declare class Storybook {
65
168
  private handleTapActions;
66
169
  private emit;
67
170
  }
68
- export {};
171
+ export { findFanciFile };
69
172
  //# sourceMappingURL=Storybook.d.ts.map