spell 0.8.5 → 0.8.6

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 (56) hide show
  1. package/app/package.json +1 -1
  2. package/app/spaces/@spell/examples/Solitaire/__project.json5 +22 -4
  3. package/dist/epic/cli/epicGroups.js +1 -0
  4. package/dist/epic/command/epicArgs.js +3 -1
  5. package/dist/epic/comments/ThreadFacts.js +10 -2
  6. package/dist/epic/components/__pack/epics.entry.js +41 -41
  7. package/dist/epic/components/__pack/epics.pack.js +1517 -1481
  8. package/dist/epic/components/epic-answer/EpicAnswer.css +21 -11
  9. package/dist/epic/components/epic-answer/EpicAnswer.css.inline.js +1 -1
  10. package/dist/epic/components/epic-item/CollapseAll.css +3 -3
  11. package/dist/epic/components/epic-item/Fold.js +105 -81
  12. package/dist/epic/components/epic-overview/EpicOverview.js +0 -2
  13. package/dist/epic/components/epic-phase/EpicPhase.css +16 -7
  14. package/dist/epic/components/epic-phase/EpicPhase.css.inline.js +1 -1
  15. package/dist/epic/components/epic-phase/EpicPhase.js +1 -3
  16. package/dist/epic/components/epic-section/EpicFold.css +15 -0
  17. package/dist/epic/components/epic-section/EpicFold.css.inline.js +1 -1
  18. package/dist/epic/components/epic-section/EpicFold.js +80 -52
  19. package/dist/epic/components/epic-section/EpicSection.js +1 -3
  20. package/dist/epic/components/epic-section/EpicSection.types.js +1 -15
  21. package/dist/epic/components/epic-section/PhaseDrag.js +7 -4
  22. package/dist/epic/docs/__data/components.json5 +0 -42
  23. package/dist/epic/docs/epic-overview.html +6 -6
  24. package/dist/epic/docs/epic-phase.html +12 -5
  25. package/dist/epic/docs/epic-section.html +6 -4
  26. package/dist/epic/review/ReviewClient.js +9 -0
  27. package/dist/epic/tool/InboxCommands.js +12 -1
  28. package/dist/epic/tool/PLAN-DOC.md +9 -0
  29. package/dist/epic/tool/PlanDoc.js +17 -5
  30. package/dist/epic/tool/PlanDocCommands.js +6 -3
  31. package/dist/epic/tool/ReviewInbox.js +20 -4
  32. package/dist/epic/tools/_assets/commands.js +452 -451
  33. package/dist/epic/tools/_assets/core-reference.js +656 -655
  34. package/dist/epic/tools/_assets/spell-comments.js +575 -569
  35. package/dist/epic/tools/_assets/spell-doc-runtime.js +16 -3
  36. package/dist/epic/tools/_assets/spell-syntax.js +415 -414
  37. package/dist/epic/tools/_assets/spell-ui.entry.js +3 -2
  38. package/dist/epic/tools/_assets/spell-ui.js +7898 -7835
  39. package/dist/server/WebServer.js +2 -1
  40. package/dist/server/liveClient.d.ts +37 -1
  41. package/dist/server/liveClient.js +119 -6
  42. package/dist/server/site/PagePatch.d.ts +35 -1
  43. package/dist/server/site/PagePatch.js +94 -12
  44. package/dist/ui/components/ui-components/PackHotSwap.d.ts +6 -0
  45. package/dist/ui/components/ui-components/PackHotSwap.js +12 -2
  46. package/dist/ui/components/ui-section/UISection.d.ts +8 -0
  47. package/dist/ui/components/ui-section/UISection.js +22 -11
  48. package/dist/ui/docs-components/ui-docs-theme-bench/UIDocsThemeBench.d.ts +1 -1
  49. package/dist/util/spell/constants.js +1 -1
  50. package/epic/package.json +1 -1
  51. package/epic/skills/epic/SKILL.md +16 -0
  52. package/epic/src/AGENTS.md +29 -4
  53. package/epic/src/tool/PLAN-DOC.md +9 -0
  54. package/package.json +1 -1
  55. package/parser/package.json +1 -1
  56. package/ui/package.json +1 -1
@@ -6,7 +6,7 @@ import { createServer } from "node:http";
6
6
  import { relative, sep } from "node:path";
7
7
  import { Guard } from "./Guard.js";
8
8
  import { toListener } from "./listener.js";
9
- import { liveClientScript } from "./liveClient.js";
9
+ import { holdRevealScript, liveClientScript } from "./liveClient.js";
10
10
  import { LiveReload } from "./LiveReload.js";
11
11
  import { listenPreferred } from "./ports.js";
12
12
  import { underPrefix } from "./proxy.js";
@@ -138,6 +138,7 @@ var WebServer = class {
138
138
  const head = page.search(/<\/head>/i);
139
139
  const icons = HAS_ICON.test(head < 0 ? "" : page.slice(0, head)) ? "" : FAVICON_LINKS;
140
140
  const tags = `${icons}<script>window.SPELL_SERVER = ${config}</script>
141
+ <script>${holdRevealScript()}</script>
141
142
  <script src="${LIVE_SCRIPT}" defer></script>
142
143
  `;
143
144
  return head < 0 ? tags + page : page.slice(0, head) + tags + page.slice(head);
@@ -26,6 +26,14 @@ import type { SiteTab } from "spell/server/site/site.types";
26
26
  * - `takeScroll()`: the scroll position a live reload saved, once
27
27
  * - the docs runtime restores it itself, after its folds and definitions settle;
28
28
  * else the client does, on `load`
29
+ * - `reload()`: added by `liveClient()`: reload NOW, keeping the scroll, the new page held behind the old one until it's
30
+ * ready (`holdReveal()`); for a page whose own hot reload failed half way (Spell UI's `PackHotSwap`)
31
+ * - `reveal(settle?)`, `revealAfter(ready)`: added by `holdReveal()`: a live reload's new page waits behind the old
32
+ * one until it's ready
33
+ * - `reveal()`: it's ready: show it (a short cross-fade) once every `revealAfter()` promise has settled and its
34
+ * `<ui-root>`s are ready; `settle()` runs just before. The docs runtime calls it once it has landed, else the
35
+ * client on `load`
36
+ * - `revealAfter(ready)`: wait for `ready` too (Spell UI's site: its layout mounted); call it before `load`
29
37
  * - `etag` follows the page: an in-place update (`PageChange`) moves it to the new version's
30
38
  */
31
39
  export type ServerConfig = {
@@ -64,6 +72,9 @@ export type ServerConfig = {
64
72
  saveFile?: (save: FileSave) => Promise<PageEditResult>;
65
73
  readPage?: () => Promise<PageSource>;
66
74
  takeScroll?: () => number | undefined;
75
+ reload?: () => void;
76
+ reveal?: (settle?: () => void) => void;
77
+ revealAfter?: (ready: Promise<unknown>) => void;
67
78
  };
68
79
  /** The page's file as served now: its HTML (with what the server injects) and `ETag`. */
69
80
  export type PageSource = {
@@ -192,7 +203,7 @@ export type PageEditResult = {
192
203
  * (`layUnderWorktree()`, `worktreeHref()`; epic `epic-engine` P46)
193
204
  * - runs once per page
194
205
  */
195
- export declare function liveClient(): void;
206
+ export declare function liveClient(scrollKey: string): void;
196
207
  /**
197
208
  * Is `press` a key VS Code should handle, pressed in a page in VS Code's side-bar view (`liveClient()` `forwardKey()`)?
198
209
  * - `apple`: Cmd is the command key; else Ctrl
@@ -290,6 +301,31 @@ export type ReloadGate = {
290
301
  request: () => void;
291
302
  settle: () => void;
292
303
  };
304
+ /**
305
+ * A live reload's NEW page, held behind the old one until it has drawn and landed, then cross-faded in
306
+ * (epic `epic-engine` I164; Owen, 2026-10-29: "Page still redraws awkwardly sometimes. Can you use a page
307
+ * transition to redraw without visual flash?").
308
+ * - Measured before, on an epic page: a reload showed a white frame, then ~150ms of the bare background (the
309
+ * elements not drawn yet), then the page at its top, then the page where the reader was.
310
+ * - Runs INLINE in every served page's `<head>` (`holdRevealScript()`, `WebServer`'s injected tags), before
311
+ * anything draws: the live client itself comes later, deferred.
312
+ * - Every page opts in to cross-document view transitions (`@view-transition { navigation: auto }`), so the live
313
+ * client's `reload()` (a replace navigation to the page itself) runs one; any other navigation skips it
314
+ * (`pageswap`): links open as they always did
315
+ * - the new page, after such a reload (`KeptPlace.hold`, for this path):
316
+ * - its address's `#id` is put back, before any runtime reads it
317
+ * - its view transition's animations wait at their start: the old frame stays up, the new page draws behind it
318
+ * - `SPELL_SERVER.reveal()` lets them run, `FADE_MS`, no slide, once what the page asked to wait for
319
+ * (`revealAfter()`) has settled and its `<ui-root>`s are ready: the docs runtime calls it once it has landed and
320
+ * wears its theme, the live client on `load` for any other page (`restoreScroll()`); at the latest after `HOLD_MS`
321
+ * - measured on Spell UI's site: `load` came before its layout was even mounted, so the site waits for that too
322
+ * - less motion asked for (`prefers-reduced-motion`): no fade, the new page just shows when it's ready
323
+ * - MUST stay self-contained, as `liveClient()`: served as text
324
+ * - NEVER throws: without view transitions or storage, a reload is a plain reload
325
+ */
326
+ export declare function holdReveal(scrollKey: string): void;
327
+ /** `holdReveal()` as inline script text, for every served page's `<head>` (`WebServer`). */
328
+ export declare function holdRevealScript(): string;
293
329
  /**
294
330
  * `liveClient` as a classic script, for `/api/server/live.js`: the helpers it calls first
295
331
  * (`forVsCode()`, `liveAction()`, `servedPath()`, `worktreeHref()`, `reloadGate()`).
@@ -2,12 +2,11 @@ var __defProp = Object.defineProperty;
2
2
  var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
3
 
4
4
  // src/server/liveClient.ts
5
- function liveClient() {
5
+ function liveClient(scrollKey) {
6
6
  const holder = window;
7
7
  const config = holder.SPELL_SERVER;
8
8
  if (!config || holder.__spellLive) return;
9
9
  holder.__spellLive = true;
10
- const scrollKey = "spell-server:scroll";
11
10
  let savedScroll;
12
11
  let updating = Promise.resolve();
13
12
  let lastKey = { command: "", at: 0 };
@@ -44,6 +43,7 @@ function liveClient() {
44
43
  return y;
45
44
  };
46
45
  config.readPage = readPage;
46
+ config.reload = reload;
47
47
  if (window.parent !== window) {
48
48
  reportPlace();
49
49
  addEventListener("pageshow", reportPlace);
@@ -166,10 +166,15 @@ function liveClient() {
166
166
  __name(reloadUnseen, "reloadUnseen");
167
167
  function reload() {
168
168
  try {
169
- sessionStorage.setItem(scrollKey, JSON.stringify({ path: location.pathname, y: scrollY }));
169
+ sessionStorage.setItem(
170
+ scrollKey,
171
+ JSON.stringify({ path: location.pathname, y: scrollY, hash: location.hash, hold: true })
172
+ );
170
173
  } catch {
174
+ return location.reload();
171
175
  }
172
- location.reload();
176
+ if ("onpagereveal" in window) location.replace(location.pathname + location.search);
177
+ else location.reload();
173
178
  }
174
179
  __name(reload, "reload");
175
180
  async function updatePage(pushed) {
@@ -529,8 +534,13 @@ function liveClient() {
529
534
  addEventListener(
530
535
  "load",
531
536
  () => {
532
- if (savedScroll !== void 0) scrollTo(0, savedScroll);
537
+ if (savedScroll === void 0) return;
538
+ const y = savedScroll;
533
539
  savedScroll = void 0;
540
+ scrollTo(0, y);
541
+ config.reveal?.(() => {
542
+ if (Math.abs(scrollY - y) >= 1) scrollTo(0, y);
543
+ });
534
544
  },
535
545
  { once: true }
536
546
  );
@@ -603,6 +613,107 @@ function reloadGate({ wait, typing, reload, waiting }) {
603
613
  };
604
614
  }
605
615
  __name(reloadGate, "reloadGate");
616
+ function holdReveal(scrollKey) {
617
+ const HOLD_MS = 2500;
618
+ const FADE_MS = 150;
619
+ const config = window.SPELL_SERVER;
620
+ if (!config) return;
621
+ try {
622
+ const style = document.createElement("style");
623
+ style.textContent = "@view-transition { navigation: auto; }";
624
+ (document.head ?? document.documentElement).append(style);
625
+ } catch {
626
+ return;
627
+ }
628
+ const kept = /* @__PURE__ */ __name(() => {
629
+ try {
630
+ return JSON.parse(sessionStorage.getItem(scrollKey) ?? "null");
631
+ } catch {
632
+ return null;
633
+ }
634
+ }, "kept");
635
+ addEventListener("pageswap", (event) => {
636
+ const transition = event.viewTransition;
637
+ const place2 = kept();
638
+ if (transition && !(place2?.hold && place2.path === location.pathname)) transition.skipTransition();
639
+ });
640
+ const waits = [];
641
+ let isAsked = false;
642
+ let isShown = false;
643
+ let held;
644
+ config.revealAfter = (ready) => {
645
+ waits.push(Promise.resolve(ready).catch(() => void 0));
646
+ };
647
+ config.reveal = (settle) => {
648
+ if (isAsked) return;
649
+ isAsked = true;
650
+ void Promise.all(waits).then(rootsDrawn).then(() => {
651
+ settle?.();
652
+ show();
653
+ });
654
+ };
655
+ const place = kept();
656
+ if (!place?.hold || place.path !== location.pathname) return;
657
+ if (place.hash && !location.hash) history.replaceState(history.state, "", place.hash);
658
+ addEventListener(
659
+ "pagereveal",
660
+ (event) => {
661
+ const transition = event.viewTransition;
662
+ if (!transition) return;
663
+ held = transition;
664
+ transition.ready.then(
665
+ () => {
666
+ for (const animation of fades()) {
667
+ animation.effect?.updateTiming({ duration: FADE_MS });
668
+ if (!isShown) animation.pause();
669
+ }
670
+ },
671
+ () => void 0
672
+ );
673
+ setTimeout(show, HOLD_MS);
674
+ },
675
+ { once: true }
676
+ );
677
+ function show() {
678
+ if (isShown) return;
679
+ isShown = true;
680
+ if (!held) return;
681
+ if (matchMedia("(prefers-reduced-motion: reduce)").matches) return held.skipTransition();
682
+ for (const animation of fades()) animation.play();
683
+ }
684
+ __name(show, "show");
685
+ function fades() {
686
+ return document.getAnimations().filter((animation) => {
687
+ const effect = animation.effect;
688
+ return !!effect?.pseudoElement?.startsWith("::view-transition");
689
+ });
690
+ }
691
+ __name(fades, "fades");
692
+ function rootsDrawn() {
693
+ const isWaiting = /* @__PURE__ */ __name((root) => {
694
+ try {
695
+ return !root.matches(":state(ready)");
696
+ } catch {
697
+ return false;
698
+ }
699
+ }, "isWaiting");
700
+ return new Promise((done) => {
701
+ const look = /* @__PURE__ */ __name(() => {
702
+ if (isShown || !Array.from(document.querySelectorAll("ui-root")).some(isWaiting))
703
+ requestAnimationFrame(() => requestAnimationFrame(() => done()));
704
+ else requestAnimationFrame(look);
705
+ }, "look");
706
+ look();
707
+ });
708
+ }
709
+ __name(rootsDrawn, "rootsDrawn");
710
+ }
711
+ __name(holdReveal, "holdReveal");
712
+ function holdRevealScript() {
713
+ return `var __name = (fn) => fn;(${holdReveal.toString()})(${JSON.stringify(SCROLL_KEY)})`;
714
+ }
715
+ __name(holdRevealScript, "holdRevealScript");
716
+ var SCROLL_KEY = "spell-server:scroll";
606
717
  function liveClientScript() {
607
718
  return [
608
719
  "// spell server: live reload and page edits (spell/src/server/liveClient.ts)",
@@ -612,13 +723,15 @@ function liveClientScript() {
612
723
  servedPath.toString(),
613
724
  worktreeHref.toString(),
614
725
  reloadGate.toString(),
615
- `(${liveClient.toString()})()`,
726
+ `(${liveClient.toString()})(${JSON.stringify(SCROLL_KEY)})`,
616
727
  ""
617
728
  ].join("\n");
618
729
  }
619
730
  __name(liveClientScript, "liveClientScript");
620
731
  export {
621
732
  forVsCode,
733
+ holdReveal,
734
+ holdRevealScript,
622
735
  liveAction,
623
736
  liveClient,
624
737
  liveClientScript,
@@ -13,6 +13,8 @@
13
13
  * - what's never replaced: an open editor (Monaco in a cell), the field being typed in
14
14
  * - what reader state is kept: folds, open panels, typed text, the scroll, the selection
15
15
  * - spell-epic's docs runtime adds the epic pages' (`spell-doc-runtime.js`), Spell UI's site its own (`SitePatch`)
16
+ * - A runtime shows a patch with `redraw()`: one short cross-fade when it changes what's on screen, never a half-drawn
17
+ * frame (`crossFade()`, a view transition; epic `epic-engine` I164); a part's body swapped in uses `crossFade()` too
16
18
  * - Plain DOM, NO imports: any page's bundle can take it.
17
19
  *
18
20
  * How a node is matched (Owen, comment M1 on P40):
@@ -73,7 +75,39 @@ export declare class PagePatch {
73
75
  * `top()`: how far down the window the stuck titles end, ABOVE which nothing counts as read
74
76
  * - `<body>`'s attributes are patched too, but never its `class` (runtimes add their own)
75
77
  */
76
- page({ before, after, live, mainOf, top }: PageEdit): PageRun | null;
78
+ page(edit: PageEdit): PageRun | null;
79
+ /**
80
+ * `page()`, drawn as ONE short cross-fade (`crossFade()`) when it changes what's on screen
81
+ * (epic `epic-engine` I164; Owen, 2026-10-29: "use a page transition to redraw without visual flash").
82
+ * - the same refusals as `page()`: null, nothing changed
83
+ * - straight in, no fade: everything it changes is off screen, motion is reduced, the field being typed in has the
84
+ * focus, or the browser has no view transitions (`crossFade()` says which)
85
+ * - resolves once the page has the change; the fade finishes by itself
86
+ */
87
+ redraw(edit: PageEdit): Promise<PageRun | null>;
88
+ /**
89
+ * The checks and plan behind `page()` and `redraw()`: null when it's refused, else its steps, whether any of them
90
+ * changes what's on screen, and the run (null when the live page doesn't line up after all).
91
+ */
92
+ private pagePlan;
93
+ /**
94
+ * Run `change`, a change to the page, as ONE short cross-fade from the page as it was to the page as it is after
95
+ * (a same-document view transition, `document.startViewTransition()`; epic `epic-engine` I164).
96
+ * - the old frame stays up until `change` resolves, so nothing half drawn ever shows: a part's body loading, an
97
+ * element drawing its new state; then old and new cross-fade, `FADE_MS`, no slide
98
+ * - just `change()`, no transition, when:
99
+ * - `onScreen` is false: nothing the reader sees moves
100
+ * - the reader asked for less motion (`prefers-reduced-motion`)
101
+ * - the page is out of sight, or the browser has no view transitions
102
+ * - a field has the focus: what's typed would freeze for the fade
103
+ * - resolves with what `change` returns; rejects as it does
104
+ */
105
+ static crossFade<T>(change: () => T | Promise<T>, onScreen?: boolean): Promise<T>;
106
+ /**
107
+ * Does `node` show in the window now? Its box, else its nearest ancestor's that has one (an element drawn as
108
+ * `display: contents`, like `<epic-item>`, has none of its own), crosses the window's height.
109
+ */
110
+ static isOnScreen(node: Node): boolean;
77
111
  /**
78
112
  * What the reader is looking at in `root`: the element mid-column, just below `top` (px from the window's top),
79
113
  * and its top; null when none is.
@@ -162,7 +162,27 @@ var PagePatch = class _PagePatch {
162
162
  * `top()`: how far down the window the stuck titles end, ABOVE which nothing counts as read
163
163
  * - `<body>`'s attributes are patched too, but never its `class` (runtimes add their own)
164
164
  */
165
- page({ before, after, live, mainOf, top = /* @__PURE__ */ __name(() => 0, "top") }) {
165
+ page(edit) {
166
+ return this.pagePlan(edit)?.run() ?? null;
167
+ }
168
+ /**
169
+ * `page()`, drawn as ONE short cross-fade (`crossFade()`) when it changes what's on screen
170
+ * (epic `epic-engine` I164; Owen, 2026-10-29: "use a page transition to redraw without visual flash").
171
+ * - the same refusals as `page()`: null, nothing changed
172
+ * - straight in, no fade: everything it changes is off screen, motion is reduced, the field being typed in has the
173
+ * focus, or the browser has no view transitions (`crossFade()` says which)
174
+ * - resolves once the page has the change; the fade finishes by itself
175
+ */
176
+ async redraw(edit) {
177
+ const plan = this.pagePlan(edit);
178
+ if (!plan) return null;
179
+ return _PagePatch.crossFade(() => plan.run(), plan.isOnScreen());
180
+ }
181
+ /**
182
+ * The checks and plan behind `page()` and `redraw()`: null when it's refused, else its steps, whether any of them
183
+ * changes what's on screen, and the run (null when the live page doesn't line up after all).
184
+ */
185
+ pagePlan({ before, after, live, mainOf, top = /* @__PURE__ */ __name(() => 0, "top") }) {
166
186
  const was = mainOf(before);
167
187
  const now = mainOf(after);
168
188
  if (!was || !now || headKey(before) !== headKey(after) || shellKey(before, mainOf) !== shellKey(after, mainOf))
@@ -174,18 +194,79 @@ var PagePatch = class _PagePatch {
174
194
  0
175
195
  );
176
196
  if (weight > now.outerHTML.length / 2) return null;
177
- const anchor = _PagePatch.readingAnchor(live, top());
178
- let run;
179
- try {
180
- run = this.run(steps, live);
181
- } catch (error) {
182
- if (error instanceof PatchError) return null;
183
- throw error;
197
+ const rules = this.rules;
198
+ return {
199
+ isOnScreen: /* @__PURE__ */ __name(() => steps.some((step) => {
200
+ try {
201
+ return _PagePatch.isOnScreen(resolveAddress(live, "target" in step ? step.target : step.parent, rules));
202
+ } catch {
203
+ return true;
204
+ }
205
+ }), "isOnScreen"),
206
+ run: /* @__PURE__ */ __name(() => {
207
+ const anchor = _PagePatch.readingAnchor(live, top());
208
+ let run;
209
+ try {
210
+ run = this.run(steps, live);
211
+ } catch (error) {
212
+ if (error instanceof PatchError) return null;
213
+ throw error;
214
+ }
215
+ patchBodyAttributes(before.body, after.body, live.ownerDocument.body);
216
+ if (after.title !== before.title) live.ownerDocument.title = after.title;
217
+ _PagePatch.keepAnchor(anchor);
218
+ return { ...run, steps, weight };
219
+ }, "run")
220
+ };
221
+ }
222
+ ////////////////
223
+ // ## Redrawing without a flash
224
+ ////////////////
225
+ /**
226
+ * Run `change`, a change to the page, as ONE short cross-fade from the page as it was to the page as it is after
227
+ * (a same-document view transition, `document.startViewTransition()`; epic `epic-engine` I164).
228
+ * - the old frame stays up until `change` resolves, so nothing half drawn ever shows: a part's body loading, an
229
+ * element drawing its new state; then old and new cross-fade, `FADE_MS`, no slide
230
+ * - just `change()`, no transition, when:
231
+ * - `onScreen` is false: nothing the reader sees moves
232
+ * - the reader asked for less motion (`prefers-reduced-motion`)
233
+ * - the page is out of sight, or the browser has no view transitions
234
+ * - a field has the focus: what's typed would freeze for the fade
235
+ * - resolves with what `change` returns; rejects as it does
236
+ */
237
+ static async crossFade(change, onScreen = true) {
238
+ const doc = document;
239
+ if (!onScreen || typeof doc.startViewTransition !== "function" || doc.visibilityState !== "visible" || matchMedia("(prefers-reduced-motion: reduce)").matches || typingIn(doc.documentElement))
240
+ return change();
241
+ let result;
242
+ const transition = doc.startViewTransition(async () => {
243
+ result = await change();
244
+ });
245
+ transition.ready.then(
246
+ () => {
247
+ for (const animation of doc.getAnimations()) {
248
+ const effect = animation.effect;
249
+ if (effect?.pseudoElement?.startsWith("::view-transition")) effect.updateTiming({ duration: FADE_MS });
250
+ }
251
+ },
252
+ // skipped (another transition started, or the page went out of sight): the change still ran
253
+ () => void 0
254
+ );
255
+ await transition.updateCallbackDone;
256
+ return result;
257
+ }
258
+ /**
259
+ * Does `node` show in the window now? Its box, else its nearest ancestor's that has one (an element drawn as
260
+ * `display: contents`, like `<epic-item>`, has none of its own), crosses the window's height.
261
+ */
262
+ static isOnScreen(node) {
263
+ let element = isElement(node) ? node : node.parentElement;
264
+ while (element) {
265
+ const box = element.getBoundingClientRect();
266
+ if (box.width || box.height) return box.bottom > 0 && box.top < innerHeight;
267
+ element = element.parentElement ?? element.getRootNode().host ?? null;
184
268
  }
185
- patchBodyAttributes(before.body, after.body, live.ownerDocument.body);
186
- if (after.title !== before.title) live.ownerDocument.title = after.title;
187
- _PagePatch.keepAnchor(anchor);
188
- return { ...run, steps, weight };
269
+ return false;
189
270
  }
190
271
  ////////////////
191
272
  // ## The reading position
@@ -271,6 +352,7 @@ var PatchError = class extends Error {
271
352
  PatchError.prototype.name = "PatchError";
272
353
  var TEXT_KIND = "text()";
273
354
  var ROOT = "/";
355
+ var FADE_MS = 150;
274
356
  var Planner = class {
275
357
  static {
276
358
  __name(this, "Planner");
@@ -26,6 +26,12 @@ export declare class PackHotSwap {
26
26
  * the page, and swap each in; else leave them, and the page reloads.
27
27
  */
28
28
  private static onScripts;
29
+ /**
30
+ * Reload the page: through the live client when it's there (`SPELL_SERVER.reload()`), which keeps the scroll and
31
+ * holds the new page behind the old one until it's ready (epic `epic-engine` I164); else a plain reload.
32
+ * - measured before: `location.reload()` here lost the scroll and the item open, through ~150ms of bare background
33
+ */
34
+ private static reload;
29
35
  /** `install()` ran. */
30
36
  private static isInstalled;
31
37
  }
@@ -35,14 +35,24 @@ var PackHotSwap = class _PackHotSwap {
35
35
  event.preventDefault();
36
36
  Promise.all(sources.map((source) => ComponentPacks.reload(source, _PackHotSwap.swap))).then(
37
37
  (results) => {
38
- if (results.includes("reload")) location.reload();
38
+ if (results.includes("reload")) _PackHotSwap.reload();
39
39
  },
40
40
  (error) => {
41
41
  console.error("PackHotSwap: couldn't swap the rebuilt pack in; reloading", error);
42
- location.reload();
42
+ _PackHotSwap.reload();
43
43
  }
44
44
  );
45
45
  }
46
+ /**
47
+ * Reload the page: through the live client when it's there (`SPELL_SERVER.reload()`), which keeps the scroll and
48
+ * holds the new page behind the old one until it's ready (epic `epic-engine` I164); else a plain reload.
49
+ * - measured before: `location.reload()` here lost the scroll and the item open, through ~150ms of bare background
50
+ */
51
+ static reload() {
52
+ const server = globalThis.SPELL_SERVER;
53
+ if (server?.reload) server.reload();
54
+ else location.reload();
55
+ }
46
56
  /** `install()` ran. */
47
57
  static isInstalled = false;
48
58
  };
@@ -518,6 +518,14 @@ export declare class UISection extends E.UIComponent<SectionVocabulary> {
518
518
  * - Does nothing unless `collapsible`, or while `disabled`.
519
519
  */
520
520
  toggle(originalEvent?: Event): boolean;
521
+ /**
522
+ * More for the fold button's tooltip, on a line of its own after `Open this section`: a component that draws the
523
+ * section sets it (the epic page's blocks: `⌥-click: open everything inside`).
524
+ * - a property, not an attribute: nothing a page writes
525
+ */
526
+ accessor toggleTipMore: string | undefined;
527
+ /** The fold button's tooltip: `Open this section` / `Close this section`, then `toggleTipMore`. */
528
+ get toggleTip(): string;
521
529
  /** A click on the toggle (Enter / Space on the button click it too). */
522
530
  private readonly onToggleClick;
523
531
  /** A click on the END chevron, outside the button: folds as the button does. */
@@ -134,6 +134,7 @@ var _titleIsStuck_dec;
134
134
  var _isStuck_dec;
135
135
  var _titleHeight_dec;
136
136
  var _onFoldedChanged_dec;
137
+ var _toggleTipMore_dec;
137
138
  var _isFolded_dec;
138
139
  var _isMarkedOpen_dec;
139
140
  var _isInGroup_dec;
@@ -145,11 +146,12 @@ var _vocabulary_dec;
145
146
  var _a;
146
147
  var _init;
147
148
  var _isMarkedOpen;
149
+ var _toggleTipMore;
148
150
  var _titleHeight;
149
151
  var _isStuck;
150
152
  var _hasTuckedFirst;
151
153
  var _isFollowedByClosed;
152
- var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec = [E.proto], _elementSetup_dec = [E.protoMerged], _defaultFoldIcon_dec = [E.proto], _enclosingSection_dec = [E.derived], _isNested_dec = [E.cssState("nested")], _isInGroup_dec = [E.cssState("in-group")], _isMarkedOpen_dec = [E.controlled("open")], _isFolded_dec = [E.cssState("collapsed")], _onFoldedChanged_dec = [E.onChange("isFolded", { defer: true })], _titleHeight_dec = [E.state], _isStuck_dec = [E.state], _titleIsStuck_dec = [E.cssState("stuck")], _isStacked_dec = [E.cssState("stacked")], _stackPlaces_dec = [E.watches({
154
+ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec = [E.proto], _elementSetup_dec = [E.protoMerged], _defaultFoldIcon_dec = [E.proto], _enclosingSection_dec = [E.derived], _isNested_dec = [E.cssState("nested")], _isInGroup_dec = [E.cssState("in-group")], _isMarkedOpen_dec = [E.controlled("open")], _isFolded_dec = [E.cssState("collapsed")], _toggleTipMore_dec = [E.state], _onFoldedChanged_dec = [E.onChange("isFolded", { defer: true })], _titleHeight_dec = [E.state], _isStuck_dec = [E.state], _titleIsStuck_dec = [E.cssState("stuck")], _isStacked_dec = [E.cssState("stacked")], _stackPlaces_dec = [E.watches({
153
155
  childList: true,
154
156
  subtree: true,
155
157
  equals: isSameStack
@@ -185,6 +187,7 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
185
187
  section: this.domElement
186
188
  }), "afterDetail")
187
189
  }));
190
+ __privateAdd(this, _toggleTipMore, __runInitializers(_init, 12, this)), __runInitializers(_init, 15, this);
188
191
  __publicField(this, "onToggleClick", (event) => {
189
192
  if (E.OwnControls.isClicked(event, { before: TOGGLE_BUTTON })) return;
190
193
  this.toggle(event);
@@ -192,13 +195,13 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
192
195
  __publicField(this, "onFoldIconClick", (event) => {
193
196
  this.toggle(event);
194
197
  });
195
- __privateAdd(this, _titleHeight, __runInitializers(_init, 12, this, 0)), __runInitializers(_init, 15, this);
196
- __privateAdd(this, _isStuck, __runInitializers(_init, 16, this, false)), __runInitializers(_init, 19, this);
198
+ __privateAdd(this, _titleHeight, __runInitializers(_init, 16, this, 0)), __runInitializers(_init, 19, this);
199
+ __privateAdd(this, _isStuck, __runInitializers(_init, 20, this, false)), __runInitializers(_init, 23, this);
197
200
  __publicField(this, "title");
198
201
  __publicField(this, "sentinel");
199
202
  __publicField(this, "stickyWatch", new E.StickyWatch(({ edge }) => this.isStuck = edge !== void 0));
200
- __privateAdd(this, _hasTuckedFirst, __runInitializers(_init, 20, this, false)), __runInitializers(_init, 23, this);
201
- __privateAdd(this, _isFollowedByClosed, __runInitializers(_init, 24, this, false)), __runInitializers(_init, 27, this);
203
+ __privateAdd(this, _hasTuckedFirst, __runInitializers(_init, 24, this, false)), __runInitializers(_init, 27, this);
204
+ __privateAdd(this, _isFollowedByClosed, __runInitializers(_init, 28, this, false)), __runInitializers(_init, 31, this);
202
205
  __publicField(this, "slots", new E.SlotContent(this.domElement));
203
206
  __publicField(this, "iconGlyph", new E.IconGlyph({
204
207
  owner: this,
@@ -272,6 +275,12 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
272
275
  toggle(originalEvent) {
273
276
  return this.disclosure.toggle(originalEvent);
274
277
  }
278
+ /** The fold button's tooltip: `Open this section` / `Close this section`, then `toggleTipMore`. */
279
+ get toggleTip() {
280
+ const tip = this.translationForKey(this.isFolded ? "openSection" : "closeSection");
281
+ return this.toggleTipMore ? `${tip}
282
+ ${this.toggleTipMore}` : tip;
283
+ }
275
284
  onFoldedChanged(isFolded) {
276
285
  this.disclosure.sendAfter(!isFolded);
277
286
  }
@@ -620,7 +629,7 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
620
629
  get title() {
621
630
  return _$memo(() => {
622
631
  return !!_self$2.isCollapsible;
623
- })() ? _self$2.translationForKey(_self$2.isFolded ? "openSection" : "closeSection") : void 0;
632
+ })() ? _self$2.toggleTip : void 0;
624
633
  },
625
634
  get disabled() {
626
635
  return _self$2.isCollapsible && _self$2.disabled ? true : void 0;
@@ -807,7 +816,7 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
807
816
  return {
808
817
  e: _$readShallow(FOLD_ICON_CLASS),
809
818
  t: _self$3.partForName("fold-icon"),
810
- a: onClick ? _self$3.translationForKey(_self$3.isFolded ? "openSection" : "closeSection") : void 0
819
+ a: onClick ? _self$3.toggleTip : void 0
811
820
  };
812
821
  }, ({ e, t, a }, _p$) => {
813
822
  _$className(_el$29, e, _p$?.e);
@@ -819,6 +828,7 @@ var _UISection = class _UISection2 extends (_a = E.UIComponent, _vocabulary_dec
819
828
  };
820
829
  _init = __decoratorStart(_a);
821
830
  _isMarkedOpen = /* @__PURE__ */ new WeakMap();
831
+ _toggleTipMore = /* @__PURE__ */ new WeakMap();
822
832
  _titleHeight = /* @__PURE__ */ new WeakMap();
823
833
  _isStuck = /* @__PURE__ */ new WeakMap();
824
834
  _hasTuckedFirst = /* @__PURE__ */ new WeakMap();
@@ -828,6 +838,7 @@ __decorateElement(_init, 2, "isNested", _isNested_dec, _UISection);
828
838
  __decorateElement(_init, 2, "isInGroup", _isInGroup_dec, _UISection);
829
839
  __decorateElement(_init, 4, "isMarkedOpen", _isMarkedOpen_dec, _UISection, _isMarkedOpen);
830
840
  __decorateElement(_init, 2, "isFolded", _isFolded_dec, _UISection);
841
+ __decorateElement(_init, 4, "toggleTipMore", _toggleTipMore_dec, _UISection, _toggleTipMore);
831
842
  __decorateElement(_init, 1, "onFoldedChanged", _onFoldedChanged_dec, _UISection);
832
843
  __decorateElement(_init, 4, "titleHeight", _titleHeight_dec, _UISection, _titleHeight);
833
844
  __decorateElement(_init, 4, "isStuck", _isStuck_dec, _UISection, _isStuck);
@@ -853,8 +864,8 @@ __decorateElement(_init, 13, "vocabulary", _vocabulary_dec, _UISection);
853
864
  __decorateElement(_init, 13, "elementSetup", _elementSetup_dec, _UISection);
854
865
  __decorateElement(_init, 13, "defaultFoldIcon", _defaultFoldIcon_dec, _UISection);
855
866
  __decoratorMetadata(_init, _UISection);
856
- __publicField(_UISection, "vocabulary", __runInitializers(_init, 28, _UISection, sectionVocabulary)), __runInitializers(_init, 31, _UISection);
857
- __publicField(_UISection, "elementSetup", __runInitializers(_init, 32, _UISection, {
867
+ __publicField(_UISection, "vocabulary", __runInitializers(_init, 32, _UISection, sectionVocabulary)), __runInitializers(_init, 35, _UISection);
868
+ __publicField(_UISection, "elementSetup", __runInitializers(_init, 36, _UISection, {
858
869
  styleSheets: { section: sectionCSS },
859
870
  cssStates: ["inverted"],
860
871
  DOMElement: E.DOMLoadableBodyElement,
@@ -862,8 +873,8 @@ __publicField(_UISection, "elementSetup", __runInitializers(_init, 32, _UISectio
862
873
  delegatesFocus: false,
863
874
  // `loading`: Fomantic's veil
864
875
  loading: "its own"
865
- })), __runInitializers(_init, 35, _UISection);
866
- __publicField(_UISection, "defaultFoldIcon", __runInitializers(_init, 36, _UISection, FoldIconPlace.start)), __runInitializers(_init, 39, _UISection);
876
+ })), __runInitializers(_init, 39, _UISection);
877
+ __publicField(_UISection, "defaultFoldIcon", __runInitializers(_init, 40, _UISection, FoldIconPlace.start)), __runInitializers(_init, 43, _UISection);
867
878
  var UISection = _UISection;
868
879
  function isSameStack(a, b) {
869
880
  return a.length === b.length && a.every((place, index) => place.element === b[index].element && place.isFirst === b[index].isFirst && place.previous === b[index].previous);
@@ -41,7 +41,7 @@ export declare class UIDocsThemeBench extends E.UIComponent<DocsThemeBenchVocabu
41
41
  readonly text: "Notebook";
42
42
  readonly description: "The notebook's title.";
43
43
  }, {
44
- readonly key: "editor";
44
+ readonly key: "app";
45
45
  readonly text: "App";
46
46
  readonly description: "The Spell editor app's title (Owen renamed it from Editor).";
47
47
  }, {
@@ -2,7 +2,7 @@
2
2
  var OPTIONAL = "OPTIONAL";
3
3
  var REQUIRED = "REQUIRED";
4
4
  var NONE = "NONE";
5
- var PACKAGE_VERSION = true ? "0.8.5" : "unknown";
5
+ var PACKAGE_VERSION = true ? "0.8.6" : "unknown";
6
6
  var CONFIRM = "CONFIRM";
7
7
  var TaskStatus = {
8
8
  UNSTARTED: "UNSTARTED",
package/epic/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spell-epic",
3
- "version": "0.8.5",
3
+ "version": "0.8.6",
4
4
  "private": true,
5
5
  "type": "module"
6
6
  }