squiffy-runtime 7.0.0-beta.1 → 7.0.0-beta.11

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 (111) hide show
  1. package/dist/assets.d.ts +1 -0
  2. package/dist/classes.test.d.ts +1 -0
  3. package/dist/confirmDialog.d.ts +8 -0
  4. package/dist/events.d.ts +12 -0
  5. package/dist/every.d.ts +12 -0
  6. package/dist/every.test.d.ts +1 -0
  7. package/dist/helpers.test.d.ts +1 -0
  8. package/dist/numbers.d.ts +3 -0
  9. package/dist/panels.d.ts +14 -0
  10. package/dist/panels.test.d.ts +1 -0
  11. package/dist/paths.d.ts +15 -0
  12. package/dist/paths.test.d.ts +1 -0
  13. package/dist/persistent.test.d.ts +1 -0
  14. package/dist/playerSettings.d.ts +17 -0
  15. package/dist/preview-host.d.ts +7 -3
  16. package/dist/preview-host.js +47 -5
  17. package/dist/preview-host.js.map +2 -2
  18. package/dist/preview-html.js +1 -1
  19. package/dist/preview-protocol.d.ts +16 -0
  20. package/dist/preview.d.ts +1 -0
  21. package/dist/saveSlots.d.ts +16 -0
  22. package/dist/saves.test.d.ts +1 -0
  23. package/dist/savesDialog.d.ts +43 -0
  24. package/dist/savesDialog.test.d.ts +1 -0
  25. package/dist/scripts.test.d.ts +1 -0
  26. package/dist/settings.test.d.ts +1 -0
  27. package/dist/settingsDialog.d.ts +17 -0
  28. package/dist/skill.test.d.ts +1 -0
  29. package/dist/sound.d.ts +35 -0
  30. package/dist/sound.test.d.ts +1 -0
  31. package/dist/squiffy.page.css +155 -0
  32. package/dist/squiffy.preview.html +1469 -136
  33. package/dist/squiffy.runtime.css +1123 -20
  34. package/dist/squiffy.runtime.d.ts +13 -1
  35. package/dist/squiffy.runtime.global.js +144 -79
  36. package/dist/squiffy.runtime.global.js.map +1 -1
  37. package/dist/squiffy.runtime.js +6771 -4424
  38. package/dist/squiffy.runtime.js.map +1 -1
  39. package/dist/state.d.ts +17 -0
  40. package/dist/storyLists.d.ts +4 -0
  41. package/dist/storyLists.test.d.ts +1 -0
  42. package/dist/style.test.d.ts +1 -0
  43. package/dist/textProcessor.d.ts +27 -0
  44. package/dist/transitions.test.d.ts +1 -0
  45. package/dist/types.d.ts +125 -0
  46. package/dist/types.plugins.d.ts +1 -0
  47. package/dist/uiLinks.test.d.ts +1 -0
  48. package/dist/utils.d.ts +2 -1
  49. package/dist/utils.test.d.ts +1 -0
  50. package/package.json +11 -6
  51. package/src/__snapshots__/squiffy.runtime.test.ts.snap +22 -22
  52. package/src/animation.test.ts +44 -0
  53. package/src/animation.ts +9 -5
  54. package/src/assets.test.ts +1 -3
  55. package/src/assets.ts +1 -1
  56. package/src/classes.test.ts +201 -0
  57. package/src/confirmDialog.ts +66 -0
  58. package/src/events.ts +19 -0
  59. package/src/every.test.ts +25 -0
  60. package/src/every.ts +94 -0
  61. package/src/helpers.test.ts +34 -0
  62. package/src/numbers.ts +21 -0
  63. package/src/panels.test.ts +225 -0
  64. package/src/panels.ts +187 -0
  65. package/src/paths.test.ts +66 -0
  66. package/src/paths.ts +155 -0
  67. package/src/persistent.test.ts +155 -0
  68. package/src/playerSettings.ts +128 -0
  69. package/src/pluginManager.ts +1 -0
  70. package/src/plugins/animate.ts +28 -4
  71. package/src/plugins/live.ts +18 -5
  72. package/src/plugins/plugins.test.ts +93 -6
  73. package/src/plugins/replaceLabel.ts +7 -3
  74. package/src/preview-host.test.ts +97 -1
  75. package/src/preview-host.ts +71 -10
  76. package/src/preview-protocol.ts +25 -3
  77. package/src/preview.main.ts +1 -0
  78. package/src/preview.test.ts +203 -4
  79. package/src/preview.ts +178 -12
  80. package/src/saveSlots.ts +159 -0
  81. package/src/saves.test.ts +199 -0
  82. package/src/savesDialog.test.ts +290 -0
  83. package/src/savesDialog.ts +499 -0
  84. package/src/scripts.test.ts +130 -0
  85. package/src/settings.test.ts +233 -0
  86. package/src/settingsDialog.ts +160 -0
  87. package/src/skill.test.ts +67 -0
  88. package/src/sound.test.ts +273 -0
  89. package/src/sound.ts +207 -0
  90. package/src/squiffy.page.css +155 -0
  91. package/src/squiffy.runtime.css +1123 -20
  92. package/src/squiffy.runtime.test.ts +2806 -44
  93. package/src/squiffy.runtime.ts +1111 -64
  94. package/src/state.ts +172 -11
  95. package/src/storyLists.test.ts +134 -0
  96. package/src/storyLists.ts +57 -0
  97. package/src/style.test.ts +89 -0
  98. package/src/textProcessor.ts +739 -58
  99. package/src/transitions.test.ts +343 -0
  100. package/src/types.plugins.ts +3 -0
  101. package/src/types.ts +209 -1
  102. package/src/uiLinks.test.ts +156 -0
  103. package/src/updater.ts +26 -8
  104. package/src/utils.test.ts +60 -0
  105. package/src/utils.ts +46 -14
  106. package/vite.config.ts +3 -4
  107. package/vite.preview.config.ts +16 -5
  108. package/dist/infixExpressions.d.ts +0 -2
  109. package/src/infixExpressions.test.ts +0 -187
  110. package/src/infixExpressions.ts +0 -323
  111. /package/dist/{infixExpressions.test.d.ts → animation.test.d.ts} +0 -0
@@ -0,0 +1,343 @@
1
+ // @transition (#489): how a section or passage appears
2
+ import { expect, test, beforeEach, afterEach, vi } from "vitest";
3
+ import globalJsdom from "global-jsdom";
4
+ import { init } from "./squiffy.runtime.js";
5
+ import { compile as squiffyCompile } from "squiffy-compiler";
6
+
7
+ let cleanup: () => void;
8
+
9
+ beforeEach(() => {
10
+ cleanup = globalJsdom("<!DOCTYPE html><html><body><div id=\"squiffy\"></div></body></html>");
11
+ vi.useFakeTimers();
12
+ });
13
+
14
+ afterEach(() => {
15
+ vi.useRealTimers();
16
+ localStorage.clear();
17
+ cleanup();
18
+ });
19
+
20
+ const start = async (script: string, options: { persist?: boolean } = {}) => {
21
+ const result = await squiffyCompile({ script });
22
+ if (!result.success) throw new Error("Compile failed");
23
+ const story = {
24
+ ...result.output.story,
25
+ js: result.output.js.map(lines => new Function("squiffy", "get", "set", lines.join("\n"))) as any,
26
+ };
27
+ const element = document.getElementById("squiffy")!;
28
+ const api = await init({ element, story, persist: options.persist ?? false, storyId: "test", scroll: "none" });
29
+ await api.begin();
30
+ return { api, element };
31
+ };
32
+
33
+ const click = async (element: HTMLElement, text: string) => {
34
+ const link = [...element.querySelectorAll<HTMLElement>("a.squiffy-link")]
35
+ .find(l => l.textContent == text && !l.classList.contains("disabled"));
36
+ if (!link) throw new Error(`No link "${text}"`);
37
+ link.click();
38
+ await vi.runAllTimersAsync();
39
+ };
40
+
41
+ const sectionElement = (element: HTMLElement, name: string) =>
42
+ element.querySelector<HTMLElement>(`.squiffy-output-section[data-section="${name}"]`)!;
43
+
44
+ const passageElement = (element: HTMLElement, name: string) =>
45
+ element.querySelector<HTMLElement>(`.squiffy-output-passage[data-passage="${name}"]`)!;
46
+
47
+ // What a transition puts on an element while it plays
48
+ const transition = (el: HTMLElement) => el.classList.contains("squiffy-transition")
49
+ ? { name: el.getAttribute("data-transition"), time: el.style.getPropertyValue("--squiffy-transition-time") }
50
+ : null;
51
+
52
+ const story = `
53
+ [[forest]]:
54
+ @transition fade
55
+ The forest. [[Go to the cave]](cave), [look up], [listen]
56
+
57
+ [look up]:
58
+ @transition zoom 300ms
59
+ The stars are out.
60
+
61
+ [listen]:
62
+ Owls.
63
+
64
+ [[cave]]:
65
+ @transition slide-up 1.5s
66
+ @clear
67
+ The cave. [[Leave]](outside)
68
+
69
+ [[outside]]:
70
+ Outside.
71
+ `;
72
+
73
+ test("A section's transition plays as it appears, with its time", async () => {
74
+ const { element } = await start(story);
75
+ expect(transition(sectionElement(element, "forest"))).toEqual({ name: "fade", time: "" });
76
+ expect(sectionElement(element, "forest").classList).toContain("fade");
77
+
78
+ await click(element, "Go to the cave");
79
+ expect(transition(sectionElement(element, "cave"))).toEqual({ name: "slide-up", time: "1500ms" });
80
+
81
+ await click(element, "Leave");
82
+ expect(transition(sectionElement(element, "outside"))).toBeNull();
83
+ });
84
+
85
+ test("A passage has its own transition, or else its section's", async () => {
86
+ const { element } = await start(story);
87
+ await click(element, "look up");
88
+ expect(transition(passageElement(element, "look up"))).toEqual({ name: "zoom", time: "300ms" });
89
+
90
+ await click(element, "listen");
91
+ expect(transition(passageElement(element, "listen"))).toEqual({ name: "fade", time: "" });
92
+ });
93
+
94
+ test("The master section's transition is for every section, unless one has @transition none", async () => {
95
+ const { element } = await start(`
96
+ [[]]:
97
+ @transition blur 1s
98
+
99
+ [[a]]:
100
+ A. [[b]] [p]
101
+
102
+ [p]:
103
+ P.
104
+
105
+ [[b]]:
106
+ @transition none
107
+ B.
108
+ `);
109
+ expect(transition(sectionElement(element, "a"))).toEqual({ name: "blur", time: "1000ms" });
110
+ await click(element, "p");
111
+ expect(transition(passageElement(element, "p"))).toEqual({ name: "blur", time: "1000ms" });
112
+ await click(element, "b");
113
+ expect(transition(sectionElement(element, "b"))).toBeNull();
114
+ });
115
+
116
+ test("The transition's class comes off when it ends", async () => {
117
+ const { element } = await start(story);
118
+ const forest = sectionElement(element, "forest");
119
+ // An animation in the text doesn't end the section's transition
120
+ forest.querySelector("p, div")!.dispatchEvent(new window.Event("animationend", { bubbles: true }));
121
+ expect(transition(forest)).not.toBeNull();
122
+
123
+ forest.dispatchEvent(new window.Event("animationend", { bubbles: true }));
124
+ expect(transition(forest)).toBeNull();
125
+ expect(forest.classList).not.toContain("fade");
126
+ expect(forest.hasAttribute("style")).toBe(false);
127
+ });
128
+
129
+ test("Going back past @clear doesn't play the transition again", async () => {
130
+ const { api, element } = await start(story);
131
+ await click(element, "Go to the cave");
132
+ api.goBack();
133
+ await vi.runAllTimersAsync();
134
+ expect(transition(sectionElement(element, "forest"))).toBeNull();
135
+ });
136
+
137
+ test("A saved game doesn't play the transitions again when it's loaded", async () => {
138
+ const first = await start(story, { persist: true });
139
+ await click(first.element, "Go to the cave");
140
+ expect(transition(sectionElement(first.element, "cave"))).not.toBeNull();
141
+ first.api.dispose();
142
+ first.element.innerHTML = "";
143
+
144
+ const second = await start(story, { persist: true });
145
+ expect(sectionElement(second.element, "cave")).not.toBeNull();
146
+ expect(second.element.querySelector(".squiffy-transition")).toBeNull();
147
+ });
148
+
149
+ // @leave: how the old text goes when the screen is cleared
150
+
151
+ // So the leave transitions have an animation, which jsdom doesn't play: it's ended by hand
152
+ const animateLeaving = () => {
153
+ const style = document.createElement("style");
154
+ style.textContent = ".squiffy-leave { animation-name: leaving; animation-duration: 1s; }";
155
+ document.head.appendChild(style);
156
+ };
157
+
158
+ const clickWithoutWaiting = async (element: HTMLElement, text: string) => {
159
+ const link = [...element.querySelectorAll<HTMLElement>("a.squiffy-link")]
160
+ .find(l => l.textContent == text && !l.classList.contains("disabled"));
161
+ if (!link) throw new Error(`No link "${text}"`);
162
+ link.click();
163
+ await vi.advanceTimersByTimeAsync(0);
164
+ };
165
+
166
+ const leaving = (el: HTMLElement) => el.classList.contains("squiffy-leave")
167
+ ? { name: el.getAttribute("data-transition"), time: el.style.getPropertyValue("--squiffy-transition-time") }
168
+ : null;
169
+
170
+ const leaveStory = `
171
+ [[forest]]:
172
+ The forest. [[Go to the cave]](cave), [look up]
173
+
174
+ [look up]:
175
+ The stars are out.
176
+
177
+ [[cave]]:
178
+ @clear
179
+ @leave blur 2s
180
+ The cave. [listen]
181
+
182
+ [listen]:
183
+ @clear
184
+ Water dripping. [[Leave]](outside)
185
+
186
+ [[outside]]:
187
+ @clear
188
+ @leave none
189
+ Outside.
190
+ `;
191
+
192
+ test("The old text plays the leave transition before the screen is cleared", async () => {
193
+ animateLeaving();
194
+ const { api, element } = await start(leaveStory);
195
+ await click(element, "look up");
196
+ await clickWithoutWaiting(element, "Go to the cave");
197
+
198
+ // Everything on the screen is leaving, and the cave isn't there yet
199
+ const forest = sectionElement(element, "forest");
200
+ expect(leaving(forest)).toEqual({ name: "blur", time: "2000ms" });
201
+ expect(forest.classList).toContain("squiffy-transition");
202
+ expect(sectionElement(element, "cave")).toBeNull();
203
+ // Back waits for it
204
+ api.goBack();
205
+ await vi.advanceTimersByTimeAsync(0);
206
+ expect(leaving(forest)).not.toBeNull();
207
+ expect(passageElement(element, "look up")).not.toBeNull();
208
+
209
+ forest.dispatchEvent(new window.Event("animationend", { bubbles: true }));
210
+ await vi.runAllTimersAsync();
211
+ expect(sectionElement(element, "cave")).not.toBeNull();
212
+ // The old text is put away as it was, for going back
213
+ const putAway = element.querySelector<HTMLElement>(".squiffy-clear-stack .squiffy-output-section")!;
214
+ expect(putAway.getAttribute("data-section")).toBe("forest");
215
+ expect(putAway.classList).not.toContain("squiffy-leave");
216
+ expect(putAway.hasAttribute("style")).toBe(false);
217
+ });
218
+
219
+ test("A passage that clears the screen uses its section's leave transition, and @leave none plays none", async () => {
220
+ animateLeaving();
221
+ const { element } = await start(leaveStory);
222
+ await click(element, "Go to the cave");
223
+
224
+ await clickWithoutWaiting(element, "listen");
225
+ expect(leaving(sectionElement(element, "cave"))).toEqual({ name: "blur", time: "2000ms" });
226
+ await vi.runAllTimersAsync();
227
+ expect(passageElement(element, "listen")).not.toBeNull();
228
+
229
+ await clickWithoutWaiting(element, "Leave");
230
+ expect(sectionElement(element, "outside")).not.toBeNull();
231
+ });
232
+
233
+ test("The story goes on if the leave transition never ends", async () => {
234
+ animateLeaving();
235
+ const { element } = await start(leaveStory);
236
+ await clickWithoutWaiting(element, "Go to the cave");
237
+ await vi.advanceTimersByTimeAsync(1500);
238
+ expect(sectionElement(element, "cave")).toBeNull();
239
+ // Its 1s animation, and a second more
240
+ await vi.advanceTimersByTimeAsync(600);
241
+ expect(sectionElement(element, "cave")).not.toBeNull();
242
+ });
243
+
244
+ test("Without an animation for it, the leave transition doesn't hold the story up", async () => {
245
+ const { element } = await start(leaveStory);
246
+ await clickWithoutWaiting(element, "Go to the cave");
247
+ expect(sectionElement(element, "cave")).not.toBeNull();
248
+ });
249
+
250
+ test("Going back brings the old text back as it was", async () => {
251
+ animateLeaving();
252
+ const { api, element } = await start(leaveStory);
253
+ await click(element, "Go to the cave");
254
+ api.goBack();
255
+ await vi.runAllTimersAsync();
256
+ const forest = sectionElement(element, "forest");
257
+ expect(leaving(forest)).toBeNull();
258
+ expect(transition(forest)).toBeNull();
259
+ expect(sectionElement(element, "cave")).toBeNull();
260
+ });
261
+
262
+ test("The master section's leave transition is for every section that clears the screen", async () => {
263
+ animateLeaving();
264
+ const { element } = await start(`
265
+ [[]]:
266
+ @leave fade
267
+
268
+ [[a]]:
269
+ A. [[b]]
270
+
271
+ [[b]]:
272
+ @clear
273
+ B.
274
+ `);
275
+ await clickWithoutWaiting(element, "b");
276
+ expect(leaving(sectionElement(element, "a"))).toEqual({ name: "fade", time: "" });
277
+ });
278
+
279
+ test("{{clear}} plays the leave transition, then the new text's own transition", async () => {
280
+ // https://github.com/textadventures/squiffy/issues/524
281
+ animateLeaving();
282
+ const { element } = await start(`
283
+ [[a]]:
284
+ A. [[b]], [[c]]
285
+
286
+ [[b]]:
287
+ @leave blur 2s
288
+ @transition fade
289
+ {{clear}}B. [look]
290
+
291
+ [look]:
292
+ @transition zoom
293
+ @leave slide-up
294
+ {{clear}}Looking.
295
+
296
+ [[c]]:
297
+ C.
298
+ `);
299
+ await clickWithoutWaiting(element, "b");
300
+ // The old text is leaving, and the new text isn't there yet
301
+ expect(leaving(sectionElement(element, "a"))).toEqual({ name: "blur", time: "2000ms" });
302
+ expect(sectionElement(element, "b").textContent).toBe("");
303
+ sectionElement(element, "a").dispatchEvent(new window.Event("animationend", { bubbles: true }));
304
+ await vi.advanceTimersByTimeAsync(0);
305
+ const b = sectionElement(element, "b");
306
+ expect(b.textContent).toContain("B.");
307
+ expect(transition(b)).toEqual({ name: "fade", time: "" });
308
+ expect(element.querySelector(".squiffy-clear-stack [data-section='a']")).not.toBeNull();
309
+
310
+ // In a passage, the passage's own transitions
311
+ await clickWithoutWaiting(element, "look");
312
+ expect(leaving(sectionElement(element, "b"))).toEqual({ name: "slide-up", time: "" });
313
+ await vi.runAllTimersAsync();
314
+ const look = passageElement(element, "look");
315
+ expect(look.textContent).toBe("Looking.");
316
+ expect(transition(look)).toEqual({ name: "zoom", time: "" });
317
+ expect(element.querySelectorAll(".squiffy-clear-stack .squiffy-output-passage")).toHaveLength(0);
318
+ });
319
+
320
+ test("A slide moves the way it's named, arriving or leaving", async () => {
321
+ const { readFileSync } = await import("fs");
322
+ const style = document.createElement("style");
323
+ style.textContent = readFileSync(new URL("./squiffy.runtime.css", import.meta.url), "utf8");
324
+ document.head.appendChild(style);
325
+
326
+ const animation = (classes: string) => {
327
+ const el = document.createElement("div");
328
+ el.className = classes;
329
+ document.body.appendChild(el);
330
+ const computed = getComputedStyle(el);
331
+ const result = `${computed.animationName} ${computed.animationDirection || "normal"}`;
332
+ el.remove();
333
+ return result;
334
+ };
335
+ // Arriving, slide-left comes in from the right, and leaving, goes off to the left, by playing
336
+ // the animation from the left backwards
337
+ expect(animation("squiffy-transition slide-left")).toBe("squiffy-transition-from-right normal");
338
+ expect(animation("squiffy-transition squiffy-leave slide-left")).toBe("squiffy-transition-from-left reverse");
339
+ expect(animation("squiffy-transition slide-up")).toBe("squiffy-transition-from-below normal");
340
+ expect(animation("squiffy-transition squiffy-leave slide-up")).toBe("squiffy-transition-from-above reverse");
341
+ // Others play backwards to leave
342
+ expect(animation("squiffy-transition squiffy-leave zoom")).toBe("squiffy-transition-zoom reverse");
343
+ });
@@ -27,6 +27,9 @@ export interface PluginHost {
27
27
  // processText. Returns the HTML unchanged if no resolveAssetUrl was given.
28
28
  resolveAssetsInHtml: (html: string) => string;
29
29
  addTransition: (fn: () => Promise<void>) => void;
30
+ // Runs the plugins' onWrite on HTML a plugin has put in the output itself, so that what's in
31
+ // it works as it would in any other text, e.g. an {{#animate}} starts
32
+ written: (el: HTMLElement) => void;
30
33
  animation: Animation;
31
34
  on<E extends keyof SquiffyEventMap>(
32
35
  event: E,
package/src/types.ts CHANGED
@@ -14,6 +14,18 @@ export interface SquiffyInitOptions {
14
14
  * left alone. When not provided, paths are used as they are.
15
15
  */
16
16
  resolveAssetUrl?: (path: string) => string,
17
+ /**
18
+ * The page's text, for a story in another language: squiffy.json's "strings", by the same
19
+ * names. Used for the text of {{restart}} and {{saves}} links (#452), and the dialogs they
20
+ * open when the page doesn't handle them itself. Anything left out is in English.
21
+ */
22
+ strings?: Partial<Record<string, string>>,
23
+ /**
24
+ * The values of the story's persistent attributes (squiffy.json's "persistent", #539) to start
25
+ * with, in place of those kept in the browser: e.g. the CLI's --play carrying them from one run
26
+ * to the next. getPersistent() gives them back.
27
+ */
28
+ persistent?: Record<string, unknown>,
17
29
  }
18
30
 
19
31
  export interface SquiffySettings {
@@ -39,6 +51,42 @@ export interface SquiffyApi {
39
51
  clickLink: (link: HTMLElement) => Promise<boolean>;
40
52
  update: (story: Story) => void;
41
53
  goBack: () => void;
54
+ // Whether goBack() would go anywhere, e.g. to enable a Back button. canGoBackChanged says when it changes.
55
+ canGoBack: () => boolean;
56
+ // The game as it is now, to keep and load again later with loadSave()
57
+ getSave: () => SavedGame;
58
+ // Carries on from a saved game, in place of the game as it is now. A save from a different
59
+ // story (by its squiffy.json "id") isn't loaded.
60
+ loadSave: (save: SavedGame) => Promise<LoadSaveResult>;
61
+ // A passage in the master section [[]], rendered as HTML with the attributes as they are now,
62
+ // for a panel beside the story or a dialog (#14, #443). It changes nothing: {{set}} and the
63
+ // like are ignored, its @set and JavaScript don't run, and its links are disabled.
64
+ renderPassage: (name: string) => string;
65
+ // Whether the story's music and sounds are muted (#444). It's remembered for the story when
66
+ // persist is on, like the light or dark theme.
67
+ isMuted: () => boolean;
68
+ setMuted: (muted: boolean) => void;
69
+ // Whether the story plays music or sounds: it names some files, or has played one. The
70
+ // "sound" event says when something plays.
71
+ usesSound: () => boolean;
72
+ // The story's player settings (squiffy.json's "settings", #452), which the Settings dialog shows
73
+ getSettings: () => PlayerSetting[];
74
+ // A setting's value, as the story reads it with settings.name: its default if the player
75
+ // hasn't changed it
76
+ getSetting: (name: string) => SettingValue | null;
77
+ // Changes a setting, as the player does in the Settings dialog. A value that isn't one the
78
+ // setting can have is ignored. It's remembered for the story when persist is on, and going
79
+ // back, restarting or loading a saved game doesn't change it.
80
+ setSetting: (name: string, value: SettingValue) => void;
81
+ // Puts every setting back to its default
82
+ resetSettings: () => void;
83
+ // The values of the story's persistent attributes (squiffy.json's "persistent", #539), by
84
+ // name: those the story has set. They aren't in getSave(), as loading a game leaves them alone.
85
+ getPersistent: () => Record<string, unknown>;
86
+ // Clears persistent attributes, as {{forget}} does: the ones named, or all of them
87
+ forget: (names?: string[]) => void;
88
+ // Stops the story's music and sounds for good, when it's being replaced, e.g. in the editor's preview
89
+ dispose: () => void;
42
90
 
43
91
  on<E extends keyof SquiffyEventMap>(
44
92
  event: E,
@@ -56,6 +104,41 @@ export interface SquiffyApi {
56
104
  ): () => void;
57
105
  }
58
106
 
107
+ // The events a story's own scripts can listen for (#528). The others are for the page around the
108
+ // story: a handler for restartRequested, say, would stop the page asking before restarting.
109
+ export type SquiffyScriptEvent = "navigated" | "set" | "settingChanged";
110
+
111
+ // What a story's own scripts (.js files added to the page, or @import-ed) get with the
112
+ // squiffy:ready event, which the story's element sends, bubbling up to document, when the story
113
+ // has been set up and before it starts (#528):
114
+ //
115
+ // document.addEventListener("squiffy:ready", ({ detail: squiffy }) => {
116
+ // squiffy.on("navigated", ({ section }) => { ... });
117
+ // });
118
+ //
119
+ // Its get, set and story are the same as a section's JavaScript gets.
120
+ export interface SquiffyScriptApi {
121
+ get: (attribute: string) => any;
122
+ set: (attribute: string, value: any) => void;
123
+ story: {
124
+ go: (section: string) => Promise<void>;
125
+ seen: (sectionOrPassage: string) => boolean;
126
+ visits: (sectionOrPassage: string) => number;
127
+ // How many turns ago it was last visited: 0 if the player is there now, -1 if never (#540)
128
+ lastVisited: (sectionOrPassage: string) => number;
129
+ passages: (section?: string, filter?: TagFilter) => string[];
130
+ sections: (filter?: TagFilter) => string[];
131
+ tags: (name?: string) => string[];
132
+ };
133
+ // A player setting's value (squiffy.json's "settings"), as the story reads it with settings.name
134
+ getSetting: (name: string) => SettingValue | null;
135
+ // The story's element
136
+ element: HTMLElement;
137
+ on<E extends SquiffyScriptEvent>(event: E, handler: SquiffyEventHandler<E>): () => void;
138
+ off<E extends SquiffyScriptEvent>(event: E, handler: SquiffyEventHandler<E>): void;
139
+ once<E extends SquiffyScriptEvent>(event: E, handler: SquiffyEventHandler<E>): () => void;
140
+ }
141
+
59
142
  // Previous versions of Squiffy had "squiffy", "get" and "set" as globals - we now pass these directly into JS functions.
60
143
  // We may tidy up this API at some point, though that would be a breaking change.
61
144
  interface SquiffyJsFunctionApi {
@@ -67,9 +150,27 @@ interface SquiffyJsFunctionApi {
67
150
  story: {
68
151
  go: (section: string) => void;
69
152
  seen: (sectionOrPassage: string) => boolean;
153
+ visits: (sectionOrPassage: string) => number;
154
+ // How many turns ago it was last visited: 0 if the player is there now, -1 if never (#540)
155
+ lastVisited: (sectionOrPassage: string) => number;
156
+ // The passages of a section ("" for the master section), or with no section, the
157
+ // current section's and the master section's, leaving out @1, @last and @after (#527)
158
+ passages: (section?: string, filter?: TagFilter) => string[];
159
+ // The story's sections, apart from the master section
160
+ sections: (filter?: TagFilter) => string[];
161
+ // A passage's or section's @tag tags, or the current section's
162
+ tags: (name?: string) => string[];
70
163
  };
71
164
  }
72
165
 
166
+ // Which sections or passages squiffy.story.passages() and sections() list, by their @tag tags (#527)
167
+ export interface TagFilter {
168
+ // Only those with all of these tags (separated by spaces, or a list)
169
+ tagged?: string | string[];
170
+ // Only those with none of these tags
171
+ untagged?: string | string[];
172
+ }
173
+
73
174
  export interface Story {
74
175
  js: ((
75
176
  squiffy: SquiffyJsFunctionApi,
@@ -78,13 +179,82 @@ export interface Story {
78
179
  ) => void)[];
79
180
  start: string;
80
181
  id?: string | null;
182
+ // squiffy.json's "id", which a saved game is checked against
183
+ projectId?: string;
81
184
  uiJsIndex?: number;
185
+ // The sound files the story names (#444), to load before they're needed
186
+ audio?: string[];
187
+ // Whether @set and link setters take expressions, with the same rules as {{#if}}: attributes
188
+ // by name, and text in quotes. True for a story with a squiffy.json (#373).
189
+ expressions?: boolean;
190
+ // squiffy.json's "panels": passages shown beside the story, or in a dialog from a button
191
+ panels?: Panel[];
192
+ // squiffy.json's "settings": options the player can change, which the story reads as settings.name
193
+ settings?: PlayerSetting[];
194
+ // squiffy.json's "persistent": attributes that belong to the player rather than the
195
+ // playthrough (#539). Restarting, going back and loading a saved game leave them as they are.
196
+ persistent?: string[];
82
197
  sections: Record<string, Section>;
83
198
  }
84
199
 
200
+ // The icons a panel's button can have, in place of its label
201
+ export const PANEL_ICONS = ["bag", "person", "map", "help", "info", "list", "book", "star", "heart"] as const;
202
+ export type PanelIcon = typeof PANEL_ICONS[number];
203
+
204
+ // A passage in the master section that's always on screen, rendered again as the story goes on:
205
+ // beside the story ("side"), or in a dialog that a button in the header opens ("button").
206
+ export interface Panel {
207
+ passage: string;
208
+ // The button's text, or its tooltip if it has an icon. A side panel's button only shows on
209
+ // screens too narrow for the panel.
210
+ label: string;
211
+ // "button" if it's left out
212
+ position?: "side" | "button";
213
+ icon?: PanelIcon;
214
+ }
215
+
216
+ // A player setting (#452), from squiffy.json's "settings": "toggle" is on or off, "list" is one of
217
+ // its options, and "range" a number from min to max
218
+ export type PlayerSetting =
219
+ | PlayerSettingBase & { type: "toggle"; default?: boolean }
220
+ | PlayerSettingBase & { type: "list"; options: PlayerSettingOption[]; default?: string }
221
+ | PlayerSettingBase & { type: "range"; min: number; max: number; step?: number; default?: number };
222
+
223
+ interface PlayerSettingBase {
224
+ // How the story refers to it: settings.name
225
+ name: string;
226
+ // What the Settings dialog calls it
227
+ label: string;
228
+ // More about it, shown under the label
229
+ description?: string;
230
+ }
231
+
232
+ export interface PlayerSettingOption {
233
+ // What the story reads
234
+ value: string;
235
+ // What the Settings dialog shows
236
+ label: string;
237
+ }
238
+
239
+ export type SettingValue = boolean | string | number;
240
+
85
241
  export interface Section {
86
242
  text?: string;
87
243
  clear?: boolean;
244
+ // @music (#444): the file to play, or null to stop it
245
+ music?: string | null;
246
+ // @sound: files to play once, in order, with "stop" for @sound stop
247
+ sounds?: string[];
248
+ // @class (#449): classes on the story's element while this is the current section
249
+ classes?: string[];
250
+ // @tag (#527): tags the story can list sections by
251
+ tags?: string[];
252
+ // @transition (#489): how it appears, or "none", and how long that takes in milliseconds
253
+ transition?: string;
254
+ transitionTime?: number;
255
+ // @leave: how the old text goes when this clears the screen, or "none", and how long that takes
256
+ leave?: string;
257
+ leaveTime?: number;
88
258
  attributes?: string[],
89
259
  jsIndex?: number;
90
260
  passages?: Record<string, Passage>;
@@ -94,6 +264,44 @@ export interface Section {
94
264
  export interface Passage {
95
265
  text?: string;
96
266
  clear?: boolean;
267
+ // @music (#444): the file to play, or null to stop it
268
+ music?: string | null;
269
+ // @sound: files to play once, in order, with "stop" for @sound stop
270
+ sounds?: string[];
271
+ // @class (#449): classes added to the section's when this passage is shown
272
+ classes?: string[];
273
+ // @tag (#527): tags the story can list passages by
274
+ tags?: string[];
275
+ // @transition (#489): how it appears, or "none", and how long that takes in milliseconds
276
+ transition?: string;
277
+ transitionTime?: number;
278
+ // @leave: how the old text goes when this clears the screen, or "none", and how long that takes
279
+ leave?: string;
280
+ leaveTime?: number;
281
+ // @repeat: its links stay clickable, and clicking one doesn't count towards @1, @2... and @last (#104)
282
+ repeat?: boolean;
97
283
  attributes?: string[];
98
284
  jsIndex?: number;
99
- }
285
+ }
286
+ // A saved game, from SquiffyApi.getSave(). It's JSON, so it can be kept as text or in a file.
287
+ export interface SavedGame {
288
+ format: "squiffy-save";
289
+ version: 1;
290
+ // The story's squiffy.json "id", if it has one
291
+ storyId: string | null;
292
+ // Where the player was
293
+ section: string | null;
294
+ passage: string | null;
295
+ // The start of the text the player was reading, to tell saves apart by
296
+ summary: string;
297
+ // When it was saved, as an ISO date
298
+ savedAt: string;
299
+ // Every attribute, including the text on screen (_output)
300
+ state: Record<string, unknown>;
301
+ }
302
+
303
+ export type LoadSaveResult =
304
+ | { success: true }
305
+ // notASave: it isn't a saved game, or it's from a newer version of Squiffy.
306
+ // wrongStory: it's from a different story.
307
+ | { success: false; error: "notASave" | "wrongStory" };