@makefully/fancifully 0.1.0 → 0.2.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 (41) hide show
  1. package/CHANGELOG.md +31 -12
  2. package/LICENSE +21 -21
  3. package/README.md +250 -147
  4. package/dist/Storybook.d.ts +68 -0
  5. package/dist/Storybook.d.ts.map +1 -1
  6. package/dist/editor/EditorChrome.d.ts +33 -0
  7. package/dist/editor/EditorChrome.d.ts.map +1 -0
  8. package/dist/editor/PageCanvas.d.ts +50 -0
  9. package/dist/editor/PageCanvas.d.ts.map +1 -0
  10. package/dist/editor/dropImport.d.ts +16 -0
  11. package/dist/editor/dropImport.d.ts.map +1 -0
  12. package/dist/editor/index.d.ts +7 -0
  13. package/dist/editor/index.d.ts.map +1 -0
  14. package/dist/editor/layoutUnits.d.ts +39 -0
  15. package/dist/editor/layoutUnits.d.ts.map +1 -0
  16. package/dist/editor/packFanci.d.ts +16 -0
  17. package/dist/editor/packFanci.d.ts.map +1 -0
  18. package/dist/editor/storyFabricMap.d.ts +29 -0
  19. package/dist/editor/storyFabricMap.d.ts.map +1 -0
  20. package/dist/fancifully.css +1 -1
  21. package/dist/fancifully.iife.js +4 -8
  22. package/dist/fancifully.js +3432 -2065
  23. package/dist/flip/DefaultFlipStyle.d.ts +11 -0
  24. package/dist/flip/DefaultFlipStyle.d.ts.map +1 -0
  25. package/dist/flip/FlipStyle.d.ts +47 -0
  26. package/dist/flip/FlipStyle.d.ts.map +1 -0
  27. package/dist/flip/index.d.ts +4 -0
  28. package/dist/flip/index.d.ts.map +1 -0
  29. package/dist/index.d.ts +8 -3
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/nav/Pager.d.ts +18 -3
  32. package/dist/nav/Pager.d.ts.map +1 -1
  33. package/dist/nav/hardback.d.ts +21 -0
  34. package/dist/nav/hardback.d.ts.map +1 -0
  35. package/dist/nav/layoutMode.d.ts +43 -3
  36. package/dist/nav/layoutMode.d.ts.map +1 -1
  37. package/dist/render/SpreadView.d.ts +48 -2
  38. package/dist/render/SpreadView.d.ts.map +1 -1
  39. package/dist/schema/story.d.ts +30 -6
  40. package/dist/schema/story.d.ts.map +1 -1
  41. package/package.json +75 -74
package/CHANGELOG.md CHANGED
@@ -1,12 +1,31 @@
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.2.0]
6
+
7
+ ### Added
8
+
9
+ - Story `hardback` flag: larger front/back cover boards with a visible cover rim when interior pages are open
10
+ - Chrome theming: CSS vars for captions/buttons, image-button hooks (`--fc-btn-*-image` + `.fc-chrome--images`)
11
+ - `StorybookOptions.chrome` for labels, aria-labels, className, and hidden chrome
12
+ - Prev/next disable at first/last spread
13
+ - Layout modes: dedicated one-page spreads, `responsive` (orientation), remapping across mode flips
14
+ - `frontCover` / `backCover` story flags: closed centered covers; open/close via page-flip to interior (covers excluded from open spreads)
15
+ - Extensible `FlipStyle` API: `StorybookOptions.flipStyle` / `flipSpeed`, `registerFlipStyle`, built-in `DefaultFlipStyle`
16
+ - Optional `editor: true` host mode (Fabric page editing, cover toggles, `.fanci` download)
17
+
18
+ ### Changed
19
+
20
+ - Flip style/speed are host-only (`StorybookOptions` / `setFlipStyle` / `setFlipSpeed`); removed from story JSON
21
+ - `single` builds one spread per story page (blank mate); `two-page` keeps facing pairs
22
+ - `auto` remains the width-breakpoint resolver; prefer `responsive` for device orientation
23
+
24
+ ## [0.1.0]
25
+
26
+ ### Added
27
+
28
+ - Initial `@makefully/fancifully` release: DOM storybook engine with JSON / `.fanci` / EPUB loading
29
+ - Unified two-leaf spread paging (single viewport uses blank offscreen mate)
30
+ - SpringRoll volume/pause/captions binding and load `progress` / `loading` / delayed `loaded`
31
+ - 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,250 @@
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'); // '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
+ ## Chrome theming
77
+
78
+ Built-in Prev / Read / Next live under `.fc-chrome`. Customize via CSS variables on `.fc-root` (or a host class) and optional `chrome` options:
79
+
80
+ ```ts
81
+ await Storybook.create(el, {
82
+ story: './stories/demo/story.json',
83
+ baseUrl: './stories/demo/',
84
+ chrome: {
85
+ className: 'my-theme fc-chrome--images', // image mode hides button text
86
+ labels: { prev: 'Prev', read: 'Read', next: 'Next' },
87
+ ariaLabels: { prev: 'Previous page', read: 'Read aloud', next: 'Next page' },
88
+ // hidden: true, // host-owned nav calling book.prev() / next() / playReadAloud()
89
+ },
90
+ });
91
+ ```
92
+
93
+ | Variable | Role |
94
+ |----------|------|
95
+ | `--fc-chrome-bg` / `--fc-chrome-fg` | Chrome bar colors |
96
+ | `--fc-captions-bg` / `--fc-captions-fg` / `--fc-captions-bottom` | Caption line |
97
+ | `--fc-btn-border` / `--fc-btn-hover-bg` | Text button chrome |
98
+ | `--fc-btn-read-bg` / `--fc-btn-read-fg` | Read button fill |
99
+ | `--fc-btn-prev-image` / `--fc-btn-next-image` / `--fc-btn-read-image` | `url("…")` for image buttons |
100
+ | `--fc-btn-image-size` | Hit target when using `.fc-chrome--images` |
101
+
102
+ Prev/next disable at the first/last spread (`disabled` + `.is-disabled`).
103
+
104
+ ## Editor mode
105
+
106
+ Pass `editor: true` to mount the corner **Edit** / **Preview** toggle. While editing, visible page leaves become [Fabric.js](http://fabricjs.com/) canvases (text/image blocks). Toolbar actions: add/remove page, front/back cover flags, hardback, and **Download book** (packs a `.fanci` ZIP via `packFanci`). Hotspots are preserved but not Fabric-editable. Hosts should gate the flag so production builds stay reader-only:
107
+
108
+ ```ts
109
+ await Storybook.create(el, {
110
+ story,
111
+ baseUrl: './stories/demo/',
112
+ editor: import.meta.env.DEV, // Vite: never true in `vite build`
113
+ });
114
+
115
+ // Or programmatically:
116
+ await book.enterEditor();
117
+ await book.downloadFanci(); // `{story.id}.fanci`
118
+ await book.exitEditor();
119
+ ```
120
+
121
+ `fabric` is a dependency of `@makefully/fancifully` and loads via dynamic `import('fabric')` only when edit mode is entered.
122
+
123
+ ### Drag & drop (edit mode)
124
+
125
+ | Drop | Result |
126
+ |------|--------|
127
+ | Font (`.woff2` / `.woff` / `.ttf` / `.otf`) on empty page | Sets the default text font and applies it to all textboxes; registered in `story.fonts` for `.fanci` export |
128
+ | Font on a textbox | Changes only that textbox’s `fontFamily` (still packed into `.fanci`) |
129
+ | Image (png/jpeg/gif/webp/svg/…) | Places a new image block on the canvas at the drop point |
130
+ | Text (`text/plain`, `text/html`, or `.txt`) | Creates a new textbox with that content |
131
+
132
+ Dropped fonts/images are stored as zip-relative paths under `fonts/` / `assets/` and included when you **Download book**.
133
+
134
+ ## Embed with SpringRoll (Platypus-like)
135
+
136
+ ```ts
137
+ import { Application } from 'springroll';
138
+ import { Storybook } from '@makefully/fancifully';
139
+ import '@makefully/fancifully/fancifully.css';
140
+
141
+ const app = new Application({
142
+ features: {
143
+ sound: true,
144
+ soundVolume: true,
145
+ vo: true,
146
+ voVolume: true,
147
+ sfx: true,
148
+ captions: true,
149
+ },
150
+ });
151
+
152
+ const book = await Storybook.create(container, {
153
+ story: myStoryObject, // or URL
154
+ baseUrl: '/books/hill/',
155
+ springroll: app,
156
+ });
157
+
158
+ book.on('pagechange', ({ pageIds, index, layoutMode }) => {
159
+ console.log(pageIds, index, layoutMode);
160
+ });
161
+ ```
162
+
163
+ 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.
164
+
165
+ While loading, Fancifully reports:
166
+
167
+ | Bellhop event | Payload |
168
+ |---------------|---------|
169
+ | `progress` | `number` 0–1 (classic Container loading bar) |
170
+ | `loading` | `{ stage, progress, count?, total?, detail? }` |
171
+
172
+ ```ts
173
+ await Storybook.create(el, {
174
+ story: './book.fanci',
175
+ onProgress: ({ stage, progress }) => console.log(stage, progress),
176
+ });
177
+ ```
178
+
179
+ ## Story formats
180
+
181
+ | Input | Extension | Notes |
182
+ |-------|-----------|--------|
183
+ | Fancifully JSON | `.json` | Full fidelity; `baseUrl` resolves relative assets |
184
+ | Fancifully package | **`.fanci`** | ZIP of `story.json` + images/audio/vtt/fonts (relative paths). (`.fan` is already used by other software.) |
185
+ | EPUB | `.epub` | Import subset: spine pages, images, fonts/audio when present, Media Overlays → cues. No hotspots. |
186
+
187
+ ```ts
188
+ // Packaged book
189
+ await Storybook.create(el, { story: './tales/hill.fanci' });
190
+
191
+ // EPUB (read-aloud if Media Overlays exist)
192
+ await Storybook.create(el, { story: fileInput.files[0], storyName: fileInput.files[0].name });
193
+ ```
194
+
195
+ Pack a folder into `.fanci`:
196
+
197
+ ```bash
198
+ npm run pack:fanci -- path/to/story-dir [out.fanci]
199
+ # or: node scripts/pack-fanci.mjs path/to/story-dir out.fanci
200
+ ```
201
+
202
+ ## Story JSON
203
+
204
+ Stories are JSON packages (not a single HTML document). Text may embed HTML; images/audio/vtt are asset references.
205
+
206
+ | Field | Purpose |
207
+ |-------|---------|
208
+ | `pageSize` | Authoring pixel size per leaf |
209
+ | `frontCover` | If true, first page is a closed cover (centered); opens with a tween; no blank to its left |
210
+ | `backCover` | If true, last page is a back cover (no blank to its right); can close centered at the end |
211
+ | `hardback` | If true (with a cover flag), cover boards are larger than interior pages so open spreads show a cover rim |
212
+ | `layout.mode` | `single` (one-page) \| `two-page` \| `responsive` (orientation) \| `auto` (width breakpoint) |
213
+ | `layout.singleBreakpoint` | Width where `auto` switches to two-page |
214
+ | `assets` | Map of image / audio / vtt / html |
215
+ | `pages[].blocks` | `text`, `image`, `hotspot` with `layout` boxes |
216
+ | `pages[].readAloud` | `{ audio, cues }` — cues are a VTT asset id or inline `{id,start,end}[]` |
217
+
218
+ ### Layout modes
219
+
220
+ - **Always** a left+right spread under the hood (blank mates keep flip geometry).
221
+ - **`two-page`**: facing pairs — cover `[blank, p0]`, then `[p1, p2]`, …
222
+ - **`single` (one-page)**: one story page per spread with a blank mate (about 2× as many spreads). Blank leaf stays offscreen; same flip animation.
223
+ - **`responsive`**: landscape (width ≥ height) → two-page; portrait → single. Remaps to the same content page instantly when orientation changes.
224
+ - **`auto`**: legacy width breakpoint (`singleBreakpoint`).
225
+
226
+ When the resolved mode flips, Fancifully rebuilds spreads and jumps to the spread that contains the current page (no page-turn animation).
227
+
228
+ ### Covers (`frontCover` / `backCover` / `hardback`)
229
+
230
+ - **Unset (default):** book starts open with a blank mate beside the first page (`[blank, p0]`) and a trailing blank after an orphan last page.
231
+ - **`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.
232
+ - **`backCover: true`:** last page is omitted from open spreads; Next from the last interior spread **page-flips** to a centered back cover.
233
+ - **`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.
234
+
235
+ ### VO ↔ text
236
+
237
+ 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`.
238
+
239
+ ## Scripts
240
+
241
+ ```bash
242
+ npm install
243
+ npm test
244
+ npm run dev # demo app (Vite)
245
+ npm run build # dist library + types
246
+ ```
247
+
248
+ ## License
249
+
250
+ MIT
@@ -1,8 +1,25 @@
1
+ import type { FlipStyleInput } from './flip/index.js';
1
2
  import type { StorySource } from './load/packageTypes.js';
2
3
  import { type PagerEvents } from './nav/Pager.js';
3
4
  import type { LayoutMode, Story } from './schema/story.js';
4
5
  import { type SpringrollLike } from './springroll/bindApplication.js';
5
6
  import { type LoadProgress } from './springroll/loading.js';
7
+ export type StorybookChromeOptions = {
8
+ /** Hide built-in chrome (host can call next/prev/playReadAloud). */
9
+ hidden?: boolean;
10
+ /** Extra class(es) on `.fc-chrome` (e.g. `goldipup-chrome fc-chrome--images`). */
11
+ className?: string;
12
+ labels?: {
13
+ prev?: string;
14
+ read?: string;
15
+ next?: string;
16
+ };
17
+ ariaLabels?: {
18
+ prev?: string;
19
+ read?: string;
20
+ next?: string;
21
+ };
22
+ };
6
23
  export type StorybookOptions = {
7
24
  /** JSON URL/object, `.fanci` / `.epub` URL, or File/Blob/ArrayBuffer */
8
25
  story: StorySource | Story;
@@ -14,6 +31,20 @@ export type StorybookOptions = {
14
31
  autoPlayReadAloud?: boolean;
15
32
  /** Extra progress listener (SpringRoll Container also receives progress/loading). */
16
33
  onProgress?: (progress: LoadProgress) => void;
34
+ /** Built-in Prev / Read / Next chrome labels and visibility. */
35
+ chrome?: StorybookChromeOptions;
36
+ /**
37
+ * Page-flip style: registered id (`"default"`), a {@link FlipStyle} subclass,
38
+ * or an instance. Host setting (not part of story JSON).
39
+ */
40
+ flipStyle?: FlipStyleInput;
41
+ /** Flip duration in milliseconds. Host setting (not part of story JSON). */
42
+ flipSpeed?: number;
43
+ /**
44
+ * When true, mount editor chrome (Edit toggle, page CRUD, cover flags, Download .fanci).
45
+ * Does not start in edit mode. Hosts should gate with their prod flag (e.g. `import.meta.env.DEV`).
46
+ */
47
+ editor?: boolean;
17
48
  };
18
49
  type StorybookEvents = PagerEvents & {
19
50
  ready: {
@@ -40,22 +71,59 @@ export declare class Storybook {
40
71
  private resizeObserver;
41
72
  private listeners;
42
73
  private destroyed;
74
+ private btnPrev;
75
+ private btnRead;
76
+ private btnNext;
77
+ private editorEnabled;
78
+ private editing;
79
+ private chromeHiddenByOptions;
80
+ private editorChrome;
81
+ private pageCanvases;
82
+ private editorMounting;
83
+ /** Zip-relative paths → bytes for assets/fonts added during edit (for packFanci). */
84
+ private editorFiles;
85
+ /** Default font family for new textboxes (set by dropping a font on empty canvas). */
86
+ private editorDefaultFontFamily;
43
87
  private constructor();
44
88
  static create(container: HTMLElement, options: StorybookOptions): Promise<Storybook>;
45
89
  get story(): Story;
46
90
  get layoutMode(): import("./schema/story.js").ResolvedLayoutMode;
47
91
  get pageIds(): string[];
48
92
  get spreadIndex(): number;
93
+ get isEditing(): boolean;
49
94
  on<K extends keyof StorybookEvents>(event: K, fn: Listener<K>): () => void;
50
95
  next(): Promise<void>;
51
96
  prev(): Promise<void>;
52
97
  goTo(pageId: string): Promise<void>;
53
98
  setLayoutMode(mode: LayoutMode): void;
99
+ /** Swap page-flip implementation at runtime (id, subclass, or instance). */
100
+ setFlipStyle(style: FlipStyleInput): void;
101
+ /** Set flip duration in milliseconds. */
102
+ setFlipSpeed(speedMs: number): void;
54
103
  playReadAloud(): Promise<void>;
55
104
  pause(): void;
56
105
  resume(): void;
106
+ /** Enter Fabric edit mode (requires `editor: true` in options). */
107
+ enterEditor(): Promise<void>;
108
+ /** Commit canvases and restore normal PageView rendering. */
109
+ exitEditor(): Promise<void>;
110
+ /** Commit current edits, pack `.fanci`, and trigger a browser download. */
111
+ downloadFanci(filename?: string): Promise<void>;
57
112
  destroy(): void;
113
+ private navigate;
114
+ private mountEditorChrome;
115
+ private syncEditorChromeState;
116
+ private editorHost;
117
+ private mountEditorCanvases;
118
+ private commitEditorCanvases;
119
+ private destroyEditorCanvases;
120
+ private editorAddPage;
121
+ private editorRemovePage;
122
+ private editorSetFrontCover;
123
+ private editorSetBackCover;
124
+ private editorSetHardback;
58
125
  private wireChrome;
126
+ private syncChromeNavState;
59
127
  private wirePager;
60
128
  private wireSpringroll;
61
129
  private wireResize;
@@ -1 +1 @@
1
- {"version":3,"file":"Storybook.d.ts","sourceRoot":"","sources":["../src/Storybook.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Storybook.d.ts","sourceRoot":"","sources":["../src/Storybook.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,33 @@
1
+ export type EditorChromeHandlers = {
2
+ onToggleEdit: () => void;
3
+ onAddPage: () => void;
4
+ onRemovePage: () => void;
5
+ onFrontCoverChange: (enabled: boolean) => void;
6
+ onBackCoverChange: (enabled: boolean) => void;
7
+ onHardbackChange: (enabled: boolean) => void;
8
+ onDownload: () => void;
9
+ };
10
+ export type EditorChromeState = {
11
+ editing: boolean;
12
+ frontCover: boolean;
13
+ backCover: boolean;
14
+ hardback: boolean;
15
+ canRemovePage: boolean;
16
+ };
17
+ /**
18
+ * Corner Edit / Preview toggle + toolbar (add/remove page, cover toggles, download).
19
+ */
20
+ export declare class EditorChrome {
21
+ readonly element: HTMLElement;
22
+ private toggleBtn;
23
+ private toolbar;
24
+ private frontCoverInput;
25
+ private backCoverInput;
26
+ private hardbackInput;
27
+ private removeBtn;
28
+ private handlers;
29
+ constructor(handlers: EditorChromeHandlers);
30
+ setState(state: EditorChromeState): void;
31
+ destroy(): void;
32
+ }
33
+ //# sourceMappingURL=EditorChrome.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"EditorChrome.d.ts","sourceRoot":"","sources":["../../src/editor/EditorChrome.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,iBAAiB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC9C,gBAAgB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,eAAe,CAAmB;IAC1C,OAAO,CAAC,cAAc,CAAmB;IACzC,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,QAAQ,EAAE,oBAAoB;IAkE1C,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAWxC,OAAO,IAAI,IAAI;CAGhB"}