spell 0.8.7 → 0.8.9

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 (304) hide show
  1. package/README-epics.md +149 -49
  2. package/app/package.json +25 -1
  3. package/app/spaces/@spell/guides/SpellUI/SpellUI.spellml +486 -486
  4. package/app/spaces/@spell/sites/SpellApp/SpellApp.spellml +50 -124
  5. package/dist/app/app/pages/SiteBoardView.css +5 -5
  6. package/dist/app/app/pages/SiteBoardView.js +1 -1
  7. package/dist/app/app/pages/SiteEditorPage.js +6 -3
  8. package/dist/app/app/pages/SiteEdits.js +27 -10
  9. package/dist/app/app/pages/SiteWrites.js +11 -0
  10. package/dist/app/app/runner/spellRuntime.js +1 -0
  11. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  12. package/dist/cli/publish/PublishedPackage.js +6 -3
  13. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  14. package/dist/cli/publish/ScratchInstall.js +69 -8
  15. package/dist/epic/cli/EpicProgram.js +20 -5
  16. package/dist/epic/cli/epicGroups.js +7 -1
  17. package/dist/epic/command/BaseBranch.d.ts +35 -0
  18. package/dist/epic/command/BaseBranch.js +58 -0
  19. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  20. package/dist/epic/command/EpicCheckout.js +4 -4
  21. package/dist/epic/command/EpicGuide.js +3 -2
  22. package/dist/epic/command/EpicTools.d.ts +5 -0
  23. package/dist/epic/command/EpicTools.js +14 -3
  24. package/dist/epic/command/MainMerge.d.ts +26 -15
  25. package/dist/epic/command/MainMerge.js +60 -16
  26. package/dist/epic/command/PullRequest.d.ts +45 -0
  27. package/dist/epic/command/PullRequest.js +100 -0
  28. package/dist/epic/command/RepoInit.d.ts +196 -39
  29. package/dist/epic/command/RepoInit.js +481 -60
  30. package/dist/epic/command/Requests.d.ts +1 -0
  31. package/dist/epic/command/Requests.js +7 -1
  32. package/dist/epic/command/SessionMoves.js +2 -1
  33. package/dist/epic/command/SkillsCheck.js +3 -2
  34. package/dist/epic/command/Stock.js +3 -1
  35. package/dist/epic/command/TurnEnd.d.ts +1 -1
  36. package/dist/epic/command/TurnEnd.js +4 -3
  37. package/dist/epic/command/Worktrees.d.ts +20 -3
  38. package/dist/epic/command/Worktrees.js +39 -7
  39. package/dist/epic/command/command.types.d.ts +3 -0
  40. package/dist/epic/components/__pack/epics.entry.js +43 -43
  41. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  42. package/dist/epic/config/CodeHost.d.ts +96 -0
  43. package/dist/epic/config/CodeHost.js +89 -0
  44. package/dist/epic/config/EngineFiles.mjs +60 -0
  45. package/dist/epic/config/EpicConfig.d.ts +20 -3
  46. package/dist/epic/config/EpicConfig.js +25 -1
  47. package/dist/epic/config/EpicRepo.js +1 -1
  48. package/dist/epic/config/GitHub.d.ts +75 -3
  49. package/dist/epic/config/GitHub.js +106 -5
  50. package/dist/epic/config/GitLab.d.ts +138 -0
  51. package/dist/epic/config/GitLab.js +297 -0
  52. package/dist/epic/config/LayeredSettings.js +3 -2
  53. package/dist/epic/server/EpicServer.d.ts +1 -1
  54. package/dist/epic/server/EpicServer.js +26 -12
  55. package/dist/epic/tool/InboxPoller.mjs +2 -1
  56. package/dist/epic/tool/MigrateCommands.js +6 -8
  57. package/dist/epic/tool/PlanCommits.d.ts +7 -4
  58. package/dist/epic/tool/PlanCommits.js +7 -5
  59. package/dist/epic/tool/PlanDocCommands.js +3 -4
  60. package/dist/epic/tool/PlanDocFiles.d.ts +3 -1
  61. package/dist/epic/tool/PlanDocFiles.js +13 -5
  62. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  63. package/dist/epic/tool/ServedFolders.js +4 -4
  64. package/dist/epic/tools/PageInboxes.js +3 -3
  65. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  66. package/dist/epic/tools/_assets/commands.js +20 -2073
  67. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  68. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  69. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  103. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  104. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  105. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  106. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  107. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  108. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  109. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  110. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  111. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  112. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  113. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  114. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  115. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  116. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  117. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  118. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  119. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  120. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  121. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  122. package/dist/epic/tools/_assets/goals-live.js +318 -210
  123. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  124. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  125. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  126. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  127. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  128. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  129. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  130. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  131. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  132. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  133. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  134. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  135. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  136. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  137. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  138. package/dist/epic/tools/pages.d.ts +5 -6
  139. package/dist/epic/tools/pages.js +7 -6
  140. package/dist/epic/window.mjs +2 -3
  141. package/dist/parser/core/classes/View.d.ts +20 -0
  142. package/dist/parser/core/classes/View.js +91 -17
  143. package/dist/parser/core/core.declarations.json5 +18 -0
  144. package/dist/parser/core/core.scopes.js +5 -0
  145. package/dist/parser/core/sites.d.ts +10 -0
  146. package/dist/parser/core/sites.js +12 -0
  147. package/dist/parser/parser/tokenizer/Tokenizer.d.ts +9 -1
  148. package/dist/parser/parser/tokenizer/Tokenizer.js +43 -5
  149. package/dist/parser/parser/tokenizer/Tokens.d.ts +4 -0
  150. package/dist/parser/parser/tokenizer/Tokens.js +4 -0
  151. package/dist/parser/parser/tokenizer/tokenizer.types.d.ts +5 -0
  152. package/dist/parser/parser/tokenizer/tokenizer.types.js +2 -0
  153. package/dist/parser/py/core/spell_core/apps.py +2 -0
  154. package/dist/parser/spell/PARSING.md +21 -0
  155. package/dist/parser/spell/SpellParser.d.ts +2 -0
  156. package/dist/parser/spell/SpellParser.js +58 -3
  157. package/dist/parser/spell/SpellxTokenizer.js +2 -1
  158. package/dist/parser/spell/SpellxTwin.d.ts +4 -1
  159. package/dist/parser/spell/SpellxTwin.js +10 -3
  160. package/dist/parser/spell/builtinTypes.js +24 -1
  161. package/dist/parser/spell/ingest/PlaceIngest.js +3 -1
  162. package/dist/parser/spell/languages/Language.d.ts +11 -2
  163. package/dist/parser/spell/languages/en/words.js +3 -2
  164. package/dist/parser/spell/languages/es/words.js +7 -4
  165. package/dist/parser/spell/rules/Statement.js +1 -1
  166. package/dist/parser/spell/rules/classes/DrawSlot.js +6 -1
  167. package/dist/parser/spell/rules/sites/SitePage.d.ts +3 -3
  168. package/dist/parser/spell/rules/sites/SitePage.js +2 -2
  169. package/dist/parser/spell/rules/sites/sites.en.js +1 -1
  170. package/dist/parser/spell/rules/sites/sites.es.js +1 -1
  171. package/dist/parser/spell/rules/sites/sites.shared.d.ts +2 -2
  172. package/dist/parser/spell/spell.types.d.ts +7 -0
  173. package/dist/parser/spell/spellSyntax.es.json +6 -6
  174. package/dist/parser/spell/spellSyntax.json +6 -6
  175. package/dist/parser/spellx/SpellxView.js +2 -1
  176. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  177. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  178. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  179. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  180. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  181. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  182. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  183. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  184. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  185. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  186. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  187. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  188. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  189. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  190. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  191. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  192. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  193. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  194. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  195. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  196. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  197. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  198. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  199. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  200. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  201. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  202. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  203. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  204. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  205. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  206. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  207. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  208. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  209. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  210. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  211. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  212. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  213. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  214. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  215. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  216. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  217. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  218. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  219. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  220. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  221. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  222. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  223. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  224. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  225. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  226. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  227. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  228. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  229. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  230. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  231. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  232. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  233. package/dist/ui/components/ui-parts/UIHeader.d.ts +15 -3
  234. package/dist/ui/components/ui-parts/UIHeader.en.d.ts +5 -2
  235. package/dist/ui/components/ui-parts/UIHeader.en.js +6 -3
  236. package/dist/ui/components/ui-parts/UIHeader.js +45 -5
  237. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  238. package/dist/ui/components/ui-parts/UIParts.css +18 -0
  239. package/dist/ui/components/ui-parts/UIParts.css.inline.js +1 -1
  240. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  241. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  242. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  243. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  244. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  245. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  246. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  247. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  248. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  249. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  250. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  251. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  252. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  253. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  254. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  255. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  256. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  257. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  258. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  259. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  260. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  261. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  262. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  263. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  264. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  265. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  266. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  267. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  268. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  269. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  270. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  271. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  272. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  273. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  274. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  275. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  276. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  277. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  278. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  279. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  280. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  281. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  282. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  283. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  284. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  285. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  286. package/dist/ui/jsx.d.ts +4 -4
  287. package/dist/ui/vocabulary/defaults.generated.js +1 -1
  288. package/dist/util/spell/constants.js +1 -1
  289. package/epic/.claude-plugin/plugin.json +1 -1
  290. package/epic/.codex-plugin/plugin.json +1 -1
  291. package/epic/hooks/handoff.mjs +4 -3
  292. package/epic/hooks/worktree.mjs +22 -3
  293. package/epic/package.json +41 -2
  294. package/epic/skills/details/SKILL.md +2 -1
  295. package/epic/skills/epic/SKILL.md +7 -1
  296. package/epic/skills/epic/guide.md +3 -0
  297. package/epic/skills/isolate/SKILL.md +53 -20
  298. package/epic/src/AGENTS.md +11 -2
  299. package/epic/templates/durable.html +1 -1
  300. package/epic/vscode/package.json +1 -1
  301. package/epic/vscode/spell-epic.vsix +0 -0
  302. package/package.json +1 -1
  303. package/parser/package.json +1 -1
  304. package/ui/package.json +15 -2
@@ -1,13 +1,89 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
-
4
- // src/tools/_assets/spell-doc-runtime.js
5
- import { nextFrame } from "spell/util/dom";
6
- import { clamp } from "spell/util/number";
7
- import { PrefStore } from "spell/util/persist/PrefStore";
8
- import { slug } from "spell/util/string";
9
- import { PagePatch } from "spell/server/site";
10
- import { wireComments } from "./spell-doc-comments.js";
1
+ /*
2
+ * Page behaviour for the `.html` docs.
3
+ * Bundled into `spell-ui.js` (a classic IIFE, beside spell-ui) by `scripts/bundle-spell-ui.js`;
4
+ * side effects only. The page's markup is hand-authored; this only DRIVES it.
5
+ * - Two page markups, read into ONE outline (`outlineOf()`) that everything below works from:
6
+ * - SECTIONS (every page but the saga pages):
7
+ * `<ui-section id label sticky collapsible dividing>` in `main`, nested for sub-sections,
8
+ * `open="false"` to start folded.
9
+ * - the element draws the title, the fold button, the rule and the stack of stuck titles
10
+ * - this runtime sets the top-level `offset`s, remembers folds, writes counts
11
+ * - an EPIC PAGE is `<epic-page>` markup (the `epics` pack, `spell-epic`):
12
+ * its folding blocks (`<epic-overview>`, `<epic-section>`, `<epic-phase>`, `EPIC_FOLDS`) are its sections.
13
+ * They draw and stick themselves, count their items, filter them,
14
+ * and draw the page header, the review line, the commits and every review control;
15
+ * this runtime only lists them (each host's `contentsEntry`, with label, icon and count),
16
+ * remembers their folds, and lands links inside them
17
+ * - HEADINGS (the saga pages): `section.s2|s3` > `<ui-sticky class="spell-h2|spell-h3">` > `<h2|h3 id>`;
18
+ * this runtime adds the fold chevrons and every sticky's `offset`
19
+ * - the TOOLBAR, the page's one navigation (epic `airplane` P8; the floating right-edge rail before):
20
+ * a row of the top-level sections' buttons, the last row of the sticky page header (`buildPageToolbar()`)
21
+ * - mark and title, the titles shrinking, then gone on a narrow window
22
+ * - No contents list: Owen, 2026-10-08
23
+ * - an EPIC PAGE's (`buildToolbar()`): its blocks' icons only, with badges of the items waiting on the person,
24
+ * in `<epic-page>`'s header; and Cmd / Ctrl + K asks for an item to jump to (`wireJumpKey()`)
25
+ * - at its right, on any page that takes comments, a bullhorn counting the threads waiting on the person,
26
+ * landing on the next at each click (`PageComments.drawWaiting()`); Cmd / Ctrl + K takes a comment's id too (`C3`)
27
+ * - sticky headers: the page header (`ui-sticky.spell-h1`) sticks at the top, each top-level title below it,
28
+ * nested ones below their parents' (re-measured on resize);
29
+ * CSS variables on the sections let anchors land below them all
30
+ * - everything that sticks or lands at the top starts BELOW the fixed site header (`<spell-site-header>`,
31
+ * `siteHeaderHeight()`): the page header and its toolbar, the titles
32
+ * - folding: every section folds from a chevron on its title; folds are remembered per page, and `open="false"`
33
+ * (`data-fold="closed"` on HEADINGS pages) starts one folded
34
+ * - counts: a top-level section holding `[data-status]` items (the Epics index's epic cards, the saga pages' items)
35
+ * shows open / all on its title;
36
+ * the toolbar shows, with a red badge, how many NEED OWEN (none: no badge; `countItems()`);
37
+ * an epic card section also gets state chips with counts, filtering its items (`wireItemFilters()`)
38
+ * - scroll-follow: the toolbar's button of the section being read is highlighted, and the address follows it
39
+ * - links to any id in `main` (a section, a heading, a plan item) land below the stuck titles,
40
+ * unfolding what hides it; a `#hash` in another case than the page's id (`#T1` for `t1`) lands too
41
+ * - SHORT ADDRESSES (`wireAddresses()`, epic `epic-workflow` P15):
42
+ * a link to `SAGA:/<saga>[/<epic>][#<id>]` becomes the saga or epic page and its `#id`, so both kinds of link work
43
+ * - the CHEATSHEET card filters
44
+ * - highlight.js, when the page loaded it
45
+ * - COMMENTS (`wireComments()`), served by the page server:
46
+ * - a bullhorn beside every major block (and in the page header), and ⌘ I or a floating bullhorn on selected text,
47
+ * which open a comment box under the block
48
+ * - the comments wait in an inbox file (a docs page's own, an epic page's review inbox), drawn under their blocks
49
+ * - their own module, `spell-doc-comments.js` (epic `epic-engine` P2), which Epic UI's pages load alone too
50
+ * - PAGE NOTES (`wireNotes()`), written into docs pages before them: each `<spell-note>` a folded card
51
+ * - SCREENSHOTS open full size (`wireImageZoom()`, epic `epic-engine` I129): a click on a content image (one shown
52
+ * smaller than its size, in a `<figure>`, or in a link to an image) shows it over the page, in Spell UI's
53
+ * `<ui-zoom>` (epic `ui-gaps` P14), never following its link; the rule is `ImageZoom`'s
54
+ * - the EPICS PAGE's sort buttons, `<epic-sort>`, in its header (`wireEpicSort()`):
55
+ * its list, its cards' stars and saga chips are the epics pack's elements (`<epic-list>`, `<epic-card>`),
56
+ * which do their own
57
+ * LANDING -- where a jump puts its target, ONE model for every kind of jump:
58
+ * - the line: just below the lowest title that will be stuck over the target: site header + `--spell-top` (page
59
+ * header, filter bar) + the stack of the target's sections' titles
60
+ * - CSS `scroll-margin-top` holds that line MINUS the site header (`spell-doc.css`); the site header is added by
61
+ * whoever does the scrolling, once:
62
+ * - our jumps (link clicks, a `#hash` load, `hashchange` / `popstate`, so also `location.hash = id`):
63
+ * `scrollTo()` with a computed top, which `scroll-padding` never touches: `offsetFor()` adds the site header
64
+ * - the browser's own (a `#hash` before this runs, `scrollIntoView()`, focus):
65
+ * `:root`'s `scroll-padding-top`, the site header's height (`<spell-site-header>` installs it)
66
+ * - paging (Page Down / Up, Space): ours (`wirePaging()`), measured at the destination:
67
+ * the old bottom lands just below the titles stuck THERE
68
+ * - the browser's own paging (where ours stands aside) goes by `scroll-padding-top`:
69
+ * while titles are stuck, `<ui-section>` / `<ui-sticky>` (`StickyWatch`) write the lowest stuck edge
70
+ * as an INLINE `scroll-padding-top` on `<html>`, overriding `:root`'s; removed once none is stuck
71
+ * - it includes the site header: titles stick below it
72
+ * - that's where it STARTS, so a title that sticks on the way can cover the old bottom
73
+ * - NOTE: a browser jump made WHILE titles are stuck adds that inline padding to the margin, landing one stack lower:
74
+ * every such jump that changes the hash (`hashchange`) lands again through ours;
75
+ * `scrollIntoView()` from code doesn't --
76
+ * call `jump`'s path (a click on a `#id` link, or set `location.hash`) instead
77
+ * NOTE: panels open and close through the accordion's `open` PROPERTY (panel indexes as text):
78
+ * that's `<ui-accordion>`'s controlled state, and writing it announces nothing (`ui-opening` / `ui-closing` mean the person).
79
+ */
80
+
81
+ import { nextFrame } from "spell/util/dom"
82
+ import { clamp } from "spell/util/number"
83
+ import { PrefStore } from "spell/util/persist/PrefStore"
84
+ import { slug } from "spell/util/string"
85
+ import { PagePatch } from "spell/server/site"
86
+ import { wireComments } from "./spell-doc-comments.js"
11
87
  import {
12
88
  FIELDS,
13
89
  addBlockAction,
@@ -23,7 +99,7 @@ import {
23
99
  restoreEpicFolds,
24
100
  titleInside,
25
101
  writeJSON
26
- } from "./spell-doc-helpers.js";
102
+ } from "./spell-doc-helpers.js"
27
103
  import {
28
104
  removeToolbar,
29
105
  shortLabel,
@@ -32,16 +108,21 @@ import {
32
108
  toolbarMenu,
33
109
  toolbarTools,
34
110
  wireJumpKey
35
- } from "./spell-doc-toolbar.js";
36
- import { readingTime } from "../ReadingTime.js";
37
- import { EpicAddress, PageTargets } from "../../links/index.js";
38
- import { PageStages } from "../../phases/index.js";
39
- import { ServerLink } from "../../review/index.js";
40
- import { ImageZoom } from "spell/ui/components/ui-zoom/ImageZoom";
41
- import { ComponentPacks } from "spell/ui/components/ui-components";
42
- import { HashLanding } from "spell/ui/components/ui-toc/HashLanding";
43
- import { TocIndex } from "spell/ui/components/ui-toc/TocIndex";
44
- var TAGS = [
111
+ } from "./spell-doc-toolbar.js"
112
+ import { readingTime } from "spell/epic/tools/ReadingTime.js"
113
+ import { EpicAddress, PageTargets } from "spell/epic/links"
114
+ import { PageStages } from "spell/epic/phases"
115
+ import { ServerLink } from "spell/epic/review"
116
+ // plain DOM, no Solid: the element it opens, `<ui-zoom>`, is Spell UI's, which this bundle loads like any other
117
+ import { ImageZoom } from "spell/ui/components/ui-zoom/ImageZoom"
118
+ import { ComponentPacks } from "spell/ui/components/ui-components"
119
+ // the doc-only families' plain-DOM leaves, bundled from source (`bundle-spell-ui.js`): Spell UI's docs land links and
120
+ // follow the scroll the same way (epic `coherence` P11)
121
+ import { HashLanding } from "spell/ui/components/ui-toc/HashLanding"
122
+ import { TocIndex } from "spell/ui/components/ui-toc/TocIndex"
123
+
124
+ /** Custom elements this runtime drives: wait for their definitions before wiring. */
125
+ const TAGS = [
45
126
  "ui-accordion",
46
127
  "ui-title",
47
128
  "ui-content",
@@ -56,806 +137,1362 @@ var TAGS = [
56
137
  "ui-section",
57
138
  // installs `--spell-site-header-height`, which every sticky line starts from
58
139
  "spell-site-header"
59
- ];
60
- var UNFOLD_FRAMES = 2;
61
- var SETTLE_MS = 450;
62
- var OPENING = ["ui-opening", "ui-opening"];
63
- var CLOSING = ["ui-closing", "ui-closing"];
64
- var LOADED = "ui-loaded";
65
- var FOLD_HOLD_MS = 600;
66
- var RESTORE_HOLD_MS = 1500;
67
- var BODY_WAIT_MS = 1e3;
68
- var READER_INPUT = ["wheel", "touchstart", "keydown", "pointerdown"];
69
- var EPIC_FOLDS = "epic-overview, epic-section, epic-phase";
70
- var EPIC_OPENERS = `${EPIC_FOLDS}, epic-item`;
71
- var FIELDS_THAT_FOLD = "epic-field";
72
- var SECTIONS = `ui-section, ${EPIC_FOLDS}`;
73
- var FOLDING = `${SECTIONS}, ui-accordion`;
74
- var EPIC_WAIT_MS = 5e3;
75
- var EPICS_PACK = "/_epic/pack/epics.pack.js";
76
- var PAGE_TITLE = ":scope > ui-sticky.spell-h1 > .spell-page-head > h1";
77
- var EPIC_LAND_GAP = 8;
78
- var FILTER_KEY_PREFIX = "spell-filter:";
79
- var FOLD_KEY_PREFIX = "spell-folds:";
80
- var KEPT_FOLDS_KEY_PREFIX = "spell-doc:kept-folds:";
81
- var ITEM_FILTER_KEY_PREFIX = "spell-item-state:";
82
- var QUIET_LOAD_MS = 2500;
83
- var QUIET_PATCH_MS = 900;
84
- var quietTimer = 0;
85
- var foldWiring = null;
86
- quietFor(QUIET_LOAD_MS);
87
- if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start, { once: true });
88
- else void start();
140
+ ]
141
+
142
+ /**
143
+ * Frames a `<ui-section>` takes to draw what opening it (`open`) revealed: the write lands on a microtask, the
144
+ * render on the next frame. A jump lands only then: before, the target is laid out in a box of no height.
145
+ */
146
+ const UNFOLD_FRAMES = 2
147
+
148
+ /**
149
+ * When a jump on a `<ui-section>` page lands once more, unless the reader scrolled since:
150
+ * a fold the BROWSER opened (a `#hash` load reveals `hidden="until-found"` content itself) grows with its transition
151
+ * (`--ui-section-duration`, 300ms) and moves the target a few pixels after the first landing.
152
+ */
153
+ const SETTLE_MS = 450
154
+
155
+ /**
156
+ * The events a fold sends as the reader opens or closes it, and a source host as its body arrives:
157
+ * - a `<ui-section>`'s (`ui-opening`, `ui-closing`; its old names went in epic `repo-split` P14)
158
+ * - an `<epic-*>` block's and a `<ui-accordion>`'s (`ui-opening`, `ui-closing`)
159
+ * - every source host's body: `ui-loaded` (Spell UI's `LoadableBody`, the `<epic-*>` blocks' too)
160
+ */
161
+ const OPENING = ["ui-opening", "ui-opening"]
162
+ const CLOSING = ["ui-closing", "ui-closing"]
163
+ const LOADED = "ui-loaded"
164
+
165
+ /** How long a closing fold's header is held in place (`holdWhileFolding()`): its transition (300ms) and a margin. */
166
+ const FOLD_HOLD_MS = 600
167
+
168
+ /**
169
+ * How long a live reload holds the page at its saved scroll (`holdScroll()`), ms: while the folds it put back draw,
170
+ * and their parts load.
171
+ */
172
+ const RESTORE_HOLD_MS = 1500
173
+
174
+ /**
175
+ * How long a part's body swapped in may hold the old one on screen, in ms (`reloadBody()`'s cross-fade): the page
176
+ * shows the old frame meanwhile, and takes no clicks
177
+ */
178
+ const BODY_WAIT_MS = 1000
179
+
180
+ /** What the reader does that stops the page landing by itself: he's moving it. */
181
+ const READER_INPUT = ["wheel", "touchstart", "keydown", "pointerdown"]
182
+
183
+ /**
184
+ * An epic page's folding blocks (`spell-epic`): its sections, in the outline, the folds and the landing.
185
+ * Each host has `open` (page state) and `contentsEntry` (`EpicFoldHost`).
186
+ */
187
+ const EPIC_FOLDS = "epic-overview, epic-section, epic-phase"
188
+
189
+ /** What a link into an epic page opens on its way: the folding blocks, and the items (which fold too). */
190
+ const EPIC_OPENERS = `${EPIC_FOLDS}, epic-item`
191
+
192
+ /**
193
+ * The fields that fold inside an epic page's blocks (`<epic-field>`, epic `epic-engine` I167): `reveal()` opens one a
194
+ * link or a comment lands in, through its own `reveal()`.
195
+ */
196
+ const FIELDS_THAT_FOLD = "epic-field"
197
+
198
+ /** Every element the outline takes for a section: `<ui-section>`s and an epic page's folding blocks. */
199
+ const SECTIONS = `ui-section, ${EPIC_FOLDS}`
200
+ /** What folds, for `holdWhileFolding()`: the sections and epic blocks, and accordions (asides, code) */
201
+ const FOLDING = `${SECTIONS}, ui-accordion`
202
+
203
+ /**
204
+ * How long `start()` waits for an epic page's elements (the `epics` pack, loaded by `<ui-root>`) to define and draw,
205
+ * before listing the page without them: a pack that never loads must not hold up the rest.
206
+ */
207
+ const EPIC_WAIT_MS = 5000
208
+
209
+ /**
210
+ * The `epics` pack's script at the engine's route (`EpicServer`'s `/_epic/pack/`), as epic pages name it:
211
+ * what `loadEpicsPack()` loads on a page that names none.
212
+ */
213
+ const EPICS_PACK = "/_epic/pack/epics.pack.js"
214
+
215
+ /** The docs head's h1, its title (`oneLineHead()`): an epic page has none, `<epic-page>` draws its own. */
216
+ const PAGE_TITLE = ":scope > ui-sticky.spell-h1 > .spell-page-head > h1"
217
+
218
+ /**
219
+ * Space between the stuck titles and an element a link lands on inside an epic page, px: the page's own lander's
220
+ * (`landingLine()`), the ONE landing on an epic page since epic `coherence` P18.
221
+ */
222
+ const EPIC_LAND_GAP = 8
223
+
224
+ /**
225
+ * `localStorage` key prefix of a page's card filter: then its path, or the name its input gives (`data-spell-filter`).
226
+ * - per page: every `file://` page shares one origin, so one key would leak a filter between cheat sheets
227
+ * - a named one was kept under its name alone before epic `prefs-and-undo` P4: moved over once (`wireFilter()`)
228
+ */
229
+ const FILTER_KEY_PREFIX = "spell-filter:"
230
+
231
+ /** `localStorage` key prefix of a page's folds (`{ [section or heading id]: folded }`), per page like the filter's. */
232
+ const FOLD_KEY_PREFIX = "spell-folds:"
233
+
234
+ /** `sessionStorage` key prefix of the folds a live reload puts back (`{ [id]: open }`, `keepFoldsForReload()`). */
235
+ const KEPT_FOLDS_KEY_PREFIX = "spell-doc:kept-folds:"
236
+
237
+ /**
238
+ * `localStorage` key prefix of a page's item filters (`{ [section id]: [states shown] }`), per page.
239
+ * - `<epic-section>`'s own key too (its `FILTER_KEY`), the same shape
240
+ * - NOTE: not `spell-item-filter:`, Open | All's before P3 of `review-review`: its saved "open" meant "not done"
241
+ */
242
+ const ITEM_FILTER_KEY_PREFIX = "spell-item-state:"
243
+
244
+ /** How long a page coming up stays still (`quietFor()`): its folds put back and its scroll held (`RESTORE_HOLD_MS`). */
245
+ const QUIET_LOAD_MS = 2500
246
+
247
+ /** How long a live patch keeps the page still (`quietFor()`): its re-wiring, a frame or two, and what settles after. */
248
+ const QUIET_PATCH_MS = 900
249
+
250
+ /** The timer ending the page's quiet (`quietFor()`). */
251
+ let quietTimer = 0
252
+
253
+ /** The listeners of the last `wireFolds()` call: aborted by the next, so a rebuilt page doesn't double them. */
254
+ let foldWiring = null
255
+
256
+ // still, from the first moment: a page coming up draws its folds and marks as they ARE, never animating into them
257
+ quietFor(QUIET_LOAD_MS)
258
+ if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start, { once: true })
259
+ else void start()
260
+
261
+ /**
262
+ * QUIET (Owen, 2026-10-25: "part of the reason the page continually flashes is that you are running animations when
263
+ * updating / reloading the page ... if page is already loaded, skip the animations"): no motion for `ms` from now,
264
+ * longer if asked again meanwhile.
265
+ * - `<html data-spell-quiet>`: `spell-doc.css` sets every duration token to 0s under it (Spell UI's
266
+ * `--ui-duration-*`, `--ui-section-duration`, the epic elements' `--epic-*-duration`), which reach every shadow root
267
+ * - the page's load (until it has settled: folds put back, the scroll held) and every live patch; a fold the reader
268
+ * clicks after that still animates
269
+ */
89
270
  function quietFor(ms) {
90
- const root = document.documentElement;
91
- root.dataset.spellQuiet = "";
92
- clearTimeout(quietTimer);
93
- quietTimer = setTimeout(() => delete root.dataset.spellQuiet, ms);
271
+ const root = document.documentElement
272
+ root.dataset.spellQuiet = ""
273
+ clearTimeout(quietTimer)
274
+ quietTimer = setTimeout(() => delete root.dataset.spellQuiet, ms)
94
275
  }
95
- __name(quietFor, "quietFor");
276
+
277
+ ////////////////
278
+ // ## Start
279
+ ////////////////
280
+
281
+ /** Highlight at once (plain DOM); wire the widgets once their elements are defined. */
96
282
  async function start() {
97
- loadEpicsPack();
98
- nameTab();
99
- const main = document.querySelector("main.spell-doc-main") ?? document.querySelector("main");
100
- if (!main) return;
101
- const landing = { hash: hashId(), scroll: window.SPELL_SERVER?.takeScroll?.() };
102
- const kept = takeKeptFolds(landing.scroll !== void 0);
103
- keepFoldsForReload(main);
104
- if (landing.scroll !== void 0) {
105
- landing.hash = void 0;
106
- if (location.hash) history.replaceState(history.state, "", `${location.pathname}${location.search}`);
107
- } else if (landing.hash && landing.hash !== TocIndex.decode(location.hash.slice(1)))
108
- history.replaceState(null, "", `#${landing.hash}`);
109
- const live = wireLiveUpdate(main);
110
- editMarkdownInPlace([main]);
111
- highlight();
112
- addCodeCopies(main);
113
- wireImageZoom();
283
+ loadEpicsPack()
284
+ nameTab()
285
+ const main = document.querySelector("main.spell-doc-main") ?? document.querySelector("main")
286
+ if (!main) return
287
+ // where to land, read before anything scrolls: scroll-follow rewrites the address as the page moves
288
+ const landing = { hash: hashId(), scroll: window.SPELL_SERVER?.takeScroll?.() }
289
+ // a LIVE reload (the page's code changed) comes back as the reader left it: every fold, and the scroll
290
+ const kept = takeKeptFolds(landing.scroll !== undefined)
291
+ keepFoldsForReload(main)
292
+ if (landing.scroll !== undefined) {
293
+ // never the section the address names: `<epic-*>` blocks follow the address's `#hash` by themselves as they
294
+ // first connect, and landed on its top (I23 of `epic-engine`); the address follows the scroll again once landed
295
+ landing.hash = undefined
296
+ if (location.hash) history.replaceState(history.state, "", `${location.pathname}${location.search}`)
297
+ }
298
+ // an old phase address (`#p7`) shows the phase's stable id it landed on (`addressedId()`)
299
+ else if (landing.hash && landing.hash !== TocIndex.decode(location.hash.slice(1)))
300
+ history.replaceState(null, "", `#${landing.hash}`)
301
+ // listening at once: an edit that comes in while this is still wiring waits for `live.ready()`
302
+ const live = wireLiveUpdate(main)
303
+ editMarkdownInPlace([main])
304
+ highlight()
305
+ addCodeCopies(main)
306
+ wireImageZoom()
307
+ // an epic page: its saved folds before its blocks first draw (so nothing animates), then the blocks, which the
308
+ // outline reads (their labels, icons and counts)
114
309
  if (main.querySelector("epic-page")) {
115
310
  restoreEpicFolds(main.querySelectorAll(kept ? EPIC_OPENERS : EPIC_FOLDS), {
116
311
  saved: readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`),
117
312
  kept
118
- });
119
- await epicsDrawn(main);
120
- }
121
- const outline = outlineOf(main);
122
- oneLineHead(main);
123
- wireReadingTime(main);
124
- const counts = countItems(outline);
125
- if (outline.sections) wireItemFilters(main);
126
- else markItemStates(main);
127
- const rail = buildNavigation(main, outline, counts);
128
- const folds = wireFolds(main, outline, kept);
129
- addFoldAll(main, folds);
130
- const used = TAGS.filter((tag) => document.querySelector(tag));
131
- await Promise.all(used.map((tag) => customElements.whenDefined(tag)));
132
- const sticky = trackStickyHeights(main, outline);
133
- const follow = followScroll(main, outline, rail);
134
- wireAddresses();
135
- const { jump, go, canGo } = wireAnchors(main, outline, sticky, follow, folds);
136
- wirePaging(main);
137
- wireJumpKey(go, canGo);
138
- wireFilter(main);
139
- wireTableWidths(main);
140
- wireTwoColumnTables(main);
141
- wireTableHeads(main);
142
- wireStuckTrail(main);
143
- await nextFrame(2);
144
- sticky.measure();
145
- land(landing, jump, follow);
146
- void Promise.resolve(window.SpellUI?.themed).then(() => window.SPELL_SERVER?.reveal?.());
147
- live.ready({ main, rail, sticky, follow, entries: railKey(outline, counts) });
148
- wireNotes(main);
149
- void wireComments(main, { go, pageFolds: folds });
150
- stackWrappedSteps(main);
151
- wireNewEpic(main);
152
- wireEpicSort(main);
313
+ })
314
+ await epicsDrawn(main)
315
+ }
316
+ const outline = outlineOf(main)
317
+ oneLineHead(main)
318
+ wireReadingTime(main)
319
+ const counts = countItems(outline)
320
+ // the saga pages (HEADINGS) get no filter, but their id chips are coloured by state too
321
+ if (outline.sections) wireItemFilters(main)
322
+ else markItemStates(main)
323
+ const rail = buildNavigation(main, outline, counts)
324
+ // before the sections first draw, so a saved fold doesn't animate shut
325
+ const folds = wireFolds(main, outline, kept)
326
+ addFoldAll(main, folds)
327
+ const used = TAGS.filter((tag) => document.querySelector(tag))
328
+ await Promise.all(used.map((tag) => customElements.whenDefined(tag)))
329
+ const sticky = trackStickyHeights(main, outline)
330
+ const follow = followScroll(main, outline, rail)
331
+ // before the anchors: a short address into this page becomes a `#id` link they take
332
+ wireAddresses()
333
+ const { jump, go, canGo } = wireAnchors(main, outline, sticky, follow, folds)
334
+ wirePaging(main)
335
+ wireJumpKey(go, canGo)
336
+ wireFilter(main)
337
+ wireTableWidths(main)
338
+ wireTwoColumnTables(main)
339
+ wireTableHeads(main)
340
+ wireStuckTrail(main)
341
+ // UI renders its shadow content a little after the definitions: land once it has
342
+ await nextFrame(2)
343
+ sticky.measure()
344
+ land(landing, jump, follow)
345
+ // a live reload held the new page behind the old one until now: it cross-fades in, landed and themed (I164)
346
+ void Promise.resolve(window.SpellUI?.themed).then(() => window.SPELL_SERVER?.reveal?.())
347
+ live.ready({ main, rail, sticky, follow, entries: railKey(outline, counts) })
348
+ wireNotes(main)
349
+ void wireComments(main, { go, pageFolds: folds })
350
+ stackWrappedSteps(main)
351
+ wireNewEpic(main)
352
+ wireEpicSort(main)
353
+ // the docs index tool rewrites this page after a new epic: its header comes back without the pill and the sort
153
354
  addEventListener("spell-doc:updated", () => {
154
- wireNewEpic(main);
155
- wireEpicSort(main);
156
- });
355
+ wireNewEpic(main)
356
+ wireEpicSort(main)
357
+ })
157
358
  }
158
- __name(start, "start");
359
+
360
+ /**
361
+ * Load the `epics` pack on EVERY page this runtime runs on (epic `epic-engine` P3), so an `<epic-*>` element in it,
362
+ * written or drawn by our tools, upgrades: a guide, a list or details page, the changelog, not only an epic page.
363
+ * - Through `ComponentPacks.load()`, as `<ui-root>` loads a `<ui-components source>`: ONE script per page, keyed by
364
+ * its URL, the pack registered once. So a page that names the pack already (an epic page's root, a saga page's old
365
+ * path) loads it by THAT source, and its root's load and this one are the same.
366
+ * - No `<ui-root>` needed: the pack defines its tags for the whole document. Most guides have none.
367
+ * - Async (a `<script>` added): it never holds up the first paint, or `start()`.
368
+ * An element made before it registers upgrades as it does; wait with `customElements.whenDefined()`.
369
+ * - A pack that can't load (a page from `file://`): a console warning, and the page goes on without.
370
+ */
159
371
  function loadEpicsPack() {
160
- const declared = [...document.querySelectorAll("ui-components[source]")].map((element) => element.getAttribute("source")).find((source) => source && ComponentPacks.nameFor(new URL(source, document.baseURI).href) === "epics");
161
- ComponentPacks.load(declared ?? EPICS_PACK).catch((error) => console.warn("spell-doc: the epics pack", error));
372
+ const declared = [...document.querySelectorAll("ui-components[source]")]
373
+ .map((element) => element.getAttribute("source"))
374
+ .find((source) => source && ComponentPacks.nameFor(new URL(source, document.baseURI).href) === "epics")
375
+ ComponentPacks.load(declared ?? EPICS_PACK).catch((error) => console.warn("spell-doc: the epics pack", error))
162
376
  }
163
- __name(loadEpicsPack, "loadEpicsPack");
377
+
378
+ /**
379
+ * The page's head on ONE line, as an epic page's: `DOCS / SPELL SYNTAX`, the crumbs then the title,
380
+ * in the crumbs' own type, the title twice their size and bold (`spell-doc.css`, "The page's head on one line").
381
+ * - Owen, 2026-10-13: "Make the header changes in the other doc files"
382
+ * - a copy of the page's breadcrumb (`.spell-crumbs`, before the sticky head) goes INTO the h1, before its text;
383
+ * `data-spell-added`, so a live update steps around it
384
+ * - its last section (the page itself) stays, emptied: the title says its words;
385
+ * so the `/` before the title is the breadcrumb's own divider (epic `epic-engine` P3: a `<span>` of ours before)
386
+ * - the breadcrumb itself stays where it was, hidden (`<body class="spell-one-line-head">`):
387
+ * live updates still patch it, and the copy follows when the page reloads
388
+ * - a page with no breadcrumb: the title alone, in the same type
389
+ */
164
390
  function oneLineHead(main) {
165
- const h1 = main.querySelector(PAGE_TITLE);
166
- if (!h1) return;
167
- document.body.classList.add("spell-one-line-head");
168
- const crumbs = main.querySelector(":scope > ui-breadcrumbs.spell-crumbs");
169
- if (!crumbs || h1.querySelector(":scope > .spell-head-crumbs")) return;
170
- const trail = crumbs.cloneNode(true);
171
- trail.classList.add("spell-head-crumbs");
172
- trail.dataset.spellAdded = "";
173
- trail.removeAttribute("id");
174
- const page = trail.querySelector(":scope > ui-breadcrumb[selected]");
391
+ const h1 = main.querySelector(PAGE_TITLE)
392
+ if (!h1) return
393
+ document.body.classList.add("spell-one-line-head")
394
+ const crumbs = main.querySelector(":scope > ui-breadcrumbs.spell-crumbs")
395
+ if (!crumbs || h1.querySelector(":scope > .spell-head-crumbs")) return
396
+ const trail = crumbs.cloneNode(true)
397
+ trail.classList.add("spell-head-crumbs")
398
+ trail.dataset.spellAdded = ""
399
+ trail.removeAttribute("id")
400
+ const page = trail.querySelector(":scope > ui-breadcrumb[selected]")
175
401
  if (page) {
176
- page.textContent = "";
402
+ page.textContent = ""
403
+ // the space before it too: the divider sits as the old one did, `spell-doc.css` spacing it
177
404
  if (page.previousSibling?.nodeType === Node.TEXT_NODE && !page.previousSibling.textContent.trim())
178
- page.previousSibling.remove();
405
+ page.previousSibling.remove()
179
406
  }
180
- h1.prepend(trail);
407
+ h1.prepend(trail)
181
408
  }
182
- __name(oneLineHead, "oneLineHead");
409
+
410
+ /**
411
+ * The READING TIME chip, right after the page's title (epic `epic-engine` P14, Q5):
412
+ * `SOLID 2 · 48 min read`, a quiet `<ui-label>` (`spell-doc.css`, "The reading time chip").
413
+ * - its tooltip: the exact count, "8,749 words, 2,281 of them code" (`readingTime()`, `ReadingTime.js`)
414
+ * - every page with the docs head: guides, the index pages, details and choice pages
415
+ * - NOT an epic or saga page: `<epic-page>` draws its own head, and its own chip, counting only what's SHOWN
416
+ * (`shownReadingTime()`; J91, Owen: "Count what's shown"): its items' bodies wait in part files until opened
417
+ * - recounted on every `spell-doc:updated`: an edit saved, a section's body loaded
418
+ */
183
419
  function wireReadingTime(main) {
184
- drawReadingTime(main);
185
- addEventListener("spell-doc:updated", () => drawReadingTime(main));
420
+ drawReadingTime(main)
421
+ addEventListener("spell-doc:updated", () => drawReadingTime(main))
186
422
  }
187
- __name(wireReadingTime, "wireReadingTime");
423
+
424
+ /**
425
+ * Draw the reading time chip at the end of the page's h1, or update the one there.
426
+ * - `data-spell-added`: a live update steps around it, and `readingTime()` skips it
427
+ */
188
428
  function drawReadingTime(main) {
189
- const h1 = main.querySelector(PAGE_TITLE);
190
- if (!h1) return;
191
- const { words, code, minutes } = readingTime(main);
192
- let chip = h1.querySelector(":scope > ui-label.spell-reading-time");
429
+ const h1 = main.querySelector(PAGE_TITLE)
430
+ if (!h1) return
431
+ const { words, code, minutes } = readingTime(main)
432
+ let chip = h1.querySelector(":scope > ui-label.spell-reading-time")
193
433
  if (!chip) {
194
- chip = el("ui-label", { class: "spell-reading-time", size: "tiny", appearance: "basic", "data-spell-added": true });
195
- h1.append(chip);
434
+ chip = el("ui-label", { class: "spell-reading-time", size: "tiny", appearance: "basic", "data-spell-added": true })
435
+ h1.append(chip)
196
436
  }
197
- const counted = code ? `${words.toLocaleString()} words, ${code.toLocaleString()} of them code` : `${words.toLocaleString()} words`;
198
- if (chip.textContent !== `${minutes} min read`) chip.textContent = `${minutes} min read`;
199
- if (chip.title !== counted) chip.title = counted;
437
+ const counted = code
438
+ ? `${words.toLocaleString()} words, ${code.toLocaleString()} of them code`
439
+ : `${words.toLocaleString()} words`
440
+ if (chip.textContent !== `${minutes} min read`) chip.textContent = `${minutes} min read`
441
+ if (chip.title !== counted) chip.title = counted
200
442
  }
201
- __name(drawReadingTime, "drawReadingTime");
443
+
444
+ /**
445
+ * The wide layout, every page's (`spell-doc.css`, "Layout"; epic `epic-engine` P2):
446
+ * every table sits in the reading column, as prose does,
447
+ * with an EXPAND button over its top right corner that runs it the page's full width.
448
+ * - Owen, 2026-10-13: "make tables fit in the column by default, but have an expand button ...
449
+ * Remember that setting per table"
450
+ * - The button is a bare icon in the table's ACTIONS ROW (`addBlockAction()`), right of its bullhorn.
451
+ * - `.spell-table-toggle`, a `<ui-button appearance="basic">` with no edge (`spell-doc.css`)
452
+ * - Owen, 2026-10-19: "The expand button should be to the right of the bullhorn rather than in its own line"
453
+ * - the row is a line of no height, so it takes no room; a click flips it back
454
+ * - Expanded, the row moves with the table: its buttons stay over the table's top right corner.
455
+ * - Expanded: CSS can't know how far in a table starts (a list's indent, an item's inset), so this measures it,
456
+ * moving the table out to the page's gutter with the page's width, less the gutter on both sides.
457
+ * Again whenever its parent changes size (a section or item opening, the window resizing).
458
+ * - Never past a box that CLIPS it (`roomFor()`): an ancestor between it and `main` that hides its overflow (an
459
+ * epic element's reply card, `div.reply`) would cut the widened table off on both sides (epic `epic-engine` r10:
460
+ * "the expand table button made the table unusable"). With less than `MIN_WIDE_GAIN` to gain on its width in the
461
+ * column, the button hides.
462
+ * - Inside a `<ui-table>`, the host is what moves.
463
+ * - Remembered in this browser, per page, by the table's key (`tableKey()`): `spell-table-wide:<path>`.
464
+ * - Tables a part's body or a live update adds later get theirs too (`eachTable()`).
465
+ */
202
466
  function wireTableWidths(main) {
203
- if (!document.body.classList.contains("spell-doc-page")) return;
204
- const storeKey = `spell-table-wide:${location.pathname}`;
205
- const toggles = /* @__PURE__ */ new Map();
206
- const narrow = /* @__PURE__ */ new WeakMap();
467
+ // a page in the layout (`spell-doc.css`'s `body.spell-doc-page`), not one that only loads the bundle
468
+ if (!document.body.classList.contains("spell-doc-page")) return
469
+ const storeKey = `spell-table-wide:${location.pathname}`
470
+ const toggles = new Map()
471
+ const narrow = new WeakMap()
207
472
  const sizes = new ResizeObserver((entries) => {
208
- for (const entry of entries) for (const box of tableBoxes(entry.target)) place(box);
209
- });
210
- const isWide = /* @__PURE__ */ __name((box) => !!readJSON(storeKey)[tableKey(box, main)], "isWide");
211
- const place = /* @__PURE__ */ __name((box) => {
212
- const toggle = toggles.get(box);
213
- const parent = box.parentElement;
214
- if (!toggle || !parent || !box.isConnected) return;
215
- const row = toggle.closest(BLOCK_ROW);
216
- if (!box.style.width && box.getClientRects().length) narrow.set(box, box.getBoundingClientRect().width);
217
- toggle.hidden = roomWidth(box, main) <= (narrow.get(box) ?? 0) + MIN_WIDE_GAIN;
218
- const wide = isWide(box) && !toggle.hidden;
219
- toggle.toggleAttribute("selected", wide);
220
- toggle.title = wide ? "Back into the column" : "Expand to the page's width";
221
- toggle.setAttribute("aria-label", toggle.title);
222
- toggle.setAttribute("icon", wide ? "arrows left right to line" : "arrows left right");
223
- titleInside(toggle);
473
+ for (const entry of entries) for (const box of tableBoxes(entry.target)) place(box)
474
+ })
475
+ const isWide = (box) => !!readJSON(storeKey)[tableKey(box, main)]
476
+ const place = (box) => {
477
+ const toggle = toggles.get(box)
478
+ const parent = box.parentElement
479
+ if (!toggle || !parent || !box.isConnected) return
480
+ const row = toggle.closest(BLOCK_ROW)
481
+ // its width in the column, measured while not widened:
482
+ // the column is often the table's own `max-width`, not its parent's
483
+ if (!box.style.width && box.getClientRects().length) narrow.set(box, box.getBoundingClientRect().width)
484
+ toggle.hidden = roomWidth(box, main) <= (narrow.get(box) ?? 0) + MIN_WIDE_GAIN
485
+ const wide = isWide(box) && !toggle.hidden
486
+ toggle.toggleAttribute("selected", wide)
487
+ toggle.title = wide ? "Back into the column" : "Expand to the page's width"
488
+ toggle.setAttribute("aria-label", toggle.title)
489
+ toggle.setAttribute("icon", wide ? "arrows left right to line" : "arrows left right")
490
+ titleInside(toggle)
224
491
  if (!wide) {
225
- for (const each of [box, row]) each.style.removeProperty("margin-inline-start");
226
- for (const each of [box, row]) each.style.removeProperty("width");
227
- box.style.removeProperty("max-width");
228
- return alignBlockActions(row);
492
+ for (const each of [box, row]) each.style.removeProperty("margin-inline-start")
493
+ for (const each of [box, row]) each.style.removeProperty("width")
494
+ box.style.removeProperty("max-width")
495
+ return alignBlockActions(row)
229
496
  }
230
- if (!parent.getClientRects().length) return;
231
- const room = roomFor(box, main);
232
- const style = getComputedStyle(parent);
233
- const contentLeft = parent.getBoundingClientRect().left + parseFloat(style.borderLeftWidth) + parseFloat(style.paddingLeft);
234
- const start2 = `${room.left - contentLeft}px`;
235
- box.style.maxWidth = "none";
236
- box.style.width = `${room.right - room.left}px`;
237
- box.style.marginInlineStart = start2;
238
- row.style.width = box.style.width;
239
- row.style.marginInlineStart = start2;
240
- alignBlockActions(row);
241
- }, "place");
242
- const flip = /* @__PURE__ */ __name((box) => {
243
- const saved = readJSON(storeKey);
244
- const key = tableKey(box, main);
245
- if (saved[key]) delete saved[key];
246
- else saved[key] = true;
247
- writeJSON(storeKey, saved);
248
- place(box);
249
- }, "flip");
250
- const toggleFor = /* @__PURE__ */ __name((box) => {
251
- const toggle = document.createElement("ui-button");
252
- toggle.className = "spell-table-toggle";
253
- toggle.setAttribute("appearance", "basic");
254
- toggle.setAttribute("size", "mini");
255
- toggle.addEventListener("click", () => flip(box));
256
- return toggle;
257
- }, "toggleFor");
497
+ if (!parent.getClientRects().length) return
498
+ const room = roomFor(box, main)
499
+ const style = getComputedStyle(parent)
500
+ const contentLeft =
501
+ parent.getBoundingClientRect().left + parseFloat(style.borderLeftWidth) + parseFloat(style.paddingLeft)
502
+ const start = `${room.left - contentLeft}px`
503
+ box.style.maxWidth = "none"
504
+ box.style.width = `${room.right - room.left}px`
505
+ box.style.marginInlineStart = start
506
+ row.style.width = box.style.width
507
+ row.style.marginInlineStart = start
508
+ alignBlockActions(row)
509
+ }
510
+ const flip = (box) => {
511
+ const saved = readJSON(storeKey)
512
+ const key = tableKey(box, main)
513
+ if (saved[key]) delete saved[key]
514
+ else saved[key] = true
515
+ writeJSON(storeKey, saved)
516
+ place(box)
517
+ }
518
+ const toggleFor = (box) => {
519
+ const toggle = document.createElement("ui-button")
520
+ toggle.className = "spell-table-toggle"
521
+ toggle.setAttribute("appearance", "basic")
522
+ toggle.setAttribute("size", "mini")
523
+ toggle.addEventListener("click", () => flip(box))
524
+ return toggle
525
+ }
258
526
  const redrawSoon = eachTable(main, {
259
527
  added(box) {
260
- if (!box.parentElement) return false;
261
- const toggle = toggleFor(box);
262
- addBlockAction(box, toggle, "expand");
263
- toggles.set(box, toggle);
264
- sizes.observe(box.parentElement);
265
- place(box);
528
+ if (!box.parentElement) return false
529
+ const toggle = toggleFor(box)
530
+ addBlockAction(box, toggle, "expand")
531
+ toggles.set(box, toggle)
532
+ sizes.observe(box.parentElement)
533
+ place(box)
266
534
  },
267
535
  // a table a live update replaced, or moved away from its actions row: its button goes with it
268
- keeps: /* @__PURE__ */ __name((box) => toggles.get(box)?.closest(BLOCK_ROW)?.nextElementSibling === box, "keeps"),
536
+ keeps: (box) => toggles.get(box)?.closest(BLOCK_ROW)?.nextElementSibling === box,
269
537
  gone(box) {
270
- const toggle = toggles.get(box);
271
- const row = toggle?.closest(BLOCK_ROW);
272
- for (const name of ["width", "margin-inline-start"]) row?.style.removeProperty(name);
273
- if (toggle) dropBlockAction(toggle);
274
- toggles.delete(box);
538
+ const toggle = toggles.get(box)
539
+ const row = toggle?.closest(BLOCK_ROW)
540
+ for (const name of ["width", "margin-inline-start"]) row?.style.removeProperty(name)
541
+ if (toggle) dropBlockAction(toggle)
542
+ toggles.delete(box)
275
543
  },
276
- redraw: /* @__PURE__ */ __name(() => toggles.forEach((_toggle, box) => place(box)), "redraw")
277
- });
278
- addEventListener("resize", () => redrawSoon());
544
+ redraw: () => toggles.forEach((_toggle, box) => place(box))
545
+ })
546
+ addEventListener("resize", () => redrawSoon())
279
547
  }
280
- __name(wireTableWidths, "wireTableWidths");
548
+
549
+ /**
550
+ * A TWO-COLUMN table's first column WRAPS once it would take more than 40% of the table, so the second keeps a
551
+ * readable measure (epic `epic-engine` I145; Owen, 2026-10-26: "table layout sucks").
552
+ * - its first column never wraps otherwise (`spell-doc.css`, "A TWO-COLUMN table")
553
+ * - at the side bar's width, a long first column held whole squeezed the second to a word per line
554
+ * - CSS can't say "no wider than its words, nor than 40%" for a table's cell, so this measures:
555
+ * - each column's width with nothing wrapped (`data-spell-measuring`, for that moment only), and the room the table
556
+ * has (its box's width, wide or not)
557
+ * - the first column whole still leaves the second a readable measure (its words whole, or 24em): nothing to do
558
+ * - else, a first column wider than 40% of the room wraps (`data-spell-wrap-first`), at the wider of:
559
+ * - 40% of the room
560
+ * - the room less that readable measure (so the first wraps no more than it must)
561
+ * - but never so wide that the second gets less than `TWO_COLUMN_MIN_SECOND` (12em of its type)
562
+ * - the width: `--spell-first-column`, on the table
563
+ * - and only when that takes 2em or more off it (`TWO_COLUMN_LEAST_GAIN`): never a word wrapped for a few px
564
+ * - too narrow even then (a phone): the table scrolls sideways inside its own box, as every table does
565
+ * - again whenever its box changes size (a section or item opening, the side bar or window resizing, the expand
566
+ * button), a frame at a time; tables a part's body or a live update adds later get theirs too (`eachTable()`)
567
+ */
281
568
  function wireTwoColumnTables(main) {
282
- const sizes = new ResizeObserver((entries) => entries.forEach((entry) => redrawSoon(entry.target)));
569
+ const sizes = new ResizeObserver((entries) => entries.forEach((entry) => redrawSoon(entry.target)))
283
570
  const redrawSoon = eachTable(main, {
284
571
  // its first notice comes at once: the first fit
285
- added: /* @__PURE__ */ __name((box) => sizes.observe(box), "added"),
286
- redraw: /* @__PURE__ */ __name((boxes) => boxes.forEach((box) => fitTwoColumns(box)), "redraw")
287
- });
288
- }
289
- __name(wireTwoColumnTables, "wireTwoColumnTables");
290
- var TWO_COLUMN_FIRST_SHARE = 0.4;
291
- var TWO_COLUMN_MIN_SECOND = 12;
292
- var TWO_COLUMN_LEAST_GAIN = 2;
572
+ added: (box) => sizes.observe(box),
573
+ redraw: (boxes) => boxes.forEach((box) => fitTwoColumns(box))
574
+ })
575
+ }
576
+
577
+ /** How much of a two-column table's room its first column may take before it wraps (`wireTwoColumnTables()`). */
578
+ const TWO_COLUMN_FIRST_SHARE = 0.4
579
+
580
+ /** The least a two-column table's second column keeps before the table scrolls, in ems of its own type. */
581
+ const TWO_COLUMN_MIN_SECOND = 12
582
+
583
+ /** The least a two-column table's first column must give up to wrap at all, in ems of the body's type. */
584
+ const TWO_COLUMN_LEAST_GAIN = 2
585
+
586
+ /**
587
+ * Fit one table's box (`tableBoxes()`) as `wireTwoColumnTables()` says: wrap its first column, or not.
588
+ * - SIDE EFFECT: `data-spell-wrap-first` and `--spell-first-column` on its `<table>`, set or removed
589
+ * - a table that isn't two columns, or isn't shown, is left alone
590
+ */
293
591
  function fitTwoColumns(box) {
294
- const table = tableOf(box);
295
- if (!table?.isConnected || !table.getClientRects().length) return;
296
- const rows = [...table.rows];
297
- const pair = rows.find((row) => row.cells.length === 2 && row.cells[0].colSpan === 1);
298
- if (!pair || rows.some((row) => row.cells.length > 2)) return;
299
- table.setAttribute("data-spell-measuring", "");
300
- const room = table.clientWidth;
301
- const [first, second] = [...pair.cells].map((cell) => cell.getBoundingClientRect().width);
302
- const style = getComputedStyle(rows.find((row) => row.cells[1]?.localName === "td")?.cells[1] ?? pair.cells[1]);
303
- table.removeAttribute("data-spell-measuring");
304
- const minSecond = parseFloat(style.fontSize) * TWO_COLUMN_MIN_SECOND + parseFloat(style.paddingLeft) + parseFloat(style.paddingRight) + parseFloat(style.borderLeftWidth) + parseFloat(style.borderRightWidth);
305
- const readable = Math.min(second, minSecond * 2);
306
- const width = Math.max(0, Math.min(Math.max(room * TWO_COLUMN_FIRST_SHARE, room - readable), room - minSecond));
307
- const wraps = first > room * TWO_COLUMN_FIRST_SHARE && room - first < readable && first + second > room + 1 && first - width >= parseFloat(style.fontSize) * TWO_COLUMN_LEAST_GAIN;
308
- table.toggleAttribute("data-spell-wrap-first", wraps);
309
- setStyle(table, "--spell-first-column", wraps ? `${Math.floor(width)}px` : "");
310
- }
311
- __name(fitTwoColumns, "fitTwoColumns");
592
+ const table = tableOf(box)
593
+ if (!table?.isConnected || !table.getClientRects().length) return
594
+ const rows = [...table.rows]
595
+ const pair = rows.find((row) => row.cells.length === 2 && row.cells[0].colSpan === 1)
596
+ if (!pair || rows.some((row) => row.cells.length > 2)) return
597
+ // with nothing wrapped: a `display: block` table is as wide as its room, its cells as wide as their words
598
+ table.setAttribute("data-spell-measuring", "")
599
+ const room = table.clientWidth
600
+ const [first, second] = [...pair.cells].map((cell) => cell.getBoundingClientRect().width)
601
+ // a body cell's type, not the header's small capitals
602
+ const style = getComputedStyle(rows.find((row) => row.cells[1]?.localName === "td")?.cells[1] ?? pair.cells[1])
603
+ table.removeAttribute("data-spell-measuring")
604
+ const minSecond =
605
+ parseFloat(style.fontSize) * TWO_COLUMN_MIN_SECOND +
606
+ parseFloat(style.paddingLeft) +
607
+ parseFloat(style.paddingRight) +
608
+ parseFloat(style.borderLeftWidth) +
609
+ parseFloat(style.borderRightWidth)
610
+ // what the second column needs to read well: its words whole, or twice its least, if less
611
+ const readable = Math.min(second, minSecond * 2)
612
+ const width = Math.max(0, Math.min(Math.max(room * TWO_COLUMN_FIRST_SHARE, room - readable), room - minSecond))
613
+ // and only for a real gain: not to take a word or two off it
614
+ const wraps =
615
+ first > room * TWO_COLUMN_FIRST_SHARE &&
616
+ room - first < readable &&
617
+ first + second > room + 1 &&
618
+ first - width >= parseFloat(style.fontSize) * TWO_COLUMN_LEAST_GAIN
619
+ table.toggleAttribute("data-spell-wrap-first", wraps)
620
+ setStyle(table, "--spell-first-column", wraps ? `${Math.floor(width)}px` : "")
621
+ }
622
+
623
+ /**
624
+ * A table's HEADER ROW sticks (epic `epic-engine` r4; Owen, 2026-10-19: "make the table headers sticky"):
625
+ * while its rows scroll past, it stays just under the stuck titles, the page header's and the sections',
626
+ * until the table ends.
627
+ * - its header: its `<thead>`, else a first row of `<th>`s alone
628
+ * - a PIN, not the row itself: `position: sticky` on a `<thead>` holds only inside its nearest scroll box.
629
+ * - A table wider than its column scrolls sideways in its own box (every `<ui-table>`, a bare table at phone width),
630
+ * which scrolls nothing up or down.
631
+ * - So a COPY of the header (`.spell-table-pin`, `data-spell-added`) sticks instead.
632
+ * - the copy:
633
+ * - a line of no height just before the table (and its actions row), sticking at the line below the titles:
634
+ * the browser holds it there while the page scrolls, as it holds the titles
635
+ * - shown only while the table's own header is under that line,
636
+ * over the table's width as it shows (its box's, wide or not, scrolled sideways or not),
637
+ * its columns as wide as the table's, moved sideways with them
638
+ * - as the table ends, it goes up with the table's last row, cut off at the line: never over a title
639
+ * - the copy draws as the table does: the same classes in the same place (a `<ui-table>` copy for a `<ui-table>`);
640
+ * no pointer, no ids, hidden from readers
641
+ * - the line, below the titles stuck over the table (`tableLine()`)
642
+ * - read only for the tables on screen (an IntersectionObserver), a frame at a time,
643
+ * on any scroll (the page's, or a table's sideways) or resize
644
+ * - tables a part's body or a live update adds later get theirs too (`eachTable()`)
645
+ */
312
646
  function wireTableHeads(main) {
313
- const pins = /* @__PURE__ */ new Map();
314
- const onScreen = /* @__PURE__ */ new Set();
315
- let unpinnable = /* @__PURE__ */ new WeakSet();
647
+ const pins = new Map()
648
+ const onScreen = new Set()
649
+ // tables whose copy can't stick (a scroll box between them and the page): left alone until the window changes
650
+ let unpinnable = new WeakSet()
316
651
  const screen = new IntersectionObserver((entries) => {
317
652
  for (const entry of entries) {
318
- if (entry.isIntersecting) onScreen.add(entry.target);
319
- else onScreen.delete(entry.target);
653
+ if (entry.isIntersecting) onScreen.add(entry.target)
654
+ else onScreen.delete(entry.target)
320
655
  }
321
- redrawSoon();
322
- });
656
+ redrawSoon()
657
+ })
323
658
  const redrawSoon = eachTable(main, {
324
659
  // a table with no header row (yet): looked at again as the page changes
325
660
  added(box) {
326
- if (!headRows(tableOf(box)).length) return false;
327
- screen.observe(box);
661
+ if (!headRows(tableOf(box)).length) return false
662
+ screen.observe(box)
328
663
  },
329
- redraw: /* @__PURE__ */ __name(() => update(), "redraw")
330
- });
331
- const update = /* @__PURE__ */ __name(() => {
664
+ redraw: () => update()
665
+ })
666
+ const update = () => {
332
667
  for (const [box, pin] of pins) {
333
- if (box.isConnected) continue;
334
- pin.remove();
335
- pins.delete(box);
336
- onScreen.delete(box);
668
+ if (box.isConnected) continue
669
+ pin.remove()
670
+ pins.delete(box)
671
+ onScreen.delete(box)
337
672
  }
338
- for (const [box, pin] of pins) if (!onScreen.has(box)) pin.hidden = true;
339
- for (const box of onScreen) if (box.isConnected && !unpinnable.has(box)) place(box);
340
- }, "update");
341
- const place = /* @__PURE__ */ __name((box) => {
342
- const table = tableOf(box);
343
- const rows = headRows(table);
344
- if (!rows.length) return;
345
- const head = rows[0].getBoundingClientRect();
346
- const height = rows.at(-1).getBoundingClientRect().bottom - head.top;
347
- const line = tableLine(box);
348
- const end = table.getBoundingClientRect().bottom;
349
- let pin = pins.get(box);
673
+ for (const [box, pin] of pins) if (!onScreen.has(box)) pin.hidden = true
674
+ for (const box of onScreen) if (box.isConnected && !unpinnable.has(box)) place(box)
675
+ }
676
+ const place = (box) => {
677
+ const table = tableOf(box)
678
+ const rows = headRows(table)
679
+ if (!rows.length) return
680
+ const head = rows[0].getBoundingClientRect()
681
+ const height = rows.at(-1).getBoundingClientRect().bottom - head.top
682
+ const line = tableLine(box)
683
+ const end = table.getBoundingClientRect().bottom
684
+ let pin = pins.get(box)
350
685
  if (!(head.top < line - 0.5 && end > line + 1)) {
351
- if (pin) pin.hidden = true;
352
- return;
686
+ if (pin) pin.hidden = true
687
+ return
353
688
  }
354
689
  if (!pin) {
355
- pin = el("div", { class: "spell-table-pin", "data-spell-added": true, "aria-hidden": "true", inert: true });
356
- pin.hidden = true;
357
- pins.set(box, pin);
358
- const row = box.previousElementSibling;
359
- (row?.matches(BLOCK_ROW) ? row : box).before(pin);
690
+ pin = el("div", { class: "spell-table-pin", "data-spell-added": true, "aria-hidden": "true", inert: true })
691
+ pin.hidden = true
692
+ pins.set(box, pin)
693
+ const row = box.previousElementSibling
694
+ ;(row?.matches(BLOCK_ROW) ? row : box).before(pin)
360
695
  }
361
- if (pin.hidden) copyHead(pin, box, table, rows);
362
- pin.hidden = false;
363
- setStyle(pin, "top", `${line}px`);
364
- const view = pin.firstElementChild;
365
- const area = box.getBoundingClientRect();
366
- const at = pin.getBoundingClientRect();
696
+ // shown again: the header as it is now (a live update may have changed it)
697
+ if (pin.hidden) copyHead(pin, box, table, rows)
698
+ pin.hidden = false
699
+ setStyle(pin, "top", `${line}px`)
700
+ const view = pin.firstElementChild
701
+ const area = box.getBoundingClientRect()
702
+ const at = pin.getBoundingClientRect()
703
+ // not held at the line: nothing, rather than a copy out of place
367
704
  if (Math.abs(at.top - line) > 1) {
368
- pin.hidden = true;
369
- unpinnable.add(box);
370
- return;
705
+ pin.hidden = true
706
+ unpinnable.add(box)
707
+ return
371
708
  }
372
- setStyle(view, "left", `${area.left - at.left}px`);
373
- setStyle(view, "width", `${area.width}px`);
374
- const copies = [...view.querySelectorAll("tr")].flatMap((each) => [...each.cells]);
375
- const widths = rows.flatMap((each) => [...each.cells]).map((cell) => cell.getBoundingClientRect().width);
376
- widths.forEach((width, n) => copies[n] && setStyle(copies[n], "width", `${width}px`));
377
- const copy = view.querySelector("table");
378
- const first = view.querySelector("tr");
379
- const edges = copy.getBoundingClientRect().width - first.getBoundingClientRect().width;
380
- setStyle(copy, "width", `${head.width + edges}px`);
381
- const shift = parseFloat(copy.style.translate) || 0;
382
- setStyle(copy, "translate", `${shift + head.left - first.getBoundingClientRect().left}px`);
383
- const up = Math.min(0, end - (line + height));
384
- setStyle(view, "translate", up ? `0 ${up}px` : "");
385
- setStyle(view, "clip-path", up ? `inset(${-up}px 0 0 0)` : "");
386
- }, "place");
387
- document.addEventListener("scroll", () => redrawSoon(), { capture: true, passive: true });
709
+ setStyle(view, "left", `${area.left - at.left}px`)
710
+ setStyle(view, "width", `${area.width}px`)
711
+ // each column as wide as the table's, and the copy moved to where the table's header is (sideways too)
712
+ const copies = [...view.querySelectorAll("tr")].flatMap((each) => [...each.cells])
713
+ const widths = rows.flatMap((each) => [...each.cells]).map((cell) => cell.getBoundingClientRect().width)
714
+ widths.forEach((width, n) => copies[n] && setStyle(copies[n], "width", `${width}px`))
715
+ const copy = view.querySelector("table")
716
+ const first = view.querySelector("tr")
717
+ // the copy as wide as the row, its own edges added (`table-layout: fixed` keeps the columns as set)
718
+ const edges = copy.getBoundingClientRect().width - first.getBoundingClientRect().width
719
+ setStyle(copy, "width", `${head.width + edges}px`)
720
+ const shift = parseFloat(copy.style.translate) || 0
721
+ setStyle(copy, "translate", `${shift + head.left - first.getBoundingClientRect().left}px`)
722
+ // leaving with the table's last row: up, the part above the line cut off
723
+ const up = Math.min(0, end - (line + height))
724
+ setStyle(view, "translate", up ? `0 ${up}px` : "")
725
+ setStyle(view, "clip-path", up ? `inset(${-up}px 0 0 0)` : "")
726
+ }
727
+ // capture: a table's own sideways scroll too, which doesn't bubble
728
+ document.addEventListener("scroll", () => redrawSoon(), { capture: true, passive: true })
388
729
  addEventListener("resize", () => {
389
- unpinnable = /* @__PURE__ */ new WeakSet();
390
- redrawSoon();
391
- });
730
+ unpinnable = new WeakSet()
731
+ redrawSoon()
732
+ })
392
733
  }
393
- __name(wireTableHeads, "wireTableHeads");
734
+
735
+ /** Set `element`'s inline style `name` to `value` ("" removes it), unless it's that already. */
394
736
  function setStyle(element, name, value) {
395
- if (element.style.getPropertyValue(name) === value) return;
396
- if (value) element.style.setProperty(name, value);
397
- else element.style.removeProperty(name);
737
+ if (element.style.getPropertyValue(name) === value) return
738
+ if (value) element.style.setProperty(name, value)
739
+ else element.style.removeProperty(name)
398
740
  }
399
- __name(setStyle, "setStyle");
741
+
742
+ /** The `<table>` of a table's box (`tableBoxes()`): the box itself, or the `<ui-table>`'s own. */
400
743
  function tableOf(box) {
401
- return box.localName === "table" ? box : box.querySelector(":scope > table");
744
+ return box.localName === "table" ? box : box.querySelector(":scope > table")
402
745
  }
403
- __name(tableOf, "tableOf");
746
+
747
+ /** A table's header rows (`wireTableHeads()`): its `<thead>`'s, else its first row when it holds `<th>`s alone. */
404
748
  function headRows(table) {
405
- if (!table) return [];
406
- if (table.tHead?.rows.length) return [...table.tHead.rows];
407
- const first = table.rows[0];
408
- return first?.cells.length && [...first.cells].every((cell) => cell.localName === "th") ? [first] : [];
749
+ if (!table) return []
750
+ if (table.tHead?.rows.length) return [...table.tHead.rows]
751
+ const first = table.rows[0]
752
+ return first?.cells.length && [...first.cells].every((cell) => cell.localName === "th") ? [first] : []
409
753
  }
410
- __name(headRows, "headRows");
754
+
755
+ /**
756
+ * Draw a copy of `table`'s header `rows` into `pin` (`wireTableHeads()`): the table's own tag and classes, in a
757
+ * shallow copy of its `<ui-table>`, so the page's rules draw it as they draw the table; never its ids, the table's
758
+ * inline styles (the expand button's widths) or its body.
759
+ */
411
760
  function copyHead(pin, box, table, rows) {
412
- const copy = table.cloneNode(false);
413
- const head = el("thead", {}, ...rows.map((row) => row.cloneNode(true)));
414
- copy.append(head);
415
- const host = box === table ? void 0 : box.cloneNode(false);
416
- host?.append(copy);
761
+ const copy = table.cloneNode(false)
762
+ const head = el("thead", {}, ...rows.map((row) => row.cloneNode(true)))
763
+ copy.append(head)
764
+ const host = box === table ? undefined : box.cloneNode(false)
765
+ host?.append(copy)
417
766
  for (const each of [copy, host]) {
418
- each?.removeAttribute("id");
419
- each?.removeAttribute("style");
767
+ each?.removeAttribute("id")
768
+ each?.removeAttribute("style")
420
769
  }
421
- for (const each of head.querySelectorAll("[id]")) each.removeAttribute("id");
422
- pin.replaceChildren(el("div", { class: "spell-table-pin-view" }, host ?? copy));
770
+ for (const each of head.querySelectorAll("[id]")) each.removeAttribute("id")
771
+ pin.replaceChildren(el("div", { class: "spell-table-pin-view" }, host ?? copy))
423
772
  }
424
- __name(copyHead, "copyHead");
773
+
774
+ /**
775
+ * Where a table's header sticks (`wireTableHeads()`), px from the window's top: the bottom of what is stuck over it.
776
+ * - an epic page's: its `--epic-stack` (the page header and bar, the stuck block titles), and the line of the item
777
+ * it's in, which sticks there too
778
+ * - a `<ui-section>` page's: the site header and the TOP-LEVEL section's stack (`--spell-stack`, the page header and
779
+ * its title): a nested section's stuck title joins that one's row (`wireStuckTrail()`), its own room left empty
780
+ * - a headings page's (the saga pages): the page header, then the h2's and h3's above it
781
+ */
425
782
  function tableLine(box) {
426
- const style = getComputedStyle(box);
427
- const px = /* @__PURE__ */ __name((name) => parseFloat(style.getPropertyValue(name)) || 0, "px");
783
+ const style = getComputedStyle(box)
784
+ const px = (name) => parseFloat(style.getPropertyValue(name)) || 0
428
785
  if (box.closest("epic-page")) {
429
- const line = box.parentElement?.closest("epic-item")?.shadowRoot?.querySelector('[part~="line"]');
430
- return (px("--epic-stack") || siteHeaderHeight()) + (line?.getBoundingClientRect().height ?? 0);
786
+ const line = box.parentElement?.closest("epic-item")?.shadowRoot?.querySelector('[part~="line"]')
787
+ return (px("--epic-stack") || siteHeaderHeight()) + (line?.getBoundingClientRect().height ?? 0)
431
788
  }
432
- let section = box.closest("ui-section");
433
- while (section?.parentElement?.closest("ui-section")) section = section.parentElement.closest("ui-section");
434
- if (section) return siteHeaderHeight() + (parseFloat(section.style.getPropertyValue("--spell-stack")) || 0);
435
- return siteHeaderHeight() + px("--spell-top") + px("--spell-h2-h") + px("--spell-h3-h");
789
+ let section = box.closest("ui-section")
790
+ while (section?.parentElement?.closest("ui-section")) section = section.parentElement.closest("ui-section")
791
+ if (section) return siteHeaderHeight() + (parseFloat(section.style.getPropertyValue("--spell-stack")) || 0)
792
+ return siteHeaderHeight() + px("--spell-top") + px("--spell-h2-h") + px("--spell-h3-h")
436
793
  }
437
- __name(tableLine, "tableLine");
794
+
795
+ /**
796
+ * Stuck titles on ONE row (Owen, 2026-10-13: "This could collapse to one row when stickified").
797
+ * - while a nested section's title is stuck under its parent's,
798
+ * the top-level stuck title reads `2. Files on disk › 2.1 The repo`
799
+ * - the nested stuck titles under it hide: their room shows the text scrolling under them
800
+ * - the trail is the top-level title's `::part(header)::after`, from `--spell-stuck-trail` on it, with
801
+ * `data-spell-trail`; each hidden one has `data-spell-merged` (`spell-doc.css`, "Stuck titles on one row")
802
+ * - worked out again on every scroll and resize, a frame at a time, and once more as it settles:
803
+ * `:state(stuck)` (`<ui-section sticky>`'s) sends no event
804
+ * - every page's `<ui-section>`s; an epic page draws its own sections, in its elements' shadow roots
805
+ */
438
806
  function wireStuckTrail(main) {
439
- const marked = /* @__PURE__ */ new Set();
440
- const isStuck = /* @__PURE__ */ __name((section) => section.matches("[sticky]") && section.matches(":state(stuck)"), "isStuck");
441
- const childrenOf = /* @__PURE__ */ __name((section) => [...section.querySelectorAll("ui-section")].filter((each) => each.parentElement.closest("ui-section") === section), "childrenOf");
442
- const titleOf2 = /* @__PURE__ */ __name((section) => (section.getAttribute("label") ?? section.querySelector(':scope > [slot="label"]')?.textContent ?? "").replace(/\s+/g, " ").trim(), "titleOf");
443
- const update = /* @__PURE__ */ __name(() => {
444
- const merged = /* @__PURE__ */ new Set();
445
- const trails = /* @__PURE__ */ new Map();
807
+ const marked = new Set()
808
+ const isStuck = (section) => section.matches("[sticky]") && section.matches(":state(stuck)")
809
+ // the sections directly under `section` (none between), as nesting goes
810
+ const childrenOf = (section) =>
811
+ [...section.querySelectorAll("ui-section")].filter((each) => each.parentElement.closest("ui-section") === section)
812
+ const titleOf = (section) =>
813
+ (section.getAttribute("label") ?? section.querySelector(':scope > [slot="label"]')?.textContent ?? "")
814
+ .replace(/\s+/g, " ")
815
+ .trim()
816
+ const update = () => {
817
+ const merged = new Set()
818
+ const trails = new Map()
446
819
  for (const top of main.querySelectorAll("ui-section")) {
447
- if (top.parentElement.closest("ui-section") || !isStuck(top)) continue;
448
- const trail = [];
449
- for (let at = top; ; ) {
450
- const child = childrenOf(at).find(isStuck);
451
- if (!child) break;
452
- trail.push(titleOf2(child));
453
- merged.add(child);
454
- at = child;
820
+ if (top.parentElement.closest("ui-section") || !isStuck(top)) continue
821
+ const trail = []
822
+ for (let at = top; ;) {
823
+ const child = childrenOf(at).find(isStuck)
824
+ if (!child) break
825
+ trail.push(titleOf(child))
826
+ merged.add(child)
827
+ at = child
455
828
  }
456
- if (trail.length) trails.set(top, JSON.stringify(` › ${trail.join(" › ")}`));
829
+ if (trail.length) trails.set(top, JSON.stringify(` › ${trail.join(" › ")}`))
457
830
  }
458
831
  for (const section of marked) {
459
- if (!merged.has(section)) section.removeAttribute("data-spell-merged");
832
+ if (!merged.has(section)) section.removeAttribute("data-spell-merged")
460
833
  if (!trails.has(section)) {
461
- section.removeAttribute("data-spell-trail");
462
- section.style.removeProperty("--spell-stuck-trail");
834
+ section.removeAttribute("data-spell-trail")
835
+ section.style.removeProperty("--spell-stuck-trail")
463
836
  }
464
837
  }
465
- marked.clear();
838
+ marked.clear()
466
839
  for (const section of merged) {
467
- if (!section.hasAttribute("data-spell-merged")) section.setAttribute("data-spell-merged", "");
468
- marked.add(section);
840
+ if (!section.hasAttribute("data-spell-merged")) section.setAttribute("data-spell-merged", "")
841
+ marked.add(section)
469
842
  }
470
843
  for (const [section, trail] of trails) {
471
844
  if (section.style.getPropertyValue("--spell-stuck-trail") !== trail)
472
- section.style.setProperty("--spell-stuck-trail", trail);
473
- if (!section.hasAttribute("data-spell-trail")) section.setAttribute("data-spell-trail", "");
474
- marked.add(section);
845
+ section.style.setProperty("--spell-stuck-trail", trail)
846
+ if (!section.hasAttribute("data-spell-trail")) section.setAttribute("data-spell-trail", "")
847
+ marked.add(section)
475
848
  }
476
- }, "update");
477
- let queued = false;
478
- const soon = /* @__PURE__ */ __name(() => {
479
- if (queued) return;
480
- queued = true;
849
+ }
850
+ let queued = false
851
+ const soon = () => {
852
+ if (queued) return
853
+ queued = true
481
854
  requestAnimationFrame(() => {
482
- queued = false;
483
- update();
484
- });
485
- }, "soon");
486
- let settle;
487
- const later = /* @__PURE__ */ __name(() => {
488
- soon();
489
- clearTimeout(settle);
490
- settle = setTimeout(soon, STUCK_SETTLE_MS);
491
- }, "later");
492
- addEventListener("scroll", later, { passive: true });
493
- addEventListener("resize", later);
494
- later();
495
- }
496
- __name(wireStuckTrail, "wireStuckTrail");
497
- var STUCK_SETTLE_MS = 120;
855
+ queued = false
856
+ update()
857
+ })
858
+ }
859
+ // `:state(stuck)` follows a moment after the scroll (`StickyWatch` hears it from an observer):
860
+ // so again once the scrolling settles, or the last frame would read the titles as they were
861
+ let settle
862
+ const later = () => {
863
+ soon()
864
+ clearTimeout(settle)
865
+ settle = setTimeout(soon, STUCK_SETTLE_MS)
866
+ }
867
+ addEventListener("scroll", later, { passive: true })
868
+ addEventListener("resize", later)
869
+ later()
870
+ }
871
+
872
+ /** How long after the last scroll the stuck titles are read again (`wireStuckTrail()`), ms. */
873
+ const STUCK_SETTLE_MS = 120
874
+
875
+ /**
876
+ * A table's key, for remembering its width: its id, else the nearest id above it and which table it is under that
877
+ * (`p14#table-1`, `memory#table-2`); `page#table-<n>` with no id above it.
878
+ */
498
879
  function tableKey(box, main) {
499
- if (box.id) return box.id;
500
- const holder = box.parentElement.closest("[id]");
501
- const root = holder && main.contains(holder) ? holder : main;
502
- return `${root === main ? "page" : root.id}#table-${tableBoxes(root).indexOf(box) + 1}`;
880
+ if (box.id) return box.id
881
+ const holder = box.parentElement.closest("[id]")
882
+ const root = holder && main.contains(holder) ? holder : main
883
+ return `${root === main ? "page" : root.id}#table-${tableBoxes(root).indexOf(box) + 1}`
503
884
  }
504
- __name(tableKey, "tableKey");
885
+
886
+ /**
887
+ * How far a widened table `box` may run, as window x's `{ left, right }`:
888
+ * `main`'s width less its gutter (`--spell-gutter`) on both sides,
889
+ * cut to every ancestor between them that clips its overflow (`overflow-x` not `visible`), at its inner edges.
890
+ * - up through slots and shadow roots:
891
+ * a table in an `<epic-*>` element's light DOM is laid out in its shadow root's boxes
892
+ */
505
893
  function roomFor(box, main) {
506
- const page = main.getBoundingClientRect();
507
- const gutter = parseFloat(getComputedStyle(main).getPropertyValue("--spell-gutter")) || 16;
508
- const room = { left: page.left + gutter, right: page.right - gutter };
509
- for (let el2 = layoutParent(box); el2 && el2 !== main; el2 = layoutParent(el2)) {
510
- if (getComputedStyle(el2).overflowX === "visible") continue;
511
- const left = el2.getBoundingClientRect().left + el2.clientLeft;
512
- room.left = Math.max(room.left, left);
513
- room.right = Math.min(room.right, left + el2.clientWidth);
514
- }
515
- return room;
516
- }
517
- __name(roomFor, "roomFor");
894
+ const page = main.getBoundingClientRect()
895
+ const gutter = parseFloat(getComputedStyle(main).getPropertyValue("--spell-gutter")) || 16
896
+ const room = { left: page.left + gutter, right: page.right - gutter }
897
+ for (let el = layoutParent(box); el && el !== main; el = layoutParent(el)) {
898
+ if (getComputedStyle(el).overflowX === "visible") continue
899
+ const left = el.getBoundingClientRect().left + el.clientLeft
900
+ room.left = Math.max(room.left, left)
901
+ room.right = Math.min(room.right, left + el.clientWidth)
902
+ }
903
+ return room
904
+ }
905
+
906
+ /** How wide `roomFor()` lets `box` run. */
518
907
  function roomWidth(box, main) {
519
- const room = roomFor(box, main);
520
- return room.right - room.left;
908
+ const room = roomFor(box, main)
909
+ return room.right - room.left
521
910
  }
522
- __name(roomWidth, "roomWidth");
523
- var MIN_WIDE_GAIN = 24;
524
- function layoutParent(el2) {
525
- return el2.assignedSlot ?? el2.parentElement ?? el2.getRootNode().host ?? null;
911
+
912
+ /** The least a widened table must gain on its column (px) for the expand button to show. */
913
+ const MIN_WIDE_GAIN = 24
914
+
915
+ /** The box `el` is laid out in: its slot when it's slotted, else its parent, else its shadow root's host. */
916
+ function layoutParent(el) {
917
+ return el.assignedSlot ?? el.parentElement ?? el.getRootNode().host ?? null
526
918
  }
527
- __name(layoutParent, "layoutParent");
919
+
920
+ /**
921
+ * The tables in `root`, each by its BOX: its `<ui-table>` host, else the bare table. Never a pinned header's copy
922
+ * (`wireTableHeads()`), which isn't the page's.
923
+ */
528
924
  function tableBoxes(root) {
529
- const tables = [...root.querySelectorAll("table")].filter((table) => !table.closest(".spell-table-pin"));
530
- return [...new Set(tables.map((table) => table.closest("ui-table") ?? table))];
531
- }
532
- __name(tableBoxes, "tableBoxes");
533
- function eachTable(main, { added, gone, keeps = /* @__PURE__ */ __name(() => true, "keeps"), redraw = /* @__PURE__ */ __name(() => {
534
- }, "redraw") }) {
535
- const taken = /* @__PURE__ */ new Set();
536
- let asked = /* @__PURE__ */ new Set();
537
- let frame = 0;
538
- look();
539
- new MutationObserver(() => requestAnimationFrame(look)).observe(main, { childList: true, subtree: true });
540
- return redrawSoon;
925
+ const tables = [...root.querySelectorAll("table")].filter((table) => !table.closest(".spell-table-pin"))
926
+ return [...new Set(tables.map((table) => table.closest("ui-table") ?? table))]
927
+ }
928
+
929
+ /**
930
+ * Watch every TABLE in `main` (each by its box, `tableBoxes()`): the ONE watch the table features run on
931
+ * (`wireTableWidths()`, `wireTwoColumnTables()`, `wireTableHeads()`; epic `coherence` P22).
932
+ * - `added(box)`: each box once, as it's first seen: now, and as a part's body or a live update adds tables
933
+ * - `false`: not taken yet, so it's handed over again at the next change (a table with no header row yet)
934
+ * - `gone(box)`: a box taken that's left the page, or that `keeps(box)` lets go: handed to `added()` again while
935
+ * it's there. Default: every box on the page is kept.
936
+ * - `redraw(boxes)`: once a frame at most, with the boxes asked for since; returns what asks for it,
937
+ * `redrawSoon(box?)`: a box, or none (a resize, a scroll: every box is the caller's to redraw)
938
+ * - SIDE EFFECT: watches `main`'s tree for the page's life
939
+ */
940
+ function eachTable(main, { added, gone, keeps = () => true, redraw = () => {} }) {
941
+ const taken = new Set()
942
+ let asked = new Set()
943
+ let frame = 0
944
+ look()
945
+ new MutationObserver(() => requestAnimationFrame(look)).observe(main, { childList: true, subtree: true })
946
+ return redrawSoon
947
+
948
+ /** What's gone first, then the boxes not seen yet. */
541
949
  function look() {
542
950
  for (const box of taken) {
543
- if (box.isConnected && keeps(box)) continue;
544
- taken.delete(box);
545
- gone?.(box);
951
+ if (box.isConnected && keeps(box)) continue
952
+ taken.delete(box)
953
+ gone?.(box)
546
954
  }
547
- for (const box of tableBoxes(main)) if (!taken.has(box) && added(box) !== false) taken.add(box);
955
+ for (const box of tableBoxes(main)) if (!taken.has(box) && added(box) !== false) taken.add(box)
548
956
  }
549
- __name(look, "look");
957
+
958
+ /** `redraw()` at the next frame, once however often it's asked, with every box asked for since. */
550
959
  function redrawSoon(box) {
551
- if (box) asked.add(box);
960
+ if (box) asked.add(box)
552
961
  frame ||= requestAnimationFrame(() => {
553
- frame = 0;
554
- const boxes = asked;
555
- asked = /* @__PURE__ */ new Set();
556
- redraw(boxes);
557
- });
962
+ frame = 0
963
+ const boxes = asked
964
+ asked = new Set()
965
+ redraw(boxes)
966
+ })
558
967
  }
559
- __name(redrawSoon, "redrawSoon");
560
968
  }
561
- __name(eachTable, "eachTable");
969
+
970
+ /**
971
+ * Land where the page should open, once its sections have drawn and folded:
972
+ * - a live reload's saved scroll position (`SPELL_SERVER.takeScroll()`): exactly there, held while the page settles
973
+ * (`holdScroll()`); its `#hash` was dropped (`start()`)
974
+ * - else the URL's `#hash`:
975
+ * - a section or heading WITHOUT unfolding the target itself: the address follows the section being read
976
+ * (`followScroll()`), so a reload (or VS Code restarting) lands on it, folded or not, as the reader left it
977
+ * - a plan item (`<epic-item>`) OPENS: the address never follows items, so an item's `#q16` is a link someone
978
+ * followed (`epic pages link --hash q16 --show`), and a folded item shows nothing of what it pointed at
979
+ * - else nowhere: the top
980
+ * - then the address starts following the scroll; after a `#hash`, only once the jump has landed:
981
+ * a target in a body not loaded yet (a split epic page's part) lands a moment later, and following before that saw
982
+ * the top of the page, and wrote the hash away (I3 of `windows-and-review`)
983
+ */
562
984
  function land({ hash, scroll }, jump, follow) {
563
- if (scroll !== void 0) {
564
- holdScroll(scroll);
565
- follow?.update();
985
+ if (scroll !== undefined) {
986
+ holdScroll(scroll)
987
+ follow?.update()
566
988
  } else if (hash) {
567
- const landed = jump(hash, { unfoldTarget: document.getElementById(hash)?.localName === "epic-item" });
568
- void landed.then(() => follow?.followAddress());
569
- return;
570
- } else follow?.update();
571
- follow?.followAddress();
989
+ // `HashLanding` lands once more as the page settles, unless the reader has moved meanwhile: the browser's own
990
+ // jump to the `#hash` can come AFTER ours and land the target under the stuck titles (an item has no box of its
991
+ // own: `display: contents`)
992
+ const landed = jump(hash, { unfoldTarget: document.getElementById(hash)?.localName === "epic-item" })
993
+ void landed.then(() => follow?.followAddress())
994
+ return
995
+ } else follow?.update()
996
+ follow?.followAddress()
572
997
  }
573
- __name(land, "land");
998
+
999
+ /**
1000
+ * Keep the page at `top` while it settles after a live reload:
1001
+ * every frame for `RESTORE_HOLD_MS`, until the reader does anything (`READER_INPUT`).
1002
+ * - why: the page grows as it settles (the folds put back draw, their parts load),
1003
+ * and the browser and the elements scroll it meanwhile
1004
+ * - one scroll, and one more after `SETTLE_MS` only when nothing else had moved it, landed short
1005
+ * (I23 of `epic-engine`: 1150 -> 671)
1006
+ * - the page may be too short for `top` at first: it gets there as it grows
1007
+ */
574
1008
  function holdScroll(top) {
575
- const reader = new AbortController();
1009
+ const reader = new AbortController()
576
1010
  for (const type of READER_INPUT)
577
- addEventListener(type, () => reader.abort(), { once: true, passive: true, signal: reader.signal });
578
- const until = performance.now() + RESTORE_HOLD_MS;
579
- const hold = /* @__PURE__ */ __name(() => {
580
- if (reader.signal.aborted) return;
581
- if (Math.abs(scrollY - top) >= 1) scrollTo({ top, behavior: "instant" });
582
- if (performance.now() < until) requestAnimationFrame(hold);
583
- else reader.abort();
584
- }, "hold");
585
- hold();
586
- }
587
- __name(holdScroll, "holdScroll");
1011
+ addEventListener(type, () => reader.abort(), { once: true, passive: true, signal: reader.signal })
1012
+ const until = performance.now() + RESTORE_HOLD_MS
1013
+ const hold = () => {
1014
+ if (reader.signal.aborted) return
1015
+ if (Math.abs(scrollY - top) >= 1) scrollTo({ top, behavior: "instant" })
1016
+ if (performance.now() < until) requestAnimationFrame(hold)
1017
+ else reader.abort()
1018
+ }
1019
+ hold()
1020
+ }
1021
+
1022
+ /**
1023
+ * Resolves once an epic page's elements are defined and have drawn (their hosts' `ready`), so their
1024
+ * `contentsEntry` can be read; after `EPIC_WAIT_MS` at most (a pack that won't load: the page goes on without).
1025
+ */
588
1026
  async function epicsDrawn(main) {
589
- const tags = ["epic-page", ...EPIC_FOLDS.split(", ")];
590
- const drawn = Promise.all(tags.map((tag) => customElements.whenDefined(tag))).then(
591
- () => Promise.all(Array.from(main.querySelectorAll(EPIC_FOLDS), (host) => host.ready))
592
- );
593
- await Promise.race([drawn, new Promise((done) => setTimeout(done, EPIC_WAIT_MS))]);
1027
+ const tags = ["epic-page", ...EPIC_FOLDS.split(", ")]
1028
+ const drawn = Promise.all(tags.map((tag) => customElements.whenDefined(tag))).then(() =>
1029
+ Promise.all(Array.from(main.querySelectorAll(EPIC_FOLDS), (host) => host.ready))
1030
+ )
1031
+ await Promise.race([drawn, new Promise((done) => setTimeout(done, EPIC_WAIT_MS))])
594
1032
  }
595
- __name(epicsDrawn, "epicsDrawn");
1033
+
1034
+ /**
1035
+ * An epic page (`epics/<name>/<name>.plan.html`; before 2026-10-04 `<name>.html`) names its tab `<name>`:
1036
+ * every link to it has `target="<name>"` (`doc-links.js`),
1037
+ * so they reuse this tab, as `epic open <name>` does.
1038
+ */
596
1039
  function nameTab() {
597
- const plan = /\/epics\/([^/]+)\/\1(?:\.plan)?\.html$/.exec(decodeURIComponent(location.pathname));
598
- if (plan) window.name = plan[1];
1040
+ const plan = /\/epics\/([^/]+)\/\1(?:\.plan)?\.html$/.exec(decodeURIComponent(location.pathname))
1041
+ if (plan) window.name = plan[1]
599
1042
  }
600
- __name(nameTab, "nameTab");
1043
+
1044
+ /** highlight.js colors every `pre code`; without it (offline) the code stays plain monospace. */
601
1045
  function highlight() {
602
1046
  try {
603
- globalThis.hljs?.highlightAll();
1047
+ globalThis.hljs?.highlightAll()
604
1048
  } catch {
1049
+ // plain monospace is fine
605
1050
  }
606
1051
  }
607
- __name(highlight, "highlight");
608
- var ADDED = ".spell-item-filter, .spell-hidden-note, [data-spell-added]";
609
- var EPIC_PAGE_STATE = ["open", "reviewing", "data-epic-filtered"];
610
- var KEPT_ATTRIBUTES = ["badge", "data-show", "data-ui-zoom", ...EPIC_PAGE_STATE];
611
- var MANAGERS = "ui-accordion, ui-tabs, ui-select, ui-dropdown";
612
- var EPIC_TAG = /^epic-/;
613
- var patcher = new PagePatch({
1052
+
1053
+ ////////////////
1054
+ // ## Live update
1055
+ ////////////////
1056
+
1057
+ /**
1058
+ * Elements the runtime adds INSIDE `main`, so not in the page's source: the patch steps around them.
1059
+ * - NOTE: anything else the runtime (or a page script) adds in `main` should carry `data-spell-added`;
1060
+ * an unknown extra of another tag than its source siblings doesn't shift their addresses either (`PagePatch`)
1061
+ */
1062
+ const ADDED = ".spell-item-filter, .spell-hidden-note, [data-spell-added]"
1063
+
1064
+ /**
1065
+ * The page state of an `<epic-*>` element (epic `epic-components`, P10): folded or open (items, sections, phases,
1066
+ * the Overview), the page being reviewed (`<epic-page reviewing>`), and an item its section's filter hides
1067
+ * (`data-epic-filtered`, epic `epic-engine` P45); never in the file, so a patch keeps them
1068
+ * (`KEPT_ATTRIBUTES`), and a replaced subtree carries them over (`carryEpicState()`).
1069
+ * - NOTE: their review controls and note boxes are in their shadow roots (P9): a patch never sees them
1070
+ */
1071
+ const EPIC_PAGE_STATE = ["open", "reviewing", "data-epic-filtered"]
1072
+
1073
+ /**
1074
+ * Attributes the reader's state lives in (folds, counts, the item filter, `EPIC_PAGE_STATE`):
1075
+ * a patch keeps them (`PagePatch`'s `keptAttributes`, beside the shared `open`).
1076
+ */
1077
+ const KEPT_ATTRIBUTES = ["badge", "data-show", "data-ui-zoom", ...EPIC_PAGE_STATE]
1078
+
1079
+ /**
1080
+ * Elements that manage their children (panels and tabs by index, options): a change inside replaces the whole
1081
+ * element, its open panels carried over (the kit's shared rules, `PagePatch.keepReaderState()`).
1082
+ */
1083
+ const MANAGERS = "ui-accordion, ui-tabs, ui-select, ui-dropdown"
1084
+
1085
+ /**
1086
+ * A tag of the `epics` pack's elements (`<epic-page>`, `<epic-item>` ...): NEVER replaced by a patch while its tag
1087
+ * stays: each keeps its fold, its loaded part and what's typed in it.
1088
+ * - patched in place like any element, attributes and children, text by text (`PagePatch`);
1089
+ * even a body file changing (`source`) doesn't replace one
1090
+ */
1091
+ const EPIC_TAG = /^epic-/
1092
+
1093
+ /**
1094
+ * The page patch, the kit's ONE patcher (`PagePatch`, `spell/server/site`; epic `epic-engine` P40), with this
1095
+ * runtime's rules laid over the shared ones:
1096
+ * - `ADDED`: what this runtime adds in `main`, stepped around
1097
+ * - `KEPT_ATTRIBUTES`: the reader's
1098
+ * - `MANAGERS`: replaced whole, their open panels carried over
1099
+ * - a host whose body comes from a file (`<ui-section source>`, an epic page's parts: `isSourceHost()`): only its
1100
+ * slotted children (icon, header) are the page's; the body is the file's (`wireSourceBodies()`)
1101
+ * - its `source` changing: replaced, so it loads the new file (never an `<epic-*>`: `EPIC_TAG`)
1102
+ * - a copy brought in: folded as the reader has it, its `<epic-*>` page state kept (`carryState()`)
1103
+ */
1104
+ const patcher = new PagePatch({
614
1105
  skip: ADDED,
615
1106
  keptAttributes: KEPT_ATTRIBUTES,
616
1107
  replacedWhole: MANAGERS,
617
1108
  slotsOnly: isSourceHost,
618
- mustReplace: /* @__PURE__ */ __name((before, after) => !EPIC_TAG.test(after.localName) && before.getAttribute("source") !== after.getAttribute("source"), "mustReplace"),
1109
+ mustReplace: (before, after) =>
1110
+ !EPIC_TAG.test(after.localName) && before.getAttribute("source") !== after.getAttribute("source"),
619
1111
  prepare: carryState
620
- });
1112
+ })
1113
+
1114
+ /**
1115
+ * An edit to this page's file updates it IN PLACE, instead of reloading it (epic page `review-review`, D10).
1116
+ * - `liveClient()` (`spell/server`, the kit's `src/server/liveClient.ts`) hands over the new version when the file
1117
+ * changes (the page server sends it with the change), and fires a cancelable `spell-server:reloading` on `window`,
1118
+ * `detail` `{ path, html, etag, own, reload() }`: taking it (`preventDefault()`) stops its reload
1119
+ * - `own`: the version this page's own save wrote, which it shows already: only taken as the new baseline
1120
+ * - the patch compares the page's source as it LOADED (fetched once, `SPELL_SERVER.readPage()`, trusted only when
1121
+ * its `ETag` is the one served) with the new source, and changes only what differs in the live page:
1122
+ * the kit's patcher (`patcher`, `PagePatch.page()`), a list of small steps, text edited in place;
1123
+ * everything else keeps its scroll, folds, open panels, focus and typed text
1124
+ * - drawn as ONE short cross-fade when it changes what's on screen (`patcher.redraw()`; epic `epic-engine` I164)
1125
+ * - then re-wires what the runtime built from the markup (`rewire()`) and fires `spell-doc:updated` on `window`,
1126
+ * `detail.changed`: the elements added, replaced or re-attributed
1127
+ * - a full reload instead (`reload()`, which keeps the scroll) when the page can't be patched safely:
1128
+ * - not `<ui-section>` markup (the saga pages), a CHEATSHEET's filter, or a script besides the bundle and
1129
+ * highlight.js (it may have built from the markup): never taken. An INERT script (a data block,
1130
+ * `<script type="text/plain">`: an epic page's "Plan hung?" prompt) never runs, so it doesn't count
1131
+ * - stylesheets, scripts or anything outside `main` changed (but `<body>`'s attributes: patched too, e.g. a plan
1132
+ * doc's `data-recent-since`, which every edit may move; not its `class`), more than half of `main` changed,
1133
+ * the source as loaded couldn't be read, or the patch threw
1134
+ * - BODIES from files (`<ui-section source>`, `<ui-accordion source>`: a split epic page's parts) live their own
1135
+ * life (`wireSourceBodies()`): the patch leaves what a host loaded alone (`isSourceHost()`), a changed body file
1136
+ * re-fetches its open host in place, and each body that loads re-wires the page (`refresh()`)
1137
+ * - an epic page in `<epic-*>` markup (epic `epic-components`): its elements are patched, never replaced
1138
+ * (`EPIC_TAG`), their page state kept (`EPIC_PAGE_STATE`);
1139
+ * their parts (`<epic-item source>` ...) live the bodies' life above
1140
+ * - returns `{ ready(page), refresh(changed) }`: `start()` hands over what it wired; a change waits for it.
1141
+ * `refresh()` re-wires after `changed` elements changed under the runtime (a body loaded), in turn with updates
1142
+ */
621
1143
  function wireLiveUpdate(main) {
622
- const server = window.SPELL_SERVER;
623
- let ready = /* @__PURE__ */ __name(() => {
624
- }, "ready");
625
- const started = new Promise((resolve) => ready = resolve);
626
- let queue = Promise.resolve();
627
- const live = { ready, refresh };
628
- wireSourceBodies(main, live, enqueue);
629
- wireLiveCounts(main, refresh);
630
- if (!server?.readPage || !canPatch(main)) return live;
1144
+ const server = window.SPELL_SERVER
1145
+ let ready = () => {}
1146
+ const started = new Promise((resolve) => (ready = resolve))
1147
+ // one update at a time, in order: patches, re-fetched bodies, re-wiring
1148
+ let queue = Promise.resolve()
1149
+ const live = { ready, refresh }
1150
+ wireSourceBodies(main, live, enqueue)
1151
+ wireLiveCounts(main, refresh)
1152
+ if (!server?.readPage || !canPatch(main)) return live
1153
+ // the source as loaded: null when it can't be trusted (the file changed before it was read)
631
1154
  let base = server.readPage().then(
632
- ({ html, etag }) => etag && etag === server.etag ? html : null,
1155
+ ({ html, etag }) => (etag && etag === server.etag ? html : null),
633
1156
  () => null
634
- );
1157
+ )
635
1158
  addEventListener("spell-server:reloading", (event) => {
636
- const { html, reload, own } = event.detail ?? {};
637
- if (typeof html !== "string" || typeof reload !== "function") return;
638
- event.preventDefault();
639
- queue = queue.then(() => update(html, reload, own)).catch(() => reload());
640
- });
641
- return live;
1159
+ const { html, reload, own } = event.detail ?? {}
1160
+ if (typeof html !== "string" || typeof reload !== "function") return
1161
+ event.preventDefault()
1162
+ queue = queue.then(() => update(html, reload, own)).catch(() => reload())
1163
+ })
1164
+ return live
1165
+
1166
+ /**
1167
+ * Patch the page to `html`, then re-wire it; reload when it can't be patched.
1168
+ * - `own`: the page shows it already (its own save): only the new baseline
1169
+ */
642
1170
  async function update(html, reload, own) {
643
1171
  if (own) {
644
- base = Promise.resolve(html);
645
- return;
1172
+ base = Promise.resolve(html)
1173
+ return
646
1174
  }
647
- const [before, page] = await Promise.all([base, started]);
648
- quietFor(QUIET_PATCH_MS);
649
- let patched = null;
1175
+ const [before, page] = await Promise.all([base, started])
1176
+ // no motion while the page takes the change: it's the file, not the reader, moving things
1177
+ quietFor(QUIET_PATCH_MS)
1178
+ let patched = null
650
1179
  try {
651
- patched = before === null ? null : await patcher.redraw({
652
- before: parse(before),
653
- after: parse(html),
654
- live: page.main,
655
- mainOf: mainIn,
656
- top: /* @__PURE__ */ __name(() => stuckBottom(page.main), "top")
657
- });
1180
+ patched =
1181
+ before === null
1182
+ ? null
1183
+ : await patcher.redraw({
1184
+ before: parse(before),
1185
+ after: parse(html),
1186
+ live: page.main,
1187
+ mainOf: mainIn,
1188
+ top: () => stuckBottom(page.main)
1189
+ })
658
1190
  } catch (error) {
659
- console.warn("live update: can't patch this page in place; it reloads once out of sight:", error);
660
- return reload();
1191
+ // says WHY, so a page that keeps falling back to its reload can be fixed (the reload waits until out of sight)
1192
+ console.warn("live update: can't patch this page in place; it reloads once out of sight:", error)
1193
+ return reload()
661
1194
  }
662
1195
  if (!patched) {
663
1196
  console.warn(
664
1197
  `live update: can't patch this page in place (${before === null ? "its source as loaded is unknown" : "its head or shell changed, or too much of it"}); it reloads once out of sight`
665
- );
666
- return reload();
1198
+ )
1199
+ return reload()
667
1200
  }
668
- base = Promise.resolve(html);
669
- await rewire(page, patched.changed);
1201
+ base = Promise.resolve(html)
1202
+ await rewire(page, patched.changed)
670
1203
  }
671
- __name(update, "update");
1204
+
1205
+ /** Re-wire the page once it's started, after `changed` (elements) changed: queued behind the updates. */
672
1206
  function refresh(changed) {
673
- enqueue(async () => rewire(await started, changed));
1207
+ enqueue(async () => rewire(await started, changed))
674
1208
  }
675
- __name(refresh, "refresh");
1209
+
1210
+ /** Run `job` (async) after every update queued before it; a failure doesn't stop the queue. */
676
1211
  function enqueue(job) {
677
- queue = queue.then(job).catch(() => void 0);
1212
+ queue = queue.then(job).catch(() => undefined)
678
1213
  }
679
- __name(enqueue, "enqueue");
680
1214
  }
681
- __name(wireLiveUpdate, "wireLiveUpdate");
1215
+
1216
+ /**
1217
+ * An epic page's blocks' counts changing with no change to the markup (`epic-count-changed`, epic `epic-engine` I147):
1218
+ * an item or phase being worked on, an urgency not applied yet -- the review inbox's, which the blocks follow live.
1219
+ * - the page is re-wired once per frame of such changes (`refresh([])`): the toolbar's badges counted again from each
1220
+ * block's `contentsEntry`, the same live state its chips draw (Owen, 2026-10-26: "badges don't match up")
1221
+ */
682
1222
  function wireLiveCounts(main, refresh) {
683
- let queued = false;
1223
+ let queued = false
684
1224
  main.addEventListener("epic-count-changed", () => {
685
- if (queued) return;
686
- queued = true;
1225
+ if (queued) return
1226
+ queued = true
687
1227
  requestAnimationFrame(() => {
688
- queued = false;
689
- refresh([]);
690
- });
691
- });
1228
+ queued = false
1229
+ refresh([])
1230
+ })
1231
+ })
692
1232
  }
693
- __name(wireLiveCounts, "wireLiveCounts");
694
- var LAZY_SCRIPT = /\/assets\/(lazy|emoji)\//;
1233
+
1234
+ /** A script Spell UI adds to a page as it needs it (`bundle-spell-ui.js`): it only defines data, never reads the markup. */
1235
+ const LAZY_SCRIPT = /\/assets\/(lazy|emoji)\//
1236
+
1237
+ /**
1238
+ * Can this page be patched in place?
1239
+ * - `<ui-section>` markup (or an epic page in `<epic-*>` markup: its `<epic-page>`)
1240
+ * - no CHEATSHEET filter
1241
+ * - no script but the bundle, highlight.js, what the page server injects,
1242
+ * component packs (`<ui-components source="x.pack.js">`'s script, which only defines elements),
1243
+ * the engines and emoji names Spell UI loads as it needs them (`LAZY_SCRIPT`; without them, a page with a
1244
+ * `<ui-markdown>` reloaded on every edit, Owen 2026-11-01: in the side bar, back to its top)
1245
+ * and inert data blocks (`PagePatch.isInert()`: epic pages' "Plan hung?" notice keeps its prompt in one)
1246
+ */
695
1247
  function canPatch(main) {
696
- if (!main.querySelector(":scope > :is(ui-section, epic-page)")) return false;
697
- if (document.querySelector("[data-spell-filter], [data-spell-filter-badge]")) return false;
1248
+ if (!main.querySelector(":scope > :is(ui-section, epic-page)")) return false
1249
+ if (document.querySelector("[data-spell-filter], [data-spell-filter-badge]")) return false
698
1250
  return Array.from(document.scripts).every((script) => {
699
- if (script.hasAttribute("data-spell-page-script")) return true;
700
- const src = script.getAttribute("src");
701
- if (!src) return PagePatch.isInert(script) || script.textContent.includes("SPELL_SERVER");
702
- return /^\/api\/server\//.test(src) || /(^|\/)(spell-ui|highlight(\.min)?|[\w-]+\.pack)\.js$/.test(src) || LAZY_SCRIPT.test(src);
703
- });
1251
+ // one the page server added to every page (`PageServer.withPageScripts()`, spell-app's spell colours): in the
1252
+ // source the patch compares too; without this, every epic page reloaded on every edit (2026-10-25)
1253
+ if (script.hasAttribute("data-spell-page-script")) return true
1254
+ const src = script.getAttribute("src")
1255
+ if (!src) return PagePatch.isInert(script) || script.textContent.includes("SPELL_SERVER")
1256
+ return (
1257
+ /^\/api\/server\//.test(src) ||
1258
+ /(^|\/)(spell-ui|highlight(\.min)?|[\w-]+\.pack)\.js$/.test(src) ||
1259
+ LAZY_SCRIPT.test(src)
1260
+ )
1261
+ })
704
1262
  }
705
- __name(canPatch, "canPatch");
1263
+
1264
+ ////////////////
1265
+ // ## Bodies from files
1266
+ ////////////////
1267
+
1268
+ /**
1269
+ * Hosts whose body comes from a file, in step with the files and the page:
1270
+ * `<ui-section source>`, `<ui-accordion source>`, and an epic page's parts
1271
+ * (`epics/<name>/parts/<id>.html`, epic `claude-design` P3, on its `<epic-*>` blocks and items).
1272
+ * - a body loads (the first open or a re-fetch): the page is re-wired around it (`live.refresh()`):
1273
+ * - `ui-loaded` (`LOADED`), from a Spell UI host or an `<epic-*>` block
1274
+ * the outline (headings inside), contents, counts, item filters, code colors
1275
+ * - a body's FILE changed (the page server's `spell-server:changed`, `liveClient.ts`): a host that has loaded it
1276
+ * re-fetches it in place (`reload()`), the reading position kept (`PagePatch.readingAnchor()`), the old body on screen
1277
+ * until the new one is in, then a short cross-fade (`PagePatch.crossFade()`, I164); one that hasn't drops the
1278
+ * cached copy, so its first open fetches the new one
1279
+ * - `enqueue`: the live update's queue (`wireLiveUpdate()`): a re-fetch waits for a patch in flight
1280
+ */
706
1281
  function wireSourceBodies(main, live, enqueue) {
707
1282
  main.addEventListener(LOADED, (event) => {
708
- const host = event.target;
709
- if (host instanceof Element && host.hasAttribute("source") && main.contains(host)) live.refresh([host]);
710
- });
1283
+ const host = event.target
1284
+ if (host instanceof Element && host.hasAttribute("source") && main.contains(host)) live.refresh([host])
1285
+ })
711
1286
  addEventListener("spell-server:changed", (event) => {
712
- const path = event.detail?.path;
713
- if (typeof path !== "string") return;
714
- const changed = decodeURIComponent(path);
1287
+ const path = event.detail?.path
1288
+ if (typeof path !== "string") return
1289
+ const changed = decodeURIComponent(path)
715
1290
  for (const host of main.querySelectorAll("[source]")) {
716
- const url = sourceUrl(host);
717
- if (!url || decodeURIComponent(url.pathname) !== changed) continue;
718
- if (hasLoaded(host)) enqueue(() => reloadBody(host));
719
- else forgetSource(url.href);
1291
+ const url = sourceUrl(host)
1292
+ if (!url || decodeURIComponent(url.pathname) !== changed) continue
1293
+ if (hasLoaded(host)) enqueue(() => reloadBody(host))
1294
+ else forgetSource(url.href)
720
1295
  }
721
- });
1296
+ })
1297
+
1298
+ /**
1299
+ * Re-fetch `host`'s body, keeping the line being read where it is.
1300
+ * - what had the focus inside it, a note box being typed in: focused again, its caret where it was
1301
+ * - `dock()` puts the same box back;
1302
+ * an `<epic-item>`'s is in its shadow root, which the reload may hide for a moment
1303
+ */
722
1304
  async function reloadBody(host) {
723
- const anchor = PagePatch.readingAnchor(main, stuckBottom(main));
724
- const active = host.contains(document.activeElement) ? deepActiveElement() : null;
725
- const caret = active && "selectionStart" in active ? [active.selectionStart, active.selectionEnd] : null;
726
- const loaded = active && new Promise((done) => {
727
- host.addEventListener(LOADED, done, { once: true });
728
- setTimeout(done, 2e3);
729
- });
1305
+ const anchor = PagePatch.readingAnchor(main, stuckBottom(main))
1306
+ const active = host.contains(document.activeElement) ? deepActiveElement() : null
1307
+ const caret = active && "selectionStart" in active ? [active.selectionStart, active.selectionEnd] : null
1308
+ // the body goes in on the host's `ui-loaded`, which can come after `reload()` resolves;
1309
+ // the runtime's pieces go back on it (`live.refresh()`): wait for it (2s at most), then for them
1310
+ const loaded =
1311
+ active &&
1312
+ new Promise((done) => {
1313
+ host.addEventListener(LOADED, done, { once: true })
1314
+ setTimeout(done, 2000)
1315
+ })
1316
+ // the old body stays up until the new one is in, then one short cross-fade (I164): never the host's loading look
730
1317
  await PagePatch.crossFade(async () => {
731
- const swapped = loaded || bodyIn(host);
732
- await host.reload?.();
733
- await swapped;
734
- PagePatch.keepAnchor(anchor);
735
- }, PagePatch.isOnScreen(host));
736
- if (!active) return;
737
- await loaded;
738
- for (let frame = 0; frame < 60 && !active.isConnected; frame++) await nextFrame(1);
739
- await nextFrame(1);
740
- if (!active.isConnected || deepActiveElement() === active) return;
741
- active.focus({ preventScroll: true });
742
- if (caret) active.setSelectionRange(...caret);
743
- }
744
- __name(reloadBody, "reloadBody");
745
- }
746
- __name(wireSourceBodies, "wireSourceBodies");
1318
+ const swapped = loaded || bodyIn(host)
1319
+ await host.reload?.()
1320
+ await swapped
1321
+ PagePatch.keepAnchor(anchor)
1322
+ }, PagePatch.isOnScreen(host))
1323
+ if (!active) return
1324
+ await loaded
1325
+ for (let frame = 0; frame < 60 && !active.isConnected; frame++) await nextFrame(1)
1326
+ // the host draws what it hid while loading (a frame): hidden, the box can't take the focus
1327
+ await nextFrame(1)
1328
+ if (!active.isConnected || deepActiveElement() === active) return
1329
+ active.focus({ preventScroll: true })
1330
+ if (caret) active.setSelectionRange(...caret)
1331
+ }
1332
+ }
1333
+
1334
+ /** Resolves once `host`'s body is in (its `ui-loaded`), or after `BODY_WAIT_MS` at most. */
747
1335
  function bodyIn(host) {
748
1336
  return new Promise((done) => {
749
- host.addEventListener(LOADED, done, { once: true });
750
- setTimeout(done, BODY_WAIT_MS);
751
- });
1337
+ host.addEventListener(LOADED, done, { once: true })
1338
+ setTimeout(done, BODY_WAIT_MS)
1339
+ })
752
1340
  }
753
- __name(bodyIn, "bodyIn");
1341
+
1342
+ /** The element with the focus, inside shadow roots too (`document.activeElement` stops at their hosts). */
754
1343
  function deepActiveElement() {
755
- let active = document.activeElement;
756
- while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
757
- return active;
1344
+ let active = document.activeElement
1345
+ while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement
1346
+ return active
758
1347
  }
759
- __name(deepActiveElement, "deepActiveElement");
1348
+
1349
+ /** Absolute URL of `host`'s `source`, when it's on this page's origin; else null. */
760
1350
  function sourceUrl(host) {
761
1351
  try {
762
- const url = new URL(host.getAttribute("source"), document.baseURI);
763
- return url.origin === location.origin ? url : null;
1352
+ const url = new URL(host.getAttribute("source"), document.baseURI)
1353
+ return url.origin === location.origin ? url : null
764
1354
  } catch {
765
- return null;
1355
+ return null
766
1356
  }
767
1357
  }
768
- __name(sourceUrl, "sourceUrl");
1358
+
1359
+ /** Has `host` started on its body (loading, loaded, or failed: then a re-fetch tries again)? */
769
1360
  function hasLoaded(host) {
770
1361
  try {
771
- return host.matches(":state(loaded), :state(loading), :state(error)");
1362
+ return host.matches(":state(loaded), :state(loading), :state(error)")
772
1363
  } catch {
773
- return false;
1364
+ return false
774
1365
  }
775
1366
  }
776
- __name(hasLoaded, "hasLoaded");
1367
+
1368
+ /** Drop `url` from UI's cache of fetched files (`UI.sources`), so the next load fetches it. */
777
1369
  function forgetSource(url) {
778
1370
  try {
779
- void window.SpellUI?.UI?.load?.()?.then((ui) => ui.sources.forget(url));
1371
+ void window.SpellUI?.UI?.load?.()?.then((ui) => ui.sources.forget(url))
780
1372
  } catch {
1373
+ // no UI yet: nothing cached either
781
1374
  }
782
1375
  }
783
- __name(forgetSource, "forgetSource");
1376
+
1377
+ /**
1378
+ * The host whose unloaded body holds element `id`: its `data-part-ids` (the ids inside, written by
1379
+ * `PlanParts`; an epic page's `<epic-*>`: `part-ids`), when the element isn't in the page yet; else null.
1380
+ */
784
1381
  function hostHolding(main, id) {
785
- if (!id || document.getElementById(id)) return null;
786
- const ids = /* @__PURE__ */ __name((host) => (host.getAttribute("data-part-ids") ?? host.getAttribute("part-ids") ?? "").split(/\s+/), "ids");
787
- return Array.from(main.querySelectorAll("[source]:is([data-part-ids], [part-ids])")).find(
788
- (host) => ids(host).includes(id)
789
- ) ?? null;
1382
+ if (!id || document.getElementById(id)) return null
1383
+ const ids = (host) => (host.getAttribute("data-part-ids") ?? host.getAttribute("part-ids") ?? "").split(/\s+/)
1384
+ return (
1385
+ Array.from(main.querySelectorAll("[source]:is([data-part-ids], [part-ids])")).find((host) =>
1386
+ ids(host).includes(id)
1387
+ ) ?? null
1388
+ )
790
1389
  }
791
- __name(hostHolding, "hostHolding");
1390
+
1391
+ /** Parse a page's HTML into an inert document. */
792
1392
  function parse(html) {
793
- return new DOMParser().parseFromString(html, "text/html");
1393
+ return new DOMParser().parseFromString(html, "text/html")
794
1394
  }
795
- __name(parse, "parse");
1395
+
1396
+ /** A document's (or body's) `main`, as `start()` finds it. */
796
1397
  function mainIn(root) {
797
- return root.querySelector("main.spell-doc-main") ?? root.querySelector("main");
1398
+ return root.querySelector("main.spell-doc-main") ?? root.querySelector("main")
798
1399
  }
799
- __name(mainIn, "mainIn");
1400
+
1401
+ /**
1402
+ * Is `element` a host whose body comes from a file (`source`), so that only its SLOTTED children (icon, header) are
1403
+ * the page's source? Its body is the file's (`wireSourceBodies()`): the patch leaves it alone.
1404
+ * - not an accordion host (`<ui-accordion source>`): a `MANAGERS` element, replaced whole as ever, its open panel
1405
+ * carried over, so it loads its body again
1406
+ */
800
1407
  function isSourceHost(element) {
801
- return element.hasAttribute("source") && !element.matches(MANAGERS);
1408
+ return element.hasAttribute("source") && !element.matches(MANAGERS)
802
1409
  }
803
- __name(isSourceHost, "isSourceHost");
1410
+
1411
+ /**
1412
+ * Give `copy`, a new or replacing element not yet in the page, the reader's state (the patcher's `prepare()`):
1413
+ * - folds: every section keeps its fold, new ones fold as `carryFolds()` says
1414
+ * - `<epic-*>` page state: `carryEpicState()`
1415
+ * - the kit's shared rules carry the rest: open panels, typed text (`PagePatch.keepReaderState()`)
1416
+ */
804
1417
  function carryState(copy) {
805
- carryFolds(copy);
806
- carryEpicState(copy);
1418
+ carryFolds(copy)
1419
+ carryEpicState(copy)
807
1420
  }
808
- __name(carryState, "carryState");
1421
+
1422
+ /**
1423
+ * Fold every collapsible section in `copy` as the reader has it: as the live one with its `id`, else as saved
1424
+ * (`spell-folds:<path>`), else an epic page's start-folded (`wireFolds()`); else the markup's `open` stands.
1425
+ */
809
1426
  function carryFolds(copy) {
810
- const saved = readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`);
811
- const planDoc = document.body.classList.contains("plan-doc");
1427
+ const saved = readJSON(`${FOLD_KEY_PREFIX}${location.pathname}`)
1428
+ const planDoc = document.body.classList.contains("plan-doc")
812
1429
  for (const section of PagePatch.withSelf(copy, "ui-section[collapsible]")) {
813
- const old = section.id ? document.getElementById(section.id) : null;
814
- if (old?.localName === "ui-section") foldAttribute(section, isCollapsed(old));
815
- else if (section.id && section.id in saved) foldAttribute(section, !!saved[section.id]);
816
- else if (planDoc) foldAttribute(section, true);
1430
+ const old = section.id ? document.getElementById(section.id) : null
1431
+ if (old?.localName === "ui-section") foldAttribute(section, isCollapsed(old))
1432
+ else if (section.id && section.id in saved) foldAttribute(section, !!saved[section.id])
1433
+ else if (planDoc) foldAttribute(section, true)
817
1434
  }
818
1435
  }
819
- __name(carryFolds, "carryFolds");
1436
+
1437
+ /**
1438
+ * Give every `<epic-*>` element with an `id` in `copy` the page state (`EPIC_PAGE_STATE`: `open` ...) of the live one
1439
+ * with that `id` and tag; a new one starts as its markup says (folded: `open` is never in the file).
1440
+ */
820
1441
  function carryEpicState(copy) {
821
1442
  for (const element of PagePatch.withSelf(copy, "[id]")) {
822
- if (!EPIC_TAG.test(element.localName)) continue;
823
- const old = document.getElementById(element.id);
824
- if (old?.localName !== element.localName) continue;
1443
+ if (!EPIC_TAG.test(element.localName)) continue
1444
+ const old = document.getElementById(element.id)
1445
+ if (old?.localName !== element.localName) continue
825
1446
  for (const name of EPIC_PAGE_STATE) {
826
- const value = old.getAttribute(name);
827
- if (value === null) element.removeAttribute(name);
828
- else element.setAttribute(name, value);
1447
+ const value = old.getAttribute(name)
1448
+ if (value === null) element.removeAttribute(name)
1449
+ else element.setAttribute(name, value)
829
1450
  }
830
1451
  }
831
1452
  }
832
- __name(carryEpicState, "carryEpicState");
1453
+
1454
+ /**
1455
+ * After a patch, redo what the runtime built from the markup, as `start()` did:
1456
+ * - the outline (ids for new entries), counts, item filters
1457
+ * - the toolbar, rebuilt only when its entries, icons or counts changed (`railKey()`)
1458
+ * - sticky lines, re-tracked when new sections came in
1459
+ * - code colors and copy buttons (`addCodeCopies()`) in what's new; scroll-follow re-read
1460
+ * - then `spell-doc:updated` on `window`, `detail.changed`
1461
+ * - `page`: what `start()` wired (`{ main, rail, sticky, follow, entries }`); updated here
1462
+ */
833
1463
  async function rewire(page, changed) {
834
- const { main } = page;
835
- quietFor(QUIET_PATCH_MS);
836
- if (main.querySelector("epic-page")) await nextFrame(1);
837
- const outline = outlineOf(main);
838
- const counts = countItems(outline);
839
- wireItemFilters(main);
840
- highlightIn(changed);
841
- addCodeCopies(main);
842
- editMarkdownInPlace(changed);
843
- const entries = railKey(outline, counts);
844
- if (entries !== page.entries) page.rail = buildNavigation(main, outline, counts);
845
- page.entries = entries;
1464
+ const { main } = page
1465
+ quietFor(QUIET_PATCH_MS)
1466
+ // an epic page's blocks take the change in a microtask (Solid batches): each `contentsEntry` reads it after
1467
+ if (main.querySelector("epic-page")) await nextFrame(1)
1468
+ const outline = outlineOf(main)
1469
+ const counts = countItems(outline)
1470
+ wireItemFilters(main)
1471
+ highlightIn(changed)
1472
+ addCodeCopies(main)
1473
+ editMarkdownInPlace(changed)
1474
+ const entries = railKey(outline, counts)
1475
+ if (entries !== page.entries) page.rail = buildNavigation(main, outline, counts)
1476
+ page.entries = entries
846
1477
  if (changed.some((node) => PagePatch.withSelf(node, "ui-section").length))
847
- page.sticky = trackStickyHeights(main, outline);
848
- page.follow.rescan(page.rail);
849
- await nextFrame(UNFOLD_FRAMES);
850
- page.sticky.measure();
851
- page.follow?.update();
852
- dispatchEvent(new CustomEvent("spell-doc:updated", { detail: { changed } }));
853
- }
854
- __name(rewire, "rewire");
1478
+ page.sticky = trackStickyHeights(main, outline)
1479
+ page.follow.rescan(page.rail)
1480
+ await nextFrame(UNFOLD_FRAMES)
1481
+ page.sticky.measure()
1482
+ page.follow?.update()
1483
+ dispatchEvent(new CustomEvent("spell-doc:updated", { detail: { changed } }))
1484
+ }
1485
+
1486
+ /** What the toolbar is built from, as one string: entries, labels, icons, what needs Owen. */
855
1487
  function railKey(outline, counts) {
856
- return JSON.stringify(outline.groups.map(entry));
1488
+ return JSON.stringify(outline.groups.map(entry))
1489
+
1490
+ /**
1491
+ * One top-level entry: its id, label, icon and state, how many of its items need Owen (and how), and how many of
1492
+ * its phases run now.
1493
+ */
857
1494
  function entry(node) {
858
- const count = counts.get(node.element);
1495
+ const count = counts.get(node.element)
859
1496
  return [
860
1497
  node.id,
861
1498
  node.label,
@@ -864,28 +1501,52 @@ function railKey(outline, counts) {
864
1501
  count?.attention ?? 0,
865
1502
  count?.replied ?? 0,
866
1503
  count?.running ?? 0
867
- ];
1504
+ ]
868
1505
  }
869
- __name(entry, "entry");
870
1506
  }
871
- __name(railKey, "railKey");
1507
+
1508
+ /** Color the code blocks in `elements` that aren't yet (`highlight()` colored the rest at load). */
872
1509
  function highlightIn(elements) {
873
- const hljs = globalThis.hljs;
874
- if (!hljs?.highlightElement) return;
1510
+ const hljs = globalThis.hljs
1511
+ if (!hljs?.highlightElement) return
875
1512
  for (const element of elements)
876
1513
  for (const code of PagePatch.withSelf(element, "pre code"))
877
1514
  try {
878
- if (!code.dataset.highlighted) hljs.highlightElement(code);
1515
+ if (!code.dataset.highlighted) hljs.highlightElement(code)
879
1516
  } catch {
1517
+ // plain monospace is fine
880
1518
  }
881
1519
  }
882
- __name(highlightIn, "highlightIn");
1520
+
1521
+ ////////////////
1522
+ // ## Outline
1523
+ ////////////////
1524
+
1525
+ /**
1526
+ * The page's outline, from either markup (see the header): what the toolbar, the counts, scroll-follow
1527
+ * and the anchors work from.
1528
+ * - SECTIONS markup (`main > ui-section`, or an epic page's `<epic-page>`): top-level sections are the groups
1529
+ * - their entries, at any depth:
1530
+ * nested sections, and the h3s / h4s in a section's own content (CHEATSHEET cards, sub-sub-items)
1531
+ * - an h4 right after an h3 of the same section goes under it
1532
+ * - an epic page's sections are its folding blocks
1533
+ * (`EPIC_FOLDS`: the Overview and its parts, the sections, the phases)
1534
+ * - HEADINGS markup: h2s are the groups, h3s their entries, h4s under the h3 before them
1535
+ * - a node: `{ element, id, label, glyph, children }` -- `glyph` the name of its (first) `<ui-icon>`, for the toolbar
1536
+ * - returns `{ sections, groups, orphans, targets, entryOf, groupOf, folded }`:
1537
+ * - `orphans`: entries before or outside any group
1538
+ * - `targets`: selector of every entry's element, for scroll-follow
1539
+ * - `entryOf(element)`: the entry holding `element`, which a jump to it makes current
1540
+ * - `groupOf(entry)`: its top-level element, for the toolbar
1541
+ * - `folded(element)`: hidden by a folded section around it (SECTIONS; HEADINGS hide those with `display`)
1542
+ * - SIDE EFFECT: gives an entry with no `id` a slug of its label (`-2`, `-3` ... when taken)
1543
+ */
883
1544
  function outlineOf(main) {
884
- const sections = !!main.querySelector(":scope > :is(ui-section, epic-page)");
885
- const groups = [];
886
- const orphans = [];
887
- if (sections) readSections();
888
- else readHeadings();
1545
+ const sections = !!main.querySelector(":scope > :is(ui-section, epic-page)")
1546
+ const groups = []
1547
+ const orphans = []
1548
+ if (sections) readSections()
1549
+ else readHeadings()
889
1550
  return {
890
1551
  sections,
891
1552
  groups,
@@ -894,1072 +1555,1752 @@ function outlineOf(main) {
894
1555
  entryOf,
895
1556
  groupOf,
896
1557
  folded
897
- };
1558
+ }
1559
+
1560
+ /**
1561
+ * SECTIONS: every section, h3 and h4 in `main`, under the section it's in.
1562
+ * - not the headings in a plan item's earlier versions (`<epic-original>`): earlier text, not the page's
1563
+ * - not what an epic page's STAGE hides (`<epic-page stage>`, epic `epic-engine` P29; `PageStages.hides()`):
1564
+ * the toolbar lists only what shows
1565
+ */
898
1566
  function readSections() {
899
- const nodes = /* @__PURE__ */ new Map();
1567
+ const nodes = new Map()
900
1568
  const elements = Array.from(main.querySelectorAll(`${SECTIONS}, h3, h4`)).filter(
901
1569
  (element) => !element.closest("epic-original") && !PageStages.hides(element)
902
- );
1570
+ )
903
1571
  for (const element of elements) {
904
- const node = nodeOf(element);
905
- nodes.set(element, node);
906
- const owner = element.parentElement?.closest(SECTIONS);
907
- const list = owner ? nodes.get(owner).children : element.matches(SECTIONS) ? groups : orphans;
908
- const last = list.at(-1);
909
- if (element.localName === "h4" && last?.element.localName === "h3") last.children.push(node);
910
- else list.push(node);
1572
+ const node = nodeOf(element)
1573
+ nodes.set(element, node)
1574
+ const owner = element.parentElement?.closest(SECTIONS)
1575
+ const list = owner ? nodes.get(owner).children : element.matches(SECTIONS) ? groups : orphans
1576
+ const last = list.at(-1)
1577
+ if (element.localName === "h4" && last?.element.localName === "h3") last.children.push(node)
1578
+ else list.push(node)
911
1579
  }
912
1580
  }
913
- __name(readSections, "readSections");
1581
+
1582
+ /** HEADINGS: h2 / h3 / h4 in document order. */
914
1583
  function readHeadings() {
915
1584
  for (const heading of main.querySelectorAll("h2, h3, h4")) {
916
- const node = nodeOf(heading);
917
- const group = groups.at(-1);
918
- if (heading.localName === "h2") groups.push(node);
919
- else if (heading.localName === "h3") (group?.children ?? orphans).push(node);
1585
+ const node = nodeOf(heading)
1586
+ const group = groups.at(-1)
1587
+ if (heading.localName === "h2") groups.push(node)
1588
+ else if (heading.localName === "h3") (group?.children ?? orphans).push(node)
920
1589
  else {
921
- const parent = group?.children.at(-1);
922
- if (parent?.element.localName === "h3") parent.children.push(node);
923
- else (group?.children ?? orphans).push(node);
1590
+ const parent = group?.children.at(-1)
1591
+ if (parent?.element.localName === "h3") parent.children.push(node)
1592
+ else (group?.children ?? orphans).push(node)
924
1593
  }
925
1594
  }
926
1595
  }
927
- __name(readHeadings, "readHeadings");
1596
+
1597
+ /** The entry a jump to `element` makes current: itself, else its section's (heading's) entry. */
928
1598
  function entryOf(element) {
929
- if (sections) return element.closest(`${SECTIONS}, h3, h4`);
930
- if (/^H[234]$/.test(element.tagName)) return element;
931
- return element.closest("section")?.querySelector(":scope > ui-sticky > :is(h2, h3)") ?? null;
1599
+ if (sections) return element.closest(`${SECTIONS}, h3, h4`)
1600
+ if (/^H[234]$/.test(element.tagName)) return element
1601
+ return element.closest("section")?.querySelector(":scope > ui-sticky > :is(h2, h3)") ?? null
932
1602
  }
933
- __name(entryOf, "entryOf");
1603
+
1604
+ /** The top-level element `entry` is in: the outermost section, or the h2. */
934
1605
  function groupOf(entry) {
935
- if (!sections) return entry.localName === "h2" ? entry : entry.closest("section.s2")?.querySelector("h2");
936
- let top = null;
1606
+ if (!sections) return entry.localName === "h2" ? entry : entry.closest("section.s2")?.querySelector("h2")
1607
+ let top = null
937
1608
  for (let section = entry.closest(SECTIONS); section; section = section.parentElement?.closest(SECTIONS))
938
- top = section;
939
- return top;
1609
+ top = section
1610
+ return top
940
1611
  }
941
- __name(groupOf, "groupOf");
1612
+
1613
+ /** Is `element` inside a folded section (not counting itself)? */
942
1614
  function folded(element) {
943
- if (!sections) return false;
944
- for (let section = element.parentElement?.closest(SECTIONS); section; ) {
945
- if (isCollapsed(section)) return true;
946
- section = section.parentElement?.closest(SECTIONS);
1615
+ if (!sections) return false
1616
+ for (let section = element.parentElement?.closest(SECTIONS); section;) {
1617
+ if (isCollapsed(section)) return true
1618
+ section = section.parentElement?.closest(SECTIONS)
947
1619
  }
948
- return false;
1620
+ return false
949
1621
  }
950
- __name(folded, "folded");
951
1622
  }
952
- __name(outlineOf, "outlineOf");
1623
+
1624
+ /**
1625
+ * An outline node for a heading, a `<ui-section>` or an epic page's block; gives it an id if it has none.
1626
+ * - a block: what its host says (`contentsEntry`), its id before it has drawn
1627
+ */
953
1628
  function nodeOf(element) {
954
1629
  if (element.matches(EPIC_FOLDS)) {
955
- const entry = element.contentsEntry;
956
- return { element, id: element.id, label: entry?.label ?? element.id, glyph: entry?.icon, children: [] };
1630
+ const entry = element.contentsEntry
1631
+ return { element, id: element.id, label: entry?.label ?? element.id, glyph: entry?.icon, children: [] }
957
1632
  }
958
- const section = element.localName === "ui-section";
959
- const label = section ? sectionLabel(element) : labelOf(element);
960
- if (!element.id) element.id = uniqueId(headingSlug(label) || "section");
961
- const glyph = section ? element.querySelector(':scope > ui-icon[slot="icon"]')?.getAttribute("name") ?? element.getAttribute("icon") : element.querySelector("ui-icon")?.getAttribute("name");
962
- return { element, id: element.id, label, glyph: glyph || void 0, children: [] };
1633
+ const section = element.localName === "ui-section"
1634
+ const label = section ? sectionLabel(element) : labelOf(element)
1635
+ if (!element.id) element.id = uniqueId(headingSlug(label) || "section")
1636
+ const glyph = section
1637
+ ? (element.querySelector(':scope > ui-icon[slot="icon"]')?.getAttribute("name") ?? element.getAttribute("icon"))
1638
+ : element.querySelector("ui-icon")?.getAttribute("name")
1639
+ return { element, id: element.id, label, glyph: glyph || undefined, children: [] }
963
1640
  }
964
- __name(nodeOf, "nodeOf");
1641
+
1642
+ /** A `<ui-section>`'s label: its `label`, else the text of its `slot="label"` child. */
965
1643
  function sectionLabel(section) {
966
- const label = section.getAttribute("label")?.trim();
967
- if (label) return label;
968
- const slotted = section.querySelector(':scope > [slot="label"]');
969
- return slotted ? labelOf(slotted) : "";
1644
+ const label = section.getAttribute("label")?.trim()
1645
+ if (label) return label
1646
+ const slotted = section.querySelector(':scope > [slot="label"]')
1647
+ return slotted ? labelOf(slotted) : ""
970
1648
  }
971
- __name(sectionLabel, "sectionLabel");
1649
+
1650
+ /** `id`, or `id-2`, `id-3` ... if the page already has it. */
972
1651
  function uniqueId(id) {
973
- let candidate = id;
974
- for (let n = 2; document.getElementById(candidate); n++) candidate = `${id}-${n}`;
975
- return candidate;
1652
+ let candidate = id
1653
+ for (let n = 2; document.getElementById(candidate); n++) candidate = `${id}-${n}`
1654
+ return candidate
976
1655
  }
977
- __name(uniqueId, "uniqueId");
1656
+
1657
+ /**
1658
+ * Is `section` folded? A `<ui-section>`: not `open`, by the property, else (not upgraded yet) `open="false"`;
1659
+ * an epic page's block (or item): not `open`, by the property, else the attribute.
1660
+ */
978
1661
  function isCollapsed(section) {
979
1662
  if (section.matches(EPIC_OPENERS))
980
- return !(typeof section.open === "boolean" ? section.open : section.hasAttribute("open"));
981
- return typeof section.open === "boolean" ? !section.open : section.getAttribute("open") === "false";
1663
+ return !(typeof section.open === "boolean" ? section.open : section.hasAttribute("open"))
1664
+ return typeof section.open === "boolean" ? !section.open : section.getAttribute("open") === "false"
982
1665
  }
983
- __name(isCollapsed, "isCollapsed");
1666
+
1667
+ /**
1668
+ * Fold or unfold a section without an event: `open` (a `<ui-section>`, and an epic page's blocks and
1669
+ * items) is controlled, so writing it announces nothing.
1670
+ */
984
1671
  function setCollapsed(section, collapsed) {
985
- if (section.matches(EPIC_OPENERS)) section.toggleAttribute("open", !collapsed);
986
- else foldAttribute(section, collapsed);
1672
+ if (section.matches(EPIC_OPENERS)) section.toggleAttribute("open", !collapsed)
1673
+ else foldAttribute(section, collapsed)
987
1674
  }
988
- __name(setCollapsed, "setCollapsed");
1675
+
1676
+ /** Fold a `<ui-section>` (`open="false"`) or open it (no `open`: open is its default), by the attribute. */
989
1677
  function foldAttribute(section, isFolded) {
990
- if (isFolded) section.setAttribute("open", "false");
991
- else section.removeAttribute("open");
1678
+ if (isFolded) section.setAttribute("open", "false")
1679
+ else section.removeAttribute("open")
992
1680
  }
993
- __name(foldAttribute, "foldAttribute");
1681
+
1682
+ /**
1683
+ * The shadow title bar of a `<ui-section>` (its public `title` part), once it has rendered; an epic page's block's:
1684
+ * the one of the `<ui-section>` it draws in its own shadow root.
1685
+ */
994
1686
  function titleOf(section) {
995
- const inner = section.matches(EPIC_FOLDS) ? section.shadowRoot?.querySelector("ui-section") : section;
996
- return inner?.shadowRoot?.querySelector('[part~="title"]') ?? null;
1687
+ const inner = section.matches(EPIC_FOLDS) ? section.shadowRoot?.querySelector("ui-section") : section
1688
+ return inner?.shadowRoot?.querySelector('[part~="title"]') ?? null
997
1689
  }
998
- __name(titleOf, "titleOf");
1690
+
1691
+ ////////////////
1692
+ // ## Text
1693
+ ////////////////
1694
+
1695
+ /** A heading's label: its text without badges, whitespace collapsed. */
999
1696
  function labelOf(heading) {
1000
- const clone = heading.cloneNode(true);
1001
- for (const badge of clone.querySelectorAll(".tag, ui-label")) badge.remove();
1002
- return clone.textContent.replace(/\s+/g, " ").trim();
1697
+ const clone = heading.cloneNode(true)
1698
+ for (const badge of clone.querySelectorAll(".tag, ui-label")) badge.remove()
1699
+ return clone.textContent.replace(/\s+/g, " ").trim()
1003
1700
  }
1004
- __name(labelOf, "labelOf");
1701
+
1702
+ /** A heading's id from its `label`: the kit's `slug()`, cut at 48. */
1005
1703
  function headingSlug(label) {
1006
- return slug(label).slice(0, 48);
1704
+ return slug(label).slice(0, 48)
1007
1705
  }
1008
- __name(headingSlug, "headingSlug");
1009
- var CLOSED = /* @__PURE__ */ new Set(["done", "decided", "canceled"]);
1010
- var EPIC_ATTENTION = ':scope > epic-item:is([state="attention"], [state="replied"]), :scope > epic-phase[state="attention"]';
1011
- var EPIC_REPLIED = ':scope > :is(epic-item, epic-phase)[state="replied"]';
1012
- var EPIC_RUNNING = ':scope > epic-phase[status="active"]';
1706
+
1707
+ ////////////////
1708
+ // ## Counts
1709
+ ////////////////
1710
+
1711
+ /**
1712
+ * Item statuses that DON'T count as open: finished (`done`), made moot (`canceled`), and a plan's answered
1713
+ * questions (`decided`) -- in "Questions" only the questions waiting on the reader are open.
1714
+ * - `spell/epic/tool/planDoc.types` `CLOSED` is the same set
1715
+ */
1716
+ const CLOSED = new Set(["done", "decided", "canceled"])
1717
+
1718
+ /**
1719
+ * An epic page's block's items that need Owen, when its `contentsEntry` count doesn't say:
1720
+ * its own items (`COUNTED` in `spell-epic`'s `EpicSection.types.ts`) the `epic` tool marked
1721
+ * - `attention` (red)
1722
+ * - or `replied` (orange: Claude answered with options, the person's turn to pick; `EpicItem.types.ts` `NEEDS_PERSON`).
1723
+ */
1724
+ const EPIC_ATTENTION =
1725
+ ':scope > epic-item:is([state="attention"], [state="replied"]), :scope > epic-phase[state="attention"]'
1726
+
1727
+ /**
1728
+ * Of those, the ones Claude answered with options, waiting on the person's pick (`replied`, orange):
1729
+ * the plan-doc toolbar shows them apart from the urgent ones (red; `buildToolbar()`).
1730
+ */
1731
+ const EPIC_REPLIED = ':scope > :is(epic-item, epic-phase)[state="replied"]'
1732
+
1733
+ /**
1734
+ * The Phases section's phases running now (`status="active"`): the toolbar's blue badge on the Phases button
1735
+ * (epic `epic-engine` P43; Owen, 2026-10-25: "blue badge for the number of things currently running")
1736
+ */
1737
+ const EPIC_RUNNING = ':scope > epic-phase[status="active"]'
1738
+
1739
+ /** A count pill's tooltip: "2 need you", "1 needs you". */
1013
1740
  function needYou({ attention }) {
1014
- return `${attention} ${attention === 1 ? "needs" : "need"} you`;
1741
+ return `${attention} ${attention === 1 ? "needs" : "need"} you`
1015
1742
  }
1016
- __name(needYou, "needYou");
1743
+
1744
+ /**
1745
+ * Each top-level section's items -- `[data-status]` elements, not counting ones inside another --
1746
+ * as `{ open, total, attention }`, by the group's element (the `<ui-section>`, or the h2).
1747
+ * - "open": any status but `CLOSED`'s
1748
+ * - "attention": the items that need the person (`stateOf()`: the toolbar's red badge, Q20 of epic `epic-components`)
1749
+ * - sections without items are left out; nested sections get no count of their own
1750
+ * - the Epics index's epic cards, the saga pages' items
1751
+ * - an epic page's sections count themselves (`<epic-section>`, on their titles): their count is read from their
1752
+ * hosts' `contentsEntry`, never written;
1753
+ * its `attention` too, else the items' `state="attention"` (`EPIC_ATTENTION`);
1754
+ * and `replied`, how many of those wait on Owen's pick (else `EPIC_REPLIED`: the toolbar's orange badge);
1755
+ * and `running`, the Phases section's phases at work now (else `EPIC_RUNNING`: the toolbar's blue badge, P43;
1756
+ * the host's own counts a phase being worked on too, I147)
1757
+ * - the host's counts are its items AS DRAWN (`DrawnState`): an item being worked on counts blue, never red
1758
+ * - SIDE EFFECT: writes `open/total` on the section's title: its `badge` (SECTIONS), or a `ui-label.spell-count`
1759
+ * at the right of the h2 (HEADINGS); callable again (it replaces both)
1760
+ */
1017
1761
  function countItems(outline) {
1018
- const counts = /* @__PURE__ */ new Map();
1762
+ const counts = new Map()
1019
1763
  for (const { element } of outline.groups) {
1020
1764
  if (element.matches(EPIC_FOLDS)) {
1021
- const count = element.contentsEntry?.count;
1765
+ const count = element.contentsEntry?.count
1022
1766
  if (count) {
1023
- const attention2 = count.attention ?? element.querySelectorAll(EPIC_ATTENTION).length;
1024
- const replied = count.replied ?? Math.min(attention2, element.querySelectorAll(EPIC_REPLIED).length);
1025
- const running = count.running ?? element.querySelectorAll(EPIC_RUNNING).length;
1026
- counts.set(element, { ...count, attention: attention2, replied, running });
1767
+ // the block's own, as drawn (`EpicSection.countOf()`: live, an item being worked on blue, not red); else
1768
+ // the markup's
1769
+ const attention = count.attention ?? element.querySelectorAll(EPIC_ATTENTION).length
1770
+ const replied = count.replied ?? Math.min(attention, element.querySelectorAll(EPIC_REPLIED).length)
1771
+ const running = count.running ?? element.querySelectorAll(EPIC_RUNNING).length
1772
+ counts.set(element, { ...count, attention, replied, running })
1027
1773
  }
1028
- continue;
1774
+ continue
1029
1775
  }
1030
- const section = outline.sections ? element : headingSection(element);
1031
- if (!section) continue;
1032
- const items = Array.from(section.querySelectorAll("[data-status]")).filter((item) => outermost(item, section));
1033
- if (!items.length) continue;
1034
- const open = items.filter((item) => !CLOSED.has(item.dataset.status)).length;
1035
- const attention = items.filter((item) => stateOf(item) === "attention").length;
1036
- counts.set(element, { open, total: items.length, attention });
1776
+ const section = outline.sections ? element : headingSection(element)
1777
+ if (!section) continue
1778
+ const items = Array.from(section.querySelectorAll("[data-status]")).filter((item) => outermost(item, section))
1779
+ if (!items.length) continue
1780
+ const open = items.filter((item) => !CLOSED.has(item.dataset.status)).length
1781
+ const attention = items.filter((item) => stateOf(item) === "attention").length
1782
+ counts.set(element, { open, total: items.length, attention })
1037
1783
  if (outline.sections) {
1038
- element.setAttribute("badge", `${open}/${items.length}`);
1039
- continue;
1784
+ element.setAttribute("badge", `${open}/${items.length}`)
1785
+ continue
1040
1786
  }
1041
- element.querySelector(":scope > ui-label.spell-count")?.remove();
1042
- const label = document.createElement("ui-label");
1043
- label.className = "spell-count";
1044
- label.setAttribute("size", "tiny");
1045
- label.setAttribute("appearance", "basic");
1046
- label.title = `${open} open of ${items.length}`;
1047
- label.textContent = `${open}/${items.length}`;
1048
- element.append(label);
1049
- }
1050
- return counts;
1051
- }
1052
- __name(countItems, "countItems");
1787
+ element.querySelector(":scope > ui-label.spell-count")?.remove()
1788
+ const label = document.createElement("ui-label")
1789
+ label.className = "spell-count"
1790
+ label.setAttribute("size", "tiny")
1791
+ label.setAttribute("appearance", "basic")
1792
+ label.title = `${open} open of ${items.length}`
1793
+ label.textContent = `${open}/${items.length}`
1794
+ element.append(label)
1795
+ }
1796
+ return counts
1797
+ }
1798
+
1799
+ /** The `section.s2` an h2 heads (`section > ui-sticky.spell-h2 > h2`), else null. */
1053
1800
  function headingSection(h2) {
1054
- const sticky = h2.parentElement;
1055
- return sticky?.matches("section > ui-sticky.spell-h2") ? sticky.parentElement : null;
1801
+ const sticky = h2.parentElement
1802
+ return sticky?.matches("section > ui-sticky.spell-h2") ? sticky.parentElement : null
1056
1803
  }
1057
- __name(headingSection, "headingSection");
1804
+
1805
+ /** Is `item` the outermost `[data-status]` within `section` (not an item's part)? */
1058
1806
  function outermost(item, section) {
1059
- const outer = item.parentElement?.closest("[data-status]");
1060
- return !outer || !section.contains(outer);
1807
+ const outer = item.parentElement?.closest("[data-status]")
1808
+ return !outer || !section.contains(outer)
1061
1809
  }
1062
- __name(outermost, "outermost");
1063
- var ITEM_STATES = [
1810
+
1811
+ ////////////////
1812
+ // ## Item states and filter
1813
+ ////////////////
1814
+
1815
+ /**
1816
+ * Where an item stands, in the colours Owen reads at a glance: `[state, tooltip words]` (an id chip's tooltip,
1817
+ * `stateTip()`; the filter's chips are `<epic-state-filter>`'s, in its order, `FILTER_STATES`).
1818
+ * - the colour scheme (Q20 of epic `epic-components`, 2026-10-08; `templates/epics/plan-doc.md`, "Colours"):
1819
+ * attention red, progress blue (Claude is working on it), open yellow, recent green, old grey;
1820
+ * `spell-doc.css`'s `--spell-state-*` tokens
1821
+ * - for the Epics index's epic cards (`.spell-epics`) and the saga pages' items (`.plan-items`, coloured by
1822
+ * `goals.css`); an epic page's items colour and filter themselves (`<epic-item>`, `<epic-section>`)
1823
+ * - `data-state` when the page writes one; else from the status (`stateOf()`)
1824
+ */
1825
+ const ITEM_STATES = [
1064
1826
  ["attention", "needs you"],
1065
1827
  ["progress", "Claude is working on it"],
1066
1828
  ["open", "open, still undecided"],
1067
1829
  ["recent", "decided or done"],
1068
1830
  ["old", "no longer relevant"]
1069
- ];
1070
- var CLOSED_STATES = { done: "recent", decided: "recent", canceled: "old" };
1071
- var STATE_NAMES = new Set(ITEM_STATES.map(([state]) => state));
1072
- var STATE_ITEMS = ":is(.plan-items, .spell-epics) > [data-status]";
1073
- var ASKS_PERSON = '.plan-items[data-kind="question"] > *';
1831
+ ]
1832
+
1833
+ /**
1834
+ * A closed item's state, by its status:
1835
+ * - decided or done stay `recent` (green) however old
1836
+ * - only `canceled` is `old` (grey: no longer relevant)
1837
+ * - Owen, 2026-10-08; `spell-epic` `PlanReader.itemState()`, the same rule
1838
+ */
1839
+ const CLOSED_STATES = { done: "recent", decided: "recent", canceled: "old" }
1840
+
1841
+ /** The state names, for checking a `data-state`. */
1842
+ const STATE_NAMES = new Set(ITEM_STATES.map(([state]) => state))
1843
+
1844
+ /** The saga pages' items, and the index's epic cards: what states and the filter apply to. */
1845
+ const STATE_ITEMS = ":is(.plan-items, .spell-epics) > [data-status]"
1846
+
1847
+ /** The saga pages' items that wait on Owen while open: their questions (`/goals` talks them through with him). */
1848
+ const ASKS_PERSON = '.plan-items[data-kind="question"] > *'
1849
+
1850
+ /**
1851
+ * An item's state: its `data-state`, else (the index's epic cards, the saga pages' items) from its status:
1852
+ * `done` / `decided` are `recent`, `canceled` `old` (`CLOSED_STATES`); an open goals question (`ASKS_PERSON`)
1853
+ * `attention`; anything else `open`.
1854
+ */
1074
1855
  function stateOf(item) {
1075
- const state = item.dataset.state;
1076
- if (STATE_NAMES.has(state)) return state;
1077
- if (CLOSED.has(item.dataset.status)) return CLOSED_STATES[item.dataset.status];
1078
- return item.matches(ASKS_PERSON) ? "attention" : "open";
1856
+ const state = item.dataset.state
1857
+ if (STATE_NAMES.has(state)) return state
1858
+ if (CLOSED.has(item.dataset.status)) return CLOSED_STATES[item.dataset.status]
1859
+ return item.matches(ASKS_PERSON) ? "attention" : "open"
1079
1860
  }
1080
- __name(stateOf, "stateOf");
1861
+
1862
+ /**
1863
+ * An item's id chip's tooltip: where it stands in words, then its review marks (Owen, 2026-10-04), e.g.
1864
+ * "Needs your attention · not reviewed yet", "Decided or reviewed recently · reviewed 2026-10-03".
1865
+ */
1081
1866
  function stateTip(item) {
1082
- const words = ITEM_STATES.find(([state]) => state === item.dataset.spellState)?.[1] ?? "";
1083
- const parts = [words.charAt(0).toUpperCase() + words.slice(1)];
1084
- const { reviewed, deferred, queued, work, status } = item.dataset;
1085
- if (queued) parts.push(`to do: ${work || "queued"}`);
1086
- if (reviewed) parts.push(`reviewed ${reviewed}`);
1087
- else if (deferred) parts.push(`deferred ${deferred}`);
1088
- else if (status === "open") parts.push("not reviewed yet");
1089
- return parts.join(" · ");
1090
- }
1091
- __name(stateTip, "stateTip");
1867
+ const words = ITEM_STATES.find(([state]) => state === item.dataset.spellState)?.[1] ?? ""
1868
+ const parts = [words.charAt(0).toUpperCase() + words.slice(1)]
1869
+ const { reviewed, deferred, queued, work, status } = item.dataset
1870
+ if (queued) parts.push(`to do: ${work || "queued"}`)
1871
+ if (reviewed) parts.push(`reviewed ${reviewed}`)
1872
+ else if (deferred) parts.push(`deferred ${deferred}`)
1873
+ else if (status === "open") parts.push("not reviewed yet")
1874
+ return parts.join(" · ")
1875
+ }
1876
+
1877
+ /**
1878
+ * Mark every item's state as `data-spell-state` (`stateOf()`), so CSS has ONE attribute to color by;
1879
+ * an item's id chip (`.plan-id`, the saga pages') says it in words.
1880
+ * - SIDE EFFECT: sets `data-spell-state`;
1881
+ * callable again (a page updated in place: a replaced item comes back without it)
1882
+ */
1092
1883
  function markItemStates(main) {
1093
1884
  for (const item of main.querySelectorAll(STATE_ITEMS)) {
1094
- item.dataset.spellState = stateOf(item);
1095
- const chip = item.querySelector(".plan-id");
1096
- if (chip) chip.title = stateTip(item);
1885
+ item.dataset.spellState = stateOf(item)
1886
+ const chip = item.querySelector(".plan-id")
1887
+ if (chip) chip.title = stateTip(item)
1097
1888
  }
1098
1889
  }
1099
- __name(markItemStates, "markItemStates");
1890
+
1891
+ /**
1892
+ * The status filter on every top-level `<ui-section>` with a filterable list
1893
+ * (the index's `.spell-epics`, a `.plan-items` list, each holding `[data-status]` children):
1894
+ * - its chips are the epics pack's `<epic-state-filter>` (epic `epic-engine` P3):
1895
+ * the ONE chip element, an epic page's too
1896
+ * - a chip per state the section has items in, in its colour, with how many (Owen, 2026-10-10: no filter icon)
1897
+ * - SOLID while its items show, OUTLINED while hidden
1898
+ * - a click (`epic-state-changed`), by the one rule (`StateFilter.nextShown()`, in the element):
1899
+ * - everything showing: only that state
1900
+ * - else a hidden state shows too, and a shown one hides
1901
+ * - the only one showing: everything again
1902
+ * - an ⌥-click: only that state, whatever showed (epic `epic-engine` I166: the element's `shown` says so)
1903
+ * - in the title's `actions` slot (`.spell-item-filter`); `spell-doc.css` puts it left of the count badge
1904
+ * - a filtered list shows "3 hidden · show all" under it (`<epic-hidden-note class="spell-hidden-note">`):
1905
+ * a click there (`epic-all-showing`) shows all
1906
+ * - the choice: `data-show="<states shown>"` on the section (none for all),
1907
+ * `data-spell-hidden` on the items it hides (CSS hides them)
1908
+ * - remembered per page (`localStorage`, `{ [section id]: [states] }`); all by default
1909
+ * - an epic page's sections filter themselves (`<epic-section>`), with the same element
1910
+ * - SIDE EFFECT: marks the items' states (`markItemStates()`), adds the chips and notes to the page;
1911
+ * callable again (it replaces the ones it added)
1912
+ */
1100
1913
  function wireItemFilters(main) {
1101
- const key = `${ITEM_FILTER_KEY_PREFIX}${location.pathname}`;
1102
- const saved = readJSON(key);
1103
- for (const old of main.querySelectorAll(":scope > ui-section > .spell-item-filter, .spell-hidden-note")) old.remove();
1104
- markItemStates(main);
1914
+ const key = `${ITEM_FILTER_KEY_PREFIX}${location.pathname}`
1915
+ const saved = readJSON(key)
1916
+ for (const old of main.querySelectorAll(":scope > ui-section > .spell-item-filter, .spell-hidden-note")) old.remove()
1917
+ markItemStates(main)
1105
1918
  for (const section of main.querySelectorAll(":scope > ui-section[id]")) {
1106
- let choose = function(shown) {
1107
- showItems(filter, shown);
1108
- saved[section.id] = shown;
1109
- writeJSON(key, saved);
1110
- };
1111
- __name(choose, "choose");
1112
- const lists = Array.from(section.querySelectorAll(".plan-items, .spell-epics")).filter(
1113
- (list) => list.querySelector(":scope > [data-status]")
1114
- );
1115
- if (!lists.length) continue;
1116
- const counts = /* @__PURE__ */ new Map();
1919
+ const lists = Array.from(section.querySelectorAll(".plan-items, .spell-epics")).filter((list) =>
1920
+ list.querySelector(":scope > [data-status]")
1921
+ )
1922
+ if (!lists.length) continue
1923
+ const counts = new Map()
1117
1924
  for (const item of lists.flatMap(itemsOf))
1118
- counts.set(item.dataset.spellState, (counts.get(item.dataset.spellState) ?? 0) + 1);
1119
- const states = [...counts.keys()];
1925
+ counts.set(item.dataset.spellState, (counts.get(item.dataset.spellState) ?? 0) + 1)
1926
+ const states = [...counts.keys()]
1120
1927
  const chips = el("epic-state-filter", {
1121
1928
  class: "spell-item-filter",
1122
1929
  slot: "actions",
1123
1930
  counts: [...counts].map(([state, count]) => `${state}:${count}`).join(" "),
1124
1931
  "data-spell-added": true
1125
- });
1126
- chips.addEventListener("epic-state-changed", (event) => choose(event.detail.shown));
1932
+ })
1933
+ chips.addEventListener("epic-state-changed", (event) => choose(event.detail.shown))
1127
1934
  const notes = lists.map((list) => {
1128
- const note = el("epic-hidden-note", { class: "spell-hidden-note", hidden: true, "data-spell-added": true });
1129
- note.addEventListener("epic-all-showing", () => choose(states));
1130
- list.after(note);
1131
- return note;
1132
- });
1133
- section.append(chips);
1134
- const filter = { section, lists, notes, chips, states };
1135
- const remembered = Array.isArray(saved[section.id]) ? saved[section.id].filter((state) => counts.has(state)) : [];
1136
- showItems(filter, remembered.length ? remembered : states);
1137
- }
1138
- }
1139
- __name(wireItemFilters, "wireItemFilters");
1935
+ const note = el("epic-hidden-note", { class: "spell-hidden-note", hidden: true, "data-spell-added": true })
1936
+ note.addEventListener("epic-all-showing", () => choose(states))
1937
+ list.after(note)
1938
+ return note
1939
+ })
1940
+ section.append(chips)
1941
+ const filter = { section, lists, notes, chips, states }
1942
+ const remembered = Array.isArray(saved[section.id]) ? saved[section.id].filter((state) => counts.has(state)) : []
1943
+ showItems(filter, remembered.length ? remembered : states)
1944
+
1945
+ /** The reader picked the states `shown`: apply them and remember. */
1946
+ function choose(shown) {
1947
+ showItems(filter, shown)
1948
+ saved[section.id] = shown
1949
+ writeJSON(key, saved)
1950
+ }
1951
+ }
1952
+ }
1953
+
1954
+ /**
1955
+ * Show the items of the states `shown` in a filter's section (`{ section, lists, notes, chips, states }`).
1956
+ * - its chips say which (`shown`, none while every state shows)
1957
+ * - an "N hidden" note under each list that hides any
1958
+ */
1140
1959
  function showItems({ section, lists, notes, chips, states }, shown) {
1141
- const showing = new Set(shown);
1142
- const everything = states.every((state) => showing.has(state));
1960
+ const showing = new Set(shown)
1961
+ const everything = states.every((state) => showing.has(state))
1143
1962
  if (everything) {
1144
- delete section.dataset.show;
1145
- chips.removeAttribute("shown");
1963
+ delete section.dataset.show
1964
+ chips.removeAttribute("shown")
1146
1965
  } else {
1147
- section.dataset.show = [...showing].join(" ");
1148
- chips.setAttribute("shown", section.dataset.show);
1966
+ section.dataset.show = [...showing].join(" ")
1967
+ chips.setAttribute("shown", section.dataset.show)
1149
1968
  }
1150
1969
  lists.forEach((list, index) => {
1151
- let hidden = 0;
1970
+ let hidden = 0
1152
1971
  for (const item of itemsOf(list)) {
1153
- const hide = !showing.has(item.dataset.spellState);
1154
- item.toggleAttribute("data-spell-hidden", hide);
1155
- if (hide) hidden++;
1972
+ const hide = !showing.has(item.dataset.spellState)
1973
+ item.toggleAttribute("data-spell-hidden", hide)
1974
+ if (hide) hidden++
1156
1975
  }
1157
- notes[index].hidden = hidden === 0;
1158
- notes[index].setAttribute("count", String(hidden));
1159
- });
1976
+ notes[index].hidden = hidden === 0
1977
+ notes[index].setAttribute("count", String(hidden))
1978
+ })
1160
1979
  }
1161
- __name(showItems, "showItems");
1980
+
1981
+ /** A filterable list's items: its `[data-status]` children. */
1162
1982
  function itemsOf(list) {
1163
- return Array.from(list.querySelectorAll(":scope > [data-status]"));
1983
+ return Array.from(list.querySelectorAll(":scope > [data-status]"))
1164
1984
  }
1165
- __name(itemsOf, "itemsOf");
1985
+
1986
+ ////////////////
1987
+ // ## Editing in place
1988
+ ////////////////
1989
+
1990
+ /**
1991
+ * Every `<ui-markdown>` of a page the page server may save is edited where it's drawn: ⌥-click a paragraph, a
1992
+ * heading, a list item or a table cell (epic `epic-engine` P60, request r53; Owen: "click in e.g. a table cell and
1993
+ * edit the text there directly, auto-save immediately").
1994
+ * - `editable` set on each in `nodes` without one of its own, so `editable="tabs"` stays
1995
+ * - only when the page says it may be saved (`SPELL_SERVER.writable`: its file in the page server's writable
1996
+ * folders); from disk, or a page outside them, nothing changes
1997
+ * - the live page only: the page's file never holds it, so a live update never takes it away (the patch compares
1998
+ * the file's versions); a block a patch brings in gets it here (`rewire()`)
1999
+ * - a plain click reads as before: ⌥ is the only way in, so no pencil and no mode
2000
+ */
1166
2001
  function editMarkdownInPlace(nodes) {
1167
- if (!window.SPELL_SERVER?.writable) return;
2002
+ if (!window.SPELL_SERVER?.writable) return
1168
2003
  for (const node of nodes) {
1169
2004
  for (const markdown of PagePatch.withSelf(node, "ui-markdown"))
1170
- if (!markdown.hasAttribute("editable")) markdown.setAttribute("editable", "");
2005
+ if (!markdown.hasAttribute("editable")) markdown.setAttribute("editable", "")
1171
2006
  }
1172
2007
  }
1173
- __name(editMarkdownInPlace, "editMarkdownInPlace");
2008
+
2009
+ ////////////////
2010
+ // ## Steps
2011
+ ////////////////
2012
+
2013
+ /**
2014
+ * A `<ui-steps>` too long for one row goes vertical, one step per row, as wide as the column, with no arrows.
2015
+ * - horizontal, its steps wrap, each with the arrow pointing at the next step, over nothing, and its text wherever
2016
+ * its number's width leaves it
2017
+ * - measured as each shows and changes width: a folded section's has no size until it opens
2018
+ * - a page's own `direction` is left alone
2019
+ */
1174
2020
  function stackWrappedSteps(main) {
1175
- const widths = /* @__PURE__ */ new WeakMap();
2021
+ const widths = new WeakMap()
1176
2022
  const watch = new ResizeObserver(async (entries) => {
1177
2023
  for (const { target, contentRect } of entries) {
1178
- if (!contentRect.width || widths.get(target) === contentRect.width) continue;
1179
- widths.set(target, contentRect.width);
1180
- target.removeAttribute("direction");
1181
- target.removeAttribute("fluid");
1182
- await nextFrame(1);
1183
- const tops = [...target.children].map((step) => step.shadowRoot?.querySelector('[part~="step"]'));
1184
- const rows = new Set(tops.map((each) => each?.getBoundingClientRect().top));
1185
- if (rows.size < 2) continue;
1186
- target.setAttribute("direction", "vertical");
1187
- target.setAttribute("fluid", "");
2024
+ if (!contentRect.width || widths.get(target) === contentRect.width) continue
2025
+ widths.set(target, contentRect.width)
2026
+ target.removeAttribute("direction")
2027
+ target.removeAttribute("fluid")
2028
+ await nextFrame(1)
2029
+ const tops = [...target.children].map((step) => step.shadowRoot?.querySelector('[part~="step"]'))
2030
+ const rows = new Set(tops.map((each) => each?.getBoundingClientRect().top))
2031
+ if (rows.size < 2) continue
2032
+ target.setAttribute("direction", "vertical")
2033
+ target.setAttribute("fluid", "")
1188
2034
  }
1189
- });
1190
- for (const steps of main.querySelectorAll("ui-steps:not([direction])")) watch.observe(steps);
2035
+ })
2036
+ for (const steps of main.querySelectorAll("ui-steps:not([direction])")) watch.observe(steps)
1191
2037
  }
1192
- __name(stackWrappedSteps, "stackWrappedSteps");
2038
+
2039
+ ////////////////
2040
+ // ## Toolbar
2041
+ ////////////////
2042
+
2043
+ /**
2044
+ * The page's navigation: an epic page's toolbar (`buildToolbar()`), else the page toolbar (`buildPageToolbar()`).
2045
+ * - both the SAME element, Spell UI's menu (`toolbarMenu()`): a guide's and an epic page's band look and behave alike
2046
+ * - returns the menu, whose `[data-rail]` items scroll-follow marks `selected`; none without top-level sections
2047
+ * - `data-rail`: the name the floating rail gave them (gone since epic `airplane` P8)
2048
+ * - kept, as scroll-follow, a details page's `<epic-ask>` and `check-spell.js` read it
2049
+ */
1193
2050
  function buildNavigation(main, outline, counts) {
1194
- const page = document.body.classList.contains("plan-doc") ? main.querySelector("epic-page") : null;
1195
- return page ? buildToolbar(page, outline, counts) : buildPageToolbar(main, outline, counts);
2051
+ const page = document.body.classList.contains("plan-doc") ? main.querySelector("epic-page") : null
2052
+ return page ? buildToolbar(page, outline, counts) : buildPageToolbar(main, outline, counts)
1196
2053
  }
1197
- __name(buildNavigation, "buildNavigation");
2054
+
2055
+ /**
2056
+ * Every other page's navigation: a row of buttons, one per top-level section, in the sticky page header,
2057
+ * in place of the floating rail.
2058
+ * - Owen, 2026-10-10: "Make the floating sidebar in guides a sticky top toolbar like the epic page.
2059
+ * Have section titles in this one"
2060
+ * - each: the section's mark and its title, a link to it (`wireAnchors()` lands it);
2061
+ * scroll-follow marks the current one `selected`, by `data-rail`
2062
+ * - the mark: an item's number, an icon, a number or a letter
2063
+ * (`titledItems()`, `spell-doc-toolbar.js`, which Epic UI's pages build theirs with too)
2064
+ * - a red badge: how many of its items need Owen (`counts`, `attention`); none, none
2065
+ * - its titles fit the row, as Spell UI's `<ui-toolbar shrinkable>` fits them (`toolbarMenu()`):
2066
+ * - too long for the row, the longest end in `...` first
2067
+ * - when one would be cut under 50px, they go: the buttons show their marks only, the title as their tooltip
2068
+ * - narrower still, every button folds into one `...` button, whose menu holds them all
2069
+ * - where: the last row of the sticky page header (`ui-sticky.spell-h1 > header.spell-page-head`),
2070
+ * so it sticks with it and the titles stick below it
2071
+ * - a page without one (the saga pages, a cheat sheet): the last row of its filter bar (`.spell-filter`),
2072
+ * else a sticky bar of its own before the first section
2073
+ * (`.spell-toolbar-alone`, measured as the filter bar is: `trackStickyHeights()`)
2074
+ * - HEADINGS (the saga pages): only the h2s that head a sticky section
2075
+ * - callable again (a page updated in place): replaces the toolbar it built before
2076
+ * - SIDE EFFECT: adds the menu inside `main`, marked `data-spell-added` so the live patch steps around it;
2077
+ * removes a hand-written `.spell-toc-open` (pages before 2026-10-01 had a "Contents" button)
2078
+ */
1198
2079
  function buildPageToolbar(main, outline, counts) {
1199
- const groups = outline.sections ? outline.groups : outline.groups.filter((group) => headingSection(group.element));
2080
+ const groups = outline.sections ? outline.groups : outline.groups.filter((group) => headingSection(group.element))
1200
2081
  const items = titledItems(groups, (element) => {
1201
- const count = counts.get(element);
1202
- return count?.attention ? [["urgent", count.attention, needYou(count)]] : [];
1203
- });
2082
+ const count = counts.get(element)
2083
+ return count?.attention ? [["urgent", count.attention, needYou(count)]] : []
2084
+ })
1204
2085
  if (!items.length) {
1205
- removeToolbar();
1206
- return void 0;
2086
+ removeToolbar()
2087
+ return undefined
1207
2088
  }
1208
- const toolbar = toolbarMenu(items, { titled: true });
1209
- const head = main.querySelector(":scope > ui-sticky.spell-h1 > .spell-page-head") ?? main.querySelector(".spell-filter");
1210
- if (head) head.append(toolbar);
2089
+ const toolbar = toolbarMenu(items, { titled: true })
2090
+ const head =
2091
+ main.querySelector(":scope > ui-sticky.spell-h1 > .spell-page-head") ?? main.querySelector(".spell-filter")
2092
+ if (head) head.append(toolbar)
1211
2093
  else {
1212
- toolbar.classList.add("spell-toolbar-alone");
1213
- const first = groups[0].element;
1214
- (outline.sections ? first : headingSection(first) ?? first).before(toolbar);
2094
+ toolbar.classList.add("spell-toolbar-alone")
2095
+ const first = groups[0].element
2096
+ ;(outline.sections ? first : (headingSection(first) ?? first)).before(toolbar)
1215
2097
  }
1216
- return toolbar;
2098
+ return toolbar
1217
2099
  }
1218
- __name(buildPageToolbar, "buildPageToolbar");
2100
+
2101
+ /**
2102
+ * An EPIC PAGE's navigation (epic `airplane` P8, Owen 2026-10-10: "The contents sidebar on the epic page should be a
2103
+ * sticky top toolbar instead"): a row of buttons across the bottom of `<epic-page>`'s sticky header, one per
2104
+ * top-level block (Overview, Phases, Questions ... Log), in place of the floating rail it had before.
2105
+ * - each: the block's icon, a link to it (`wireAnchors()` lands it); its title without its number (`Questions`)
2106
+ * only as its tooltip and name (Owen, 2026-10-10: "lose the titles ... when I click on the thing it goes to that
2107
+ * section anyway"); scroll-follow marks the current one `selected`, by `data-rail` (as the rail's)
2108
+ * - BADGES: how many of the block's items wait on Owen, from `counts` (none: no badge)
2109
+ * - red: urgent (`state="attention"`)
2110
+ * - orange: Claude answered with options, their turn to pick (`state="replied"`)
2111
+ * - blue: the Phases button's, how many phases run now (`status="active"`; epic `epic-engine` P43)
2112
+ * - several kinds: every one, red first, then orange, then blue
2113
+ * - over the icon's top right, a third of a badge on the icon: every button is the same width, badge or not
2114
+ * (Owen, 2026-10-10: "Make badge 1/3 way overlap the icon")
2115
+ * - in the header's `toolbar` slot (`<epic-page>`'s): it sticks with the header,
2116
+ * and the header's measured height, where every title below sticks (`--epic-stack`), takes it in
2117
+ * - `<epic-page>` draws the rest of that row at its right:
2118
+ * the page's state filter, collapse-all, the new item button
2119
+ * - a window too narrow for every button:
2120
+ * the row scrolls sideways (`spell-toolbar.css`), the current button scrolled into view
2121
+ * - callable again (a page updated in place): replaces the toolbar built before
2122
+ * - SIDE EFFECT: appends the menu to `page`, marked `data-spell-added` so the live patch steps around it
2123
+ */
1219
2124
  function buildToolbar(page, outline, counts) {
1220
2125
  const items = outline.groups.map(({ element, id, label, glyph }) => {
1221
- const count = counts.get(element);
1222
- const replied = count?.replied ?? 0;
1223
- const urgent = (count?.attention ?? 0) - replied;
1224
- const name = shortLabel(label);
1225
- const running = count?.running ?? 0;
1226
- const waits = replied === 1 ? "waits" : "wait";
2126
+ const count = counts.get(element)
2127
+ const replied = count?.replied ?? 0
2128
+ const urgent = (count?.attention ?? 0) - replied
2129
+ const name = shortLabel(label)
2130
+ const running = count?.running ?? 0
2131
+ const waits = replied === 1 ? "waits" : "wait"
1227
2132
  return toolbarItem({
1228
2133
  id,
1229
2134
  tip: name,
1230
2135
  glyph,
1231
2136
  // no icon: the label's first letter stands in
1232
- mark: glyph ? void 0 : el("b", { slot: "icon" }, name.charAt(0)),
2137
+ mark: glyph ? undefined : el("b", { slot: "icon" }, name.charAt(0)),
1233
2138
  badges: [
1234
2139
  ["urgent", urgent, `${urgent} urgent`],
1235
2140
  ["replied", replied, `${replied} replied: ${waits} for your pick`],
1236
2141
  ["running", running, `${running} running now`]
1237
2142
  ].filter(([, number]) => number > 0)
1238
- });
1239
- });
2143
+ })
2144
+ })
1240
2145
  if (!items.length) {
1241
- removeToolbar();
1242
- return void 0;
2146
+ removeToolbar()
2147
+ return undefined
1243
2148
  }
1244
- const toolbar = toolbarMenu(items, { titled: false });
1245
- toolbar.slot = "toolbar";
1246
- page.append(toolbar);
1247
- return toolbar;
2149
+ const toolbar = toolbarMenu(items, { titled: false })
2150
+ toolbar.slot = "toolbar"
2151
+ page.append(toolbar)
2152
+ return toolbar
1248
2153
  }
1249
- __name(buildToolbar, "buildToolbar");
2154
+
2155
+ // the menu itself, its items, fitting their titles and the jump key: `spell-doc-toolbar.js`, which Epic UI's pages
2156
+ // load too (epic `epic-engine` T11)
2157
+
2158
+ ////////////////
2159
+ // ## Folding
2160
+ ////////////////
2161
+
2162
+ /**
2163
+ * Every section folds, and the reader's folds are remembered per page (`localStorage`, `{ [id]: folded }`).
2164
+ * - SECTIONS: `<ui-section collapsible>` folds itself;
2165
+ * this restores the saved folds (else the markup's `open` stands)
2166
+ * and saves the reader's toggles (`ui-opening` / `ui-closing`; an `<epic-*>` block's `ui-opening` / `ui-closing`)
2167
+ * - an EPIC PAGE (`body.plan-doc`): every section and sub-section not in the saved folds starts FOLDED,
2168
+ * whatever its markup says: Owen opens what he wants to read (2026-10-03)
2169
+ * - a link to an id inside still lands (`reveal()` unfolds around it)
2170
+ * - its `<epic-*>` blocks start folded by themselves;
2171
+ * the ones the reader left open open again (`restoreEpicFolds()`, before they draw),
2172
+ * but the Log, which starts folded on every load (`STAYS_FOLDED`),
2173
+ * and their toggles are saved as a section's
2174
+ * - HEADINGS: a chevron button starts each h2 / h3,
2175
+ * and a click anywhere on the heading (not on a link or button in it) toggles it too;
2176
+ * folded: `section.spell-folded`, all but the heading hidden by CSS.
2177
+ * Starts folded as saved, else when the section says `data-fold="closed"`.
2178
+ * - `reveal()` unfolding for a link is never saved
2179
+ * - returns `{ reveal(element) }`: unfold every section hiding `element` (an epic page's blocks and items too, and
2180
+ * a phase's folded fields: `<epic-field>`'s `reveal()`), and open its own panel, or itself if it's a folded plan item;
2181
+ * true when it unfolded something (it draws a little later)
2182
+ * - a `<ui-section>` unfolds WITHOUT its height animation (`--ui-section-duration: 0s` on `main` for a few frames):
2183
+ * the jump measures the target once it has drawn,
2184
+ * and a growing box would move it (scroll anchoring) after the page has landed
2185
+ * - `kept`: the folds a live reload puts back (`takeKeptFolds()`), over the saved ones and the markup's
2186
+ * - callable again (a page updated in place): drops the listeners of the call before (`foldWiring`);
2187
+ * a heading that has its chevron keeps it
2188
+ */
2189
+ /**
2190
+ * ONE button that opens or folds every section and sub-section, first in the toolbar's tools (`toolbarTools()`).
2191
+ * - Owen, 2026-11-01: "single expand/collapse button"
2192
+ * - any section folded: double chevron down, Expand all; all open: up, Collapse all (`wireFolds()`' `foldAll()`)
2193
+ * - not an epic page: its own toolbar has one (`<epic-page>`)
2194
+ * - added once: a toolbar built anew keeps it
2195
+ */
1250
2196
  function addFoldAll(main, folds) {
1251
- const tools = toolbarTools(main.querySelector(".spell-toolbar"));
1252
- if (!tools || document.body.classList.contains("plan-doc") || tools.querySelector(".spell-toolbar-fold")) return;
1253
- if (!main.querySelector("ui-section[collapsible]")) return;
1254
- const anyFolded = /* @__PURE__ */ __name(() => [...main.querySelectorAll("ui-section[collapsible]")].some(isCollapsed), "anyFolded");
1255
- const item = el("ui-button", { class: "spell-toolbar-fold", appearance: "circular basic", size: "mini" });
1256
- const show = /* @__PURE__ */ __name(() => {
1257
- const tip = anyFolded() ? "Expand all" : "Collapse all";
1258
- item.setAttribute("icon", anyFolded() ? "angles down" : "angles up");
1259
- item.title = tip;
1260
- item.setAttribute("aria-label", tip);
1261
- titleInside(item);
1262
- }, "show");
1263
- item.addEventListener("click", () => folds.foldAll(!anyFolded()));
1264
- new MutationObserver(show).observe(main, { attributes: true, attributeFilter: ["open"], subtree: true });
1265
- show();
1266
- tools.prepend(item);
1267
- }
1268
- __name(addFoldAll, "addFoldAll");
2197
+ const tools = toolbarTools(main.querySelector(".spell-toolbar"))
2198
+ if (!tools || document.body.classList.contains("plan-doc") || tools.querySelector(".spell-toolbar-fold")) return
2199
+ if (!main.querySelector("ui-section[collapsible]")) return
2200
+ const anyFolded = () => [...main.querySelectorAll("ui-section[collapsible]")].some(isCollapsed)
2201
+ const item = el("ui-button", { class: "spell-toolbar-fold", appearance: "circular basic", size: "mini" })
2202
+ const show = () => {
2203
+ const tip = anyFolded() ? "Expand all" : "Collapse all"
2204
+ item.setAttribute("icon", anyFolded() ? "angles down" : "angles up")
2205
+ item.title = tip
2206
+ item.setAttribute("aria-label", tip)
2207
+ titleInside(item)
2208
+ }
2209
+ item.addEventListener("click", () => folds.foldAll(!anyFolded()))
2210
+ new MutationObserver(show).observe(main, { attributes: true, attributeFilter: ["open"], subtree: true })
2211
+ show()
2212
+ tools.prepend(item)
2213
+ }
2214
+
1269
2215
  function wireFolds(main, outline, kept) {
1270
- foldWiring?.abort();
1271
- foldWiring = new AbortController();
1272
- const { signal } = foldWiring;
1273
- const key = `${FOLD_KEY_PREFIX}${location.pathname}`;
1274
- const saved = readJSON(key);
1275
- if (outline.sections) wireSectionFolds();
1276
- else wireHeadingFolds();
1277
- return { reveal, foldAll, outermostFolded };
2216
+ foldWiring?.abort()
2217
+ foldWiring = new AbortController()
2218
+ const { signal } = foldWiring
2219
+ const key = `${FOLD_KEY_PREFIX}${location.pathname}`
2220
+ const saved = readJSON(key)
2221
+ if (outline.sections) wireSectionFolds()
2222
+ else wireHeadingFolds()
2223
+ return { reveal, foldAll, outermostFolded }
2224
+
2225
+ /**
2226
+ * The outermost fold hiding `element`, if any: its comments show after that fold's title (`drawPromoted()`).
2227
+ */
1278
2228
  function outermostFolded(element) {
1279
- const folds = outline.sections ? `ui-section, ${EPIC_OPENERS}` : "section.spell-folded";
1280
- let found;
2229
+ const folds = outline.sections ? `ui-section, ${EPIC_OPENERS}` : "section.spell-folded"
2230
+ let found
1281
2231
  for (let section = element.closest(folds); section; section = section.parentElement?.closest(folds))
1282
- if (!outline.sections || isCollapsed(section)) found = section;
1283
- return found;
2232
+ if (!outline.sections || isCollapsed(section)) found = section
2233
+ return found
1284
2234
  }
1285
- __name(outermostFolded, "outermostFolded");
2235
+
2236
+ /**
2237
+ * Fold (`isFolded`) or open every section and sub-section at once, without their height animation, remembered as
2238
+ * the reader's folds: the toolbar's Collapse all / Expand all (`addFoldAll()`).
2239
+ * - folding them all shows the page from its top: every title, folded, fits in a window or two
2240
+ */
1286
2241
  function foldAll(isFolded) {
1287
- main.style.setProperty("--ui-section-duration", "0s");
2242
+ main.style.setProperty("--ui-section-duration", "0s")
1288
2243
  for (const section of main.querySelectorAll("ui-section[collapsible]")) {
1289
- setCollapsed(section, isFolded);
1290
- if (section.id) saved[section.id] = isFolded;
2244
+ setCollapsed(section, isFolded)
2245
+ if (section.id) saved[section.id] = isFolded
1291
2246
  }
1292
- writeJSON(key, saved);
1293
- if (isFolded) scrollTo({ top: 0, behavior: "instant" });
1294
- requestAnimationFrame(() => requestAnimationFrame(() => main.style.removeProperty("--ui-section-duration")));
2247
+ writeJSON(key, saved)
2248
+ if (isFolded) scrollTo({ top: 0, behavior: "instant" })
2249
+ requestAnimationFrame(() => requestAnimationFrame(() => main.style.removeProperty("--ui-section-duration")))
1295
2250
  }
1296
- __name(foldAll, "foldAll");
2251
+
2252
+ /** SECTIONS: restore the saved folds (an epic page: the rest start folded), save the reader's. */
1297
2253
  function wireSectionFolds() {
1298
- const startFolded = document.body.classList.contains("plan-doc");
2254
+ const startFolded = document.body.classList.contains("plan-doc")
1299
2255
  for (const section of main.querySelectorAll("ui-section[collapsible][id]"))
1300
- if (kept && section.id in kept) setCollapsed(section, !kept[section.id]);
1301
- else if (section.id in saved) setCollapsed(section, !!saved[section.id]);
1302
- else if (startFolded) setCollapsed(section, true);
1303
- for (const name of [...OPENING, ...CLOSING]) main.addEventListener(name, onToggle, { signal });
1304
- for (const name of CLOSING) main.addEventListener(name, holdWhileFolding, { signal });
2256
+ if (kept && section.id in kept) setCollapsed(section, !kept[section.id])
2257
+ else if (section.id in saved) setCollapsed(section, !!saved[section.id])
2258
+ else if (startFolded) setCollapsed(section, true)
2259
+ for (const name of [...OPENING, ...CLOSING]) main.addEventListener(name, onToggle, { signal })
2260
+ for (const name of CLOSING) main.addEventListener(name, holdWhileFolding, { signal })
1305
2261
  }
1306
- __name(wireSectionFolds, "wireSectionFolds");
2262
+
2263
+ /**
2264
+ * Any fold closing (a section, an epic page's Overview part, phase or item): its header stays where it is on screen
2265
+ * while the content folds away under it.
2266
+ * - why: the browser's scroll anchoring kept something BELOW the fold in place instead, so the clicked header slid
2267
+ * down hundreds of pixels as its body shrank, then wobbled (Owen, 2026-10-10: "the 1.1 sections bounce when
2268
+ * closed"; measured: the header moved 336 -> 692px)
2269
+ * - anchoring is off for the page while it folds; each frame, the header is put back where it was
2270
+ * - starts after the toggle's own handlers (a microtask): `keepTitlePut()` / an item's `keepLinePut()` may first
2271
+ * scroll a STUCK title into place, and that's the place kept
2272
+ * - near the end of a short page (everything else folded), the page would get shorter than where it's scrolled to,
2273
+ * and the browser pulls it back: the header jumps down. So the page keeps its height (`min-height`) until the
2274
+ * reader scrolls back far enough for the shorter page to hold him
2275
+ * - stops after `FOLD_HOLD_MS`, or at once when the reader scrolls
2276
+ * - ONLY a fold's closing (a section, an epic block, an accordion): a `<ui-popup>` sends a cancelable `ui-closing`
2277
+ * as it hides, and a hidden popup's top is 0, so holding it scrolled the page to the top (epic `epic-engine` r5)
2278
+ */
1307
2279
  function holdWhileFolding(event) {
1308
- if (event.defaultPrevented || !event.cancelable || !(event.target instanceof Element)) return;
1309
- const element = event.target;
1310
- if (!element.matches(FOLDING) || !element.getClientRects().length) return;
2280
+ if (event.defaultPrevented || !event.cancelable || !(event.target instanceof Element)) return
2281
+ const element = event.target
2282
+ if (!element.matches(FOLDING) || !element.getClientRects().length) return
1311
2283
  queueMicrotask(() => {
1312
- const root = document.documentElement;
1313
- const before = element.getBoundingClientRect().top;
1314
- const until = performance.now() + FOLD_HOLD_MS;
1315
- let stopped = false;
1316
- const stop = /* @__PURE__ */ __name(() => stopped = true, "stop");
1317
- addEventListener("wheel", stop, { once: true, passive: true });
1318
- addEventListener("touchmove", stop, { once: true, passive: true });
1319
- root.style.overflowAnchor = "none";
1320
- root.style.minHeight = `${root.scrollHeight}px`;
1321
- const hold = /* @__PURE__ */ __name(() => {
1322
- const off = element.getBoundingClientRect().top - before;
1323
- if (!stopped && Math.abs(off) >= 1) scrollTo({ top: scrollY + off, behavior: "instant" });
1324
- if (!stopped && performance.now() < until) return requestAnimationFrame(hold);
1325
- root.style.overflowAnchor = "";
1326
- removeEventListener("wheel", stop);
1327
- removeEventListener("touchmove", stop);
1328
- releaseHeight(root);
1329
- }, "hold");
1330
- requestAnimationFrame(hold);
1331
- });
1332
- }
1333
- __name(holdWhileFolding, "holdWhileFolding");
2284
+ const root = document.documentElement
2285
+ const before = element.getBoundingClientRect().top
2286
+ const until = performance.now() + FOLD_HOLD_MS
2287
+ let stopped = false
2288
+ const stop = () => (stopped = true)
2289
+ addEventListener("wheel", stop, { once: true, passive: true })
2290
+ addEventListener("touchmove", stop, { once: true, passive: true })
2291
+ root.style.overflowAnchor = "none"
2292
+ root.style.minHeight = `${root.scrollHeight}px`
2293
+ const hold = () => {
2294
+ const off = element.getBoundingClientRect().top - before
2295
+ if (!stopped && Math.abs(off) >= 1) scrollTo({ top: scrollY + off, behavior: "instant" })
2296
+ if (!stopped && performance.now() < until) return requestAnimationFrame(hold)
2297
+ root.style.overflowAnchor = ""
2298
+ removeEventListener("wheel", stop)
2299
+ removeEventListener("touchmove", stop)
2300
+ releaseHeight(root)
2301
+ }
2302
+ requestAnimationFrame(hold)
2303
+ })
2304
+ }
2305
+
2306
+ /**
2307
+ * Let the page take its natural height again once that no longer pulls the reader back: at once if it fits where
2308
+ * he's scrolled to, else as soon as he scrolls up far enough.
2309
+ * - the held height only ever shrinks to the window's bottom (`scrollY + clientHeight`), never below:
2310
+ * the page is then exactly as tall as it must be to stay where it's scrolled;
2311
+ * if it's still taller than that, the content is, and the hold can go
2312
+ * - NEVER measures the natural height by taking the hold off for a moment: that layout alone makes the browser
2313
+ * clamp the scroll to the shorter page, and the reader dropped by however much shorter it was (I7 of `airplane`:
2314
+ * the line of an item a link had landed near the page's end fell 20-80px when the hold ended)
2315
+ */
1334
2316
  function releaseHeight(root) {
1335
- const release = /* @__PURE__ */ __name(() => {
1336
- const bottom = scrollY + root.clientHeight;
1337
- if (bottom < parseFloat(root.style.minHeight)) root.style.minHeight = `${bottom}px`;
1338
- if (root.scrollHeight <= bottom + 1) return false;
1339
- root.style.minHeight = "";
1340
- removeEventListener("scroll", release);
1341
- return true;
1342
- }, "release");
1343
- if (!release()) addEventListener("scroll", release, { passive: true });
1344
- }
1345
- __name(releaseHeight, "releaseHeight");
2317
+ const release = () => {
2318
+ const bottom = scrollY + root.clientHeight
2319
+ if (bottom < parseFloat(root.style.minHeight)) root.style.minHeight = `${bottom}px`
2320
+ if (root.scrollHeight <= bottom + 1) return false
2321
+ root.style.minHeight = ""
2322
+ removeEventListener("scroll", release)
2323
+ return true
2324
+ }
2325
+ if (!release()) addEventListener("scroll", release, { passive: true })
2326
+ }
2327
+
2328
+ /**
2329
+ * The reader folded or unfolded a section (accordions' `ui-opening` / `ui-closing` bubble here too: not ours).
2330
+ * - an opening that can't be cancelled is the BROWSER's reveal (find-in-page, a `#hash` load):
2331
+ * not saved, as a link's unfold isn't
2332
+ */
1346
2333
  function onToggle(event) {
1347
- const section = event.target;
1348
- if (event.defaultPrevented || !event.cancelable || !section.matches?.(SECTIONS) || !section.id) return;
1349
- saved[section.id] = !event.detail?.open;
1350
- writeJSON(key, saved);
1351
- if (!event.detail?.open) keepTitlePut(section);
2334
+ const section = event.target
2335
+ if (event.defaultPrevented || !event.cancelable || !section.matches?.(SECTIONS) || !section.id) return
2336
+ saved[section.id] = !event.detail?.open
2337
+ writeJSON(key, saved)
2338
+ if (!event.detail?.open) keepTitlePut(section)
1352
2339
  }
1353
- __name(onToggle, "onToggle");
2340
+
2341
+ /**
2342
+ * Folding a section the reader is INSIDE (its title stuck, its top scrolled past): scroll at once so the title
2343
+ * stays where it's stuck, and the content folds away below it.
2344
+ * - why: else the title drops back to the section's top, far above, and the page slides up after the
2345
+ * shrinking content (Owen's "bounce", 2026-10-04)
2346
+ */
1354
2347
  function keepTitlePut(section) {
1355
- const title = titleOf(section);
1356
- if (!title) return;
1357
- const stuckAt = title.getBoundingClientRect().top;
1358
- const top = section.getBoundingClientRect().top;
1359
- if (top >= stuckAt - 1) return;
1360
- scrollTo({ top: scrollY + top - stuckAt, behavior: "instant" });
1361
- }
1362
- __name(keepTitlePut, "keepTitlePut");
2348
+ const title = titleOf(section)
2349
+ if (!title) return
2350
+ const stuckAt = title.getBoundingClientRect().top
2351
+ const top = section.getBoundingClientRect().top
2352
+ if (top >= stuckAt - 1) return
2353
+ scrollTo({ top: scrollY + top - stuckAt, behavior: "instant" })
2354
+ }
2355
+
2356
+ /** HEADINGS: a chevron on every h2 / h3 of a sticky section. */
1363
2357
  function wireHeadingFolds() {
1364
2358
  for (const sticky of main.querySelectorAll("section > ui-sticky:is(.spell-h2, .spell-h3)")) {
1365
- const heading = sticky.firstElementChild;
1366
- if (!heading?.id || heading.querySelector(":scope > ui-button.spell-fold")) continue;
1367
- const section = sticky.parentElement;
1368
- const button = document.createElement("ui-button");
1369
- button.className = "spell-fold";
1370
- const tip = "Fold / unfold";
1371
- const attributes = { circular: "", basic: "", size: "mini", icon: "chevron down", title: tip, "aria-label": tip };
1372
- for (const [name, value] of Object.entries(attributes)) button.setAttribute(name, value);
1373
- titleInside(button);
1374
- heading.prepend(button);
1375
- heading.classList.add("spell-foldable");
1376
- if (kept && heading.id in kept) setFolded(section, !kept[heading.id]);
1377
- else setFolded(section, heading.id in saved ? !!saved[heading.id] : section.dataset.fold === "closed");
2359
+ const heading = sticky.firstElementChild
2360
+ if (!heading?.id || heading.querySelector(":scope > ui-button.spell-fold")) continue
2361
+ const section = sticky.parentElement
2362
+ const button = document.createElement("ui-button")
2363
+ button.className = "spell-fold"
2364
+ // its tooltip the browser's own, on the button the pointer lands on ("TOOLTIPS"; a `<ui-popup>` before I32)
2365
+ const tip = "Fold / unfold"
2366
+ const attributes = { circular: "", basic: "", size: "mini", icon: "chevron down", title: tip, "aria-label": tip }
2367
+ for (const [name, value] of Object.entries(attributes)) button.setAttribute(name, value)
2368
+ titleInside(button)
2369
+ heading.prepend(button)
2370
+ heading.classList.add("spell-foldable")
2371
+ if (kept && heading.id in kept) setFolded(section, !kept[heading.id])
2372
+ else setFolded(section, heading.id in saved ? !!saved[heading.id] : section.dataset.fold === "closed")
1378
2373
  heading.addEventListener("click", (event) => {
1379
- const path = event.composedPath();
2374
+ // the chevron's own `<button>` (in its shadow root) comes first in the path: look for the HOST
2375
+ const path = event.composedPath()
1380
2376
  if (!path.includes(button)) {
1381
- const before = path.slice(0, Math.max(0, path.indexOf(heading)));
1382
- if (before.some((node) => node instanceof Element && node.matches("a, ui-button, button"))) return;
2377
+ const before = path.slice(0, Math.max(0, path.indexOf(heading)))
2378
+ if (before.some((node) => node instanceof Element && node.matches("a, ui-button, button"))) return
1383
2379
  }
1384
- event.preventDefault();
1385
- const folded = !section.classList.contains("spell-folded");
1386
- setFolded(section, folded);
1387
- saved[heading.id] = folded;
1388
- writeJSON(key, saved);
1389
- });
2380
+ event.preventDefault()
2381
+ const folded = !section.classList.contains("spell-folded")
2382
+ setFolded(section, folded)
2383
+ saved[heading.id] = folded
2384
+ writeJSON(key, saved)
2385
+ })
1390
2386
  }
1391
2387
  }
1392
- __name(wireHeadingFolds, "wireHeadingFolds");
2388
+
2389
+ /**
2390
+ * Unfold every section around `element`; open `element`'s own folded panel.
2391
+ * - `self: false`: only what's AROUND it -- a folded section, or an item's closed panel, stays as it is
2392
+ */
1393
2393
  function reveal(element, { self = true } = {}) {
1394
- const shown = !!element.closest("epic-section")?.showLinked?.(element);
1395
- let unfolded = false;
2394
+ // on an epic page: shown even where its page's stage, or its section's state filter, hides it (epic `epic-engine`
2395
+ // I191: a To review chip's J2, in the Judgement calls a page still agreeing its phases hides)
2396
+ const shown = !!element.closest("epic-section")?.showLinked?.(element)
2397
+ let unfolded = false
1396
2398
  if (outline.sections) {
1397
- const folds = `ui-section, ${EPIC_OPENERS}`;
1398
- for (let section = self ? element.closest(folds) : element.parentElement?.closest(folds); section; section = section.parentElement?.closest(folds)) {
1399
- if (!isCollapsed(section)) continue;
1400
- if (!unfolded) main.style.setProperty("--ui-section-duration", "0s");
1401
- setCollapsed(section, false);
1402
- unfolded = true;
2399
+ const folds = `ui-section, ${EPIC_OPENERS}`
2400
+ for (
2401
+ let section = self ? element.closest(folds) : element.parentElement?.closest(folds);
2402
+ section;
2403
+ section = section.parentElement?.closest(folds)
2404
+ ) {
2405
+ if (!isCollapsed(section)) continue
2406
+ if (!unfolded) main.style.setProperty("--ui-section-duration", "0s")
2407
+ setCollapsed(section, false)
2408
+ unfolded = true
1403
2409
  }
1404
- if (unfolded) void nextFrame(UNFOLD_FRAMES + 1).then(() => main.style.removeProperty("--ui-section-duration"));
2410
+ if (unfolded) void nextFrame(UNFOLD_FRAMES + 1).then(() => main.style.removeProperty("--ui-section-duration"))
1405
2411
  } else {
1406
- for (let section = element.closest("section.spell-folded"); section; section = section.parentElement?.closest("section.spell-folded"))
1407
- setFolded(section, false);
2412
+ for (
2413
+ let section = element.closest("section.spell-folded");
2414
+ section;
2415
+ section = section.parentElement?.closest("section.spell-folded")
2416
+ )
2417
+ setFolded(section, false)
1408
2418
  }
1409
- for (let field = self ? element.closest(FIELDS_THAT_FOLD) : element.parentElement?.closest(FIELDS_THAT_FOLD); field; field = field.parentElement?.closest(FIELDS_THAT_FOLD))
1410
- if (field.component?.reveal?.()) unfolded = true;
1411
- const panel = self ? element.querySelector(":scope > ui-accordion > ui-title") : null;
1412
- if (panel && !isPanelOpen(panel)) setPanel(panel, true);
1413
- for (let content = element.closest("ui-accordion > ui-content"); content; content = content.parentElement.parentElement?.closest("ui-accordion > ui-content")) {
1414
- const accordion = content.parentElement;
1415
- const contents = Array.from(accordion.children).filter((child) => child.localName === "ui-content");
1416
- const title = titlesOf(accordion)[contents.indexOf(content)];
1417
- if (!title || isPanelOpen(title)) continue;
1418
- setPanel(title, true);
1419
- unfolded = true;
2419
+ // a folded field around it (a phase's Symptom, Goal ...; epic `epic-engine` I167): opened, never remembered
2420
+ for (
2421
+ let field = self ? element.closest(FIELDS_THAT_FOLD) : element.parentElement?.closest(FIELDS_THAT_FOLD);
2422
+ field;
2423
+ field = field.parentElement?.closest(FIELDS_THAT_FOLD)
2424
+ )
2425
+ if (field.component?.reveal?.()) unfolded = true
2426
+ const panel = self ? element.querySelector(":scope > ui-accordion > ui-title") : null
2427
+ if (panel && !isPanelOpen(panel)) setPanel(panel, true)
2428
+ // an id INSIDE a closed panel (an old decision's `#d7`, now the answer card in its question):
2429
+ // open the panels around it, or the jump lands on nothing
2430
+ for (
2431
+ let content = element.closest("ui-accordion > ui-content");
2432
+ content;
2433
+ content = content.parentElement.parentElement?.closest("ui-accordion > ui-content")
2434
+ ) {
2435
+ const accordion = content.parentElement
2436
+ const contents = Array.from(accordion.children).filter((child) => child.localName === "ui-content")
2437
+ const title = titlesOf(accordion)[contents.indexOf(content)]
2438
+ if (!title || isPanelOpen(title)) continue
2439
+ setPanel(title, true)
2440
+ unfolded = true
1420
2441
  }
1421
- return unfolded || shown;
2442
+ return unfolded || shown
1422
2443
  }
1423
- __name(reveal, "reveal");
1424
2444
  }
1425
- __name(wireFolds, "wireFolds");
2445
+
2446
+ /**
2447
+ * Keep every fold as it is as the page goes (`pagehide`), for a LIVE reload to put back (`takeKeptFolds()`):
2448
+ * `{ [id]: open }` in `sessionStorage`, of every section, folding heading, epic page block and ITEM with an id.
2449
+ * - why: the saved folds (`spell-folds:<path>`) hold only what the reader folded or unfolded himself,
2450
+ * never an item nor what a link opened; a reload for new code must come back as he left it (I23 of `epic-engine`)
2451
+ * - written on every `pagehide`; read only after a live reload:
2452
+ * a reload the reader asks for starts from the saved folds, as before
2453
+ * - storage blocked: kept for this page only (`PrefStore`), so a live reload starts from the saved folds
2454
+ */
1426
2455
  function keepFoldsForReload(main) {
1427
2456
  addEventListener("pagehide", () => {
1428
- const folds = {};
2457
+ const folds = {}
1429
2458
  for (const block of main.querySelectorAll(`ui-section[collapsible][id], ${EPIC_OPENERS}`))
1430
- if (block.id) folds[block.id] = !isCollapsed(block);
2459
+ if (block.id) folds[block.id] = !isCollapsed(block)
1431
2460
  for (const heading of main.querySelectorAll(".spell-foldable[id]"))
1432
- folds[heading.id] = !heading.parentElement.parentElement.classList.contains("spell-folded");
1433
- PrefStore.setAt(`${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`, folds, "session");
1434
- });
2461
+ folds[heading.id] = !heading.parentElement.parentElement.classList.contains("spell-folded")
2462
+ // storage blocked: kept for this page only, so a live reload starts from the saved folds
2463
+ PrefStore.setAt(`${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`, folds, "session")
2464
+ })
1435
2465
  }
1436
- __name(keepFoldsForReload, "keepFoldsForReload");
2466
+
2467
+ /**
2468
+ * The folds `keepFoldsForReload()` kept as the page last went, when this load is a LIVE reload (`live`);
2469
+ * else `undefined`. Forgets them either way.
2470
+ */
1437
2471
  function takeKeptFolds(live) {
1438
- const key = `${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`;
1439
- const kept = live ? PrefStore.getAt(key, "session") : void 0;
1440
- PrefStore.setAt(key, void 0, "session");
1441
- return kept && typeof kept === "object" ? kept : void 0;
2472
+ const key = `${KEPT_FOLDS_KEY_PREFIX}${location.pathname}`
2473
+ const kept = live ? PrefStore.getAt(key, "session") : undefined
2474
+ PrefStore.setAt(key, undefined, "session")
2475
+ return kept && typeof kept === "object" ? kept : undefined
1442
2476
  }
1443
- __name(takeKeptFolds, "takeKeptFolds");
2477
+
2478
+ /**
2479
+ * HEADINGS: fold or unfold `section`:
2480
+ * its class, its chevron (down / right) and the chevron's state for screen readers.
2481
+ */
1444
2482
  function setFolded(section, folded) {
1445
- section.classList.toggle("spell-folded", folded);
1446
- const button = section.querySelector(":scope > ui-sticky > * > ui-button.spell-fold");
1447
- if (!button) return;
1448
- button.setAttribute("icon", folded ? "chevron right" : "chevron down");
1449
- button.setAttribute("aria-label", folded ? "Unfold section" : "Fold section");
1450
- button.setAttribute("aria-expanded", String(!folded));
1451
- }
1452
- __name(setFolded, "setFolded");
1453
- var stickyObserver;
2483
+ section.classList.toggle("spell-folded", folded)
2484
+ const button = section.querySelector(":scope > ui-sticky > * > ui-button.spell-fold")
2485
+ if (!button) return
2486
+ button.setAttribute("icon", folded ? "chevron right" : "chevron down")
2487
+ button.setAttribute("aria-label", folded ? "Unfold section" : "Fold section")
2488
+ button.setAttribute("aria-expanded", String(!folded))
2489
+ }
2490
+
2491
+ ////////////////
2492
+ // ## Sticky headers
2493
+ ////////////////
2494
+
2495
+ /** `trackStickyHeights()`'s current observer: disconnected when it runs again. */
2496
+ let stickyObserver
2497
+
2498
+ /**
2499
+ * Where each sticky title sticks: below the fixed site header (`siteHeaderHeight()`), then whatever sticks above
2500
+ * every section -- the page header (`ui-sticky.spell-h1`) and the CHEATSHEET's filter bar (`.spell-filter`), whose
2501
+ * heights are `--spell-top` on `main`.
2502
+ * - SECTIONS: sets each top-level `<ui-section>`'s `offset`; nested ones stack themselves below their parents'.
2503
+ * Writes `--spell-section-top` (where its title sticks) and `--spell-stack` (the bottom of its stack of stuck
2504
+ * titles) on every section, which `scroll-margin-top` reads (`spell-doc.css`): a section lands at its sticky
2505
+ * line, anything in it below its stack.
2506
+ * - HEADINGS: h2s below the bar, h3s just below their section's h2; sets each sticky's `offset`, and
2507
+ * `--spell-h2-h` / `--spell-h3-h` on the sections, which the headings' `scroll-margin-top` reads
2508
+ * - also sticks the page header just below the site header (its `offset`), and writes
2509
+ * the page header's height as `--spell-head-h` on `main` (the filter bar sticks below it)
2510
+ * - NOTE: the `offset`s are from the VIEWPORT top, so they include the site header; the CSS variables (and so
2511
+ * every `scroll-margin-top`) leave it OUT, as the browser adds it (see "Landing" in the header)
2512
+ * - re-measured whenever a title changes size (fonts loading, the window narrowing and titles wrapping)
2513
+ * - returns `{ measure, offsetFor }`: `offsetFor(target)` is how far below the viewport top it should land
2514
+ * - callable again (a page updated in place): disconnects the previous call's observer (`stickyObserver`)
2515
+ */
1454
2516
  function trackStickyHeights(main, outline) {
1455
- const head = main.querySelector(":scope > ui-sticky.spell-h1");
1456
- const bar = main.querySelector(".spell-filter, nav.spell-toolbar-alone");
1457
- const h2Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h2"));
1458
- const h3Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h3"));
1459
- const sections = outline.sections ? Array.from(main.querySelectorAll("ui-section")) : [];
1460
- stickyObserver?.disconnect();
1461
- const observer = new ResizeObserver(() => measure());
1462
- stickyObserver = observer;
2517
+ const head = main.querySelector(":scope > ui-sticky.spell-h1")
2518
+ // the filter bar, or a page toolbar sticking by itself (`buildPageToolbar()`): never both
2519
+ const bar = main.querySelector(".spell-filter, nav.spell-toolbar-alone")
2520
+ const h2Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h2"))
2521
+ const h3Stickies = outline.sections ? [] : Array.from(main.querySelectorAll("ui-sticky.spell-h3"))
2522
+ const sections = outline.sections ? Array.from(main.querySelectorAll("ui-section")) : []
2523
+ // called again after an in-place update: the previous call's observer stops first
2524
+ stickyObserver?.disconnect()
2525
+ const observer = new ResizeObserver(() => measure())
2526
+ stickyObserver = observer
1463
2527
  for (const sticky of [head, ...h2Stickies, ...h3Stickies]) {
1464
- const heading = sticky?.firstElementChild;
1465
- if (heading) observer.observe(heading);
2528
+ const heading = sticky?.firstElementChild
2529
+ if (heading) observer.observe(heading)
1466
2530
  }
1467
- if (bar) observer.observe(bar);
1468
- measure();
1469
- return { measure, offsetFor };
2531
+ if (bar) observer.observe(bar)
2532
+ measure()
2533
+ return { measure, offsetFor }
2534
+
2535
+ /** The site header and what sticks above the sections; then each section's (heading's) sticky line. */
1470
2536
  function measure() {
1471
- const header = siteHeaderHeight();
1472
- const headHeight = head ? heightOf(head) : 0;
1473
- const top = Math.round(headHeight + (bar ? bar.getBoundingClientRect().height : 0));
1474
- setPixels(main, "--spell-head-h", headHeight);
1475
- setPixels(main, "--spell-top", top);
1476
- if (head) setOffset(head, header);
1477
- if (outline.sections) measureSections(header, top);
1478
- else measureHeadings(header, top);
1479
- }
1480
- __name(measure, "measure");
2537
+ const header = siteHeaderHeight()
2538
+ const headHeight = head ? heightOf(head) : 0
2539
+ const top = Math.round(headHeight + (bar ? bar.getBoundingClientRect().height : 0))
2540
+ setPixels(main, "--spell-head-h", headHeight)
2541
+ setPixels(main, "--spell-top", top)
2542
+ if (head) setOffset(head, header)
2543
+ if (outline.sections) measureSections(header, top)
2544
+ else measureHeadings(header, top)
2545
+ }
2546
+
2547
+ /**
2548
+ * SECTIONS: top-level `offset`s, and each section's sticky line and stack bottom, parents first.
2549
+ * - `header`: the site header's height; `top`: what sticks below it, above every section
2550
+ */
1481
2551
  function measureSections(header, top) {
1482
- const bottoms = /* @__PURE__ */ new Map();
2552
+ const bottoms = new Map()
1483
2553
  for (const section of sections) {
1484
- const parent = section.parentElement?.closest("ui-section");
1485
- const line = parent ? bottoms.get(parent) ?? top : top;
1486
- const title = titleOf(section);
1487
- if (title) observer.observe(title);
1488
- const height = title && section.hasAttribute("sticky") ? title.getBoundingClientRect().height : 0;
1489
- bottoms.set(section, line + height);
1490
- setPixels(section, "--spell-section-top", line);
1491
- setPixels(section, "--spell-stack", line + height);
1492
- if (!parent) setOffset(section, header + top);
2554
+ const parent = section.parentElement?.closest("ui-section")
2555
+ const line = parent ? (bottoms.get(parent) ?? top) : top
2556
+ const title = titleOf(section)
2557
+ // a title renders once UI has loaded: observe it when it's there (observing twice is a no-op)
2558
+ if (title) observer.observe(title)
2559
+ const height = title && section.hasAttribute("sticky") ? title.getBoundingClientRect().height : 0
2560
+ bottoms.set(section, line + height)
2561
+ setPixels(section, "--spell-section-top", line)
2562
+ setPixels(section, "--spell-stack", line + height)
2563
+ if (!parent) setOffset(section, header + top)
1493
2564
  }
1494
2565
  }
1495
- __name(measureSections, "measureSections");
2566
+
2567
+ /** HEADINGS: the h2 / h3 stickies' `offset`s and heights. */
1496
2568
  function measureHeadings(header, top) {
1497
2569
  for (const sticky of h2Stickies) {
1498
- sticky.parentElement.style.setProperty("--spell-h2-h", `${heightOf(sticky)}px`);
1499
- setOffset(sticky, header + top);
2570
+ sticky.parentElement.style.setProperty("--spell-h2-h", `${heightOf(sticky)}px`)
2571
+ setOffset(sticky, header + top)
1500
2572
  }
1501
2573
  for (const sticky of h3Stickies) {
1502
- sticky.parentElement.style.setProperty("--spell-h3-h", `${heightOf(sticky)}px`);
1503
- setOffset(sticky, header + top + h2HeightAbove(sticky));
2574
+ sticky.parentElement.style.setProperty("--spell-h3-h", `${heightOf(sticky)}px`)
2575
+ setOffset(sticky, header + top + h2HeightAbove(sticky))
1504
2576
  }
1505
2577
  }
1506
- __name(measureHeadings, "measureHeadings");
2578
+
2579
+ /** How far below the viewport top a target lands (`landingLine()`). */
1507
2580
  function offsetFor(target) {
1508
- return landingLine(target);
2581
+ return landingLine(target)
1509
2582
  }
1510
- __name(offsetFor, "offsetFor");
1511
2583
  }
1512
- __name(trackStickyHeights, "trackStickyHeights");
2584
+
2585
+ /**
2586
+ * How far below the viewport top `target` lands, px:
2587
+ * - inside an epic page (`<epic-page>`): where the titles stuck over it end, the `--epic-stack` it inherits (a block's
2588
+ * own title sticks there; anything else lands `EPIC_LAND_GAP` below), and below its item's line when it's in an
2589
+ * item's details (the line sticks there too)
2590
+ * - else: the site header, then its own `scroll-margin-top` (CSS derives it from the sections)
2591
+ */
1513
2592
  function landingLine(target) {
1514
- const stack = target.closest("epic-page") ? parseFloat(getComputedStyle(target).getPropertyValue("--epic-stack")) : NaN;
1515
- if (Number.isNaN(stack)) return siteHeaderHeight() + (parseFloat(getComputedStyle(target).scrollMarginTop) || 0);
1516
- if (target.matches(EPIC_OPENERS)) return stack;
1517
- const item = target.parentElement?.closest("epic-item");
1518
- const line = item?.shadowRoot?.querySelector('[part~="line"]');
1519
- return stack + EPIC_LAND_GAP + (line ? line.getBoundingClientRect().height : 0);
1520
- }
1521
- __name(landingLine, "landingLine");
2593
+ const stack = target.closest("epic-page")
2594
+ ? parseFloat(getComputedStyle(target).getPropertyValue("--epic-stack"))
2595
+ : NaN
2596
+ if (Number.isNaN(stack)) return siteHeaderHeight() + (parseFloat(getComputedStyle(target).scrollMarginTop) || 0)
2597
+ if (target.matches(EPIC_OPENERS)) return stack
2598
+ const item = target.parentElement?.closest("epic-item")
2599
+ const line = item?.shadowRoot?.querySelector('[part~="line"]')
2600
+ return stack + EPIC_LAND_GAP + (line ? line.getBoundingClientRect().height : 0)
2601
+ }
2602
+
2603
+ /**
2604
+ * Height of the fixed `<spell-site-header>` on top of the page, px: its `--spell-site-header-height` on `:root`.
2605
+ * - 0 when the page has none (or it isn't defined yet): then everything sticks at the viewport top, as before
2606
+ */
1522
2607
  function siteHeaderHeight() {
1523
- const value = getComputedStyle(document.documentElement).getPropertyValue("--spell-site-header-height");
1524
- return parseFloat(value) || 0;
2608
+ const value = getComputedStyle(document.documentElement).getPropertyValue("--spell-site-header-height")
2609
+ return parseFloat(value) || 0
1525
2610
  }
1526
- __name(siteHeaderHeight, "siteHeaderHeight");
2611
+
2612
+ /** Write `pixels` as custom property `name` on `element`, unless it's already that. */
1527
2613
  function setPixels(element, name, pixels) {
1528
- const value = `${Math.round(pixels * 100) / 100}px`;
1529
- if (element.style.getPropertyValue(name) !== value) element.style.setProperty(name, value);
2614
+ const value = `${Math.round(pixels * 100) / 100}px`
2615
+ if (element.style.getPropertyValue(name) !== value) element.style.setProperty(name, value)
1530
2616
  }
1531
- __name(setPixels, "setPixels");
2617
+
2618
+ /**
2619
+ * A sticky's (top-level section's) `offset`, in whole pixels;
2620
+ * re-setting the same value would restart its observer for nothing.
2621
+ */
1532
2622
  function setOffset(sticky, offset) {
1533
- const text = String(Math.round(offset));
1534
- if (sticky.getAttribute("offset") !== text) sticky.setAttribute("offset", text);
2623
+ const text = String(Math.round(offset))
2624
+ if (sticky.getAttribute("offset") !== text) sticky.setAttribute("offset", text)
1535
2625
  }
1536
- __name(setOffset, "setOffset");
2626
+
2627
+ /** Height of a sticky's heading (the sticky host is `display: contents`, so measure what it holds). */
1537
2628
  function heightOf(sticky) {
1538
- return sticky.firstElementChild?.getBoundingClientRect().height ?? 0;
2629
+ return sticky.firstElementChild?.getBoundingClientRect().height ?? 0
1539
2630
  }
1540
- __name(heightOf, "heightOf");
2631
+
2632
+ /** Height of the h2 whose section holds `sticky`'s section: where an h3 sticks. */
1541
2633
  function h2HeightAbove(sticky) {
1542
2634
  for (let section = sticky.parentElement?.parentElement; section; section = section.parentElement) {
1543
- const h2 = section.querySelector(":scope > ui-sticky.spell-h2");
1544
- if (h2) return heightOf(h2);
2635
+ const h2 = section.querySelector(":scope > ui-sticky.spell-h2")
2636
+ if (h2) return heightOf(h2)
1545
2637
  }
1546
- return 0;
2638
+ return 0
1547
2639
  }
1548
- __name(h2HeightAbove, "h2HeightAbove");
2640
+
2641
+ ////////////////
2642
+ // ## Anchors
2643
+ ////////////////
2644
+
2645
+ /**
2646
+ * Same-page links to anything with an id in `main` (a section, a heading, a plan item) jump there ourselves, and
2647
+ * the toolbar follows AT ONCE.
2648
+ * - a section lands with its title at its sticky line; anything else below every stuck title above it (both by
2649
+ * the site header plus their `scroll-margin-top`, "Landing" in the header): the browser's own jump would add
2650
+ * the stuck titles' scroll padding (they reserve it) on top
2651
+ * - HEADINGS: a STICKY heading's jump goes to its section: a stuck heading already "is" at the top, so the
2652
+ * browser's own jump to it does nothing -- e.g. the toolbar's entry of the section you're reading
2653
+ * - every jump lands through Spell UI's `HashLanding`, by this page's rules (its `use()`, here):
2654
+ * folded sections around the target unfold first, and a target that is a folded item opens (`folds.reveal()`);
2655
+ * an unfolded `<ui-section>` draws on the next frames, so the jump lands once it has, and once more as the page
2656
+ * settles (`SETTLE_MS` twice) unless the reader moved meanwhile
2657
+ * - the page lands its hashes itself: a `<ui-toc>` or `<ui-docs-api>` on it leaves them to it
2658
+ * - the target's entry becomes the current one even when the page can't scroll it up to its line (the last
2659
+ * short sections), until the user scrolls on (`follow.pin()`)
2660
+ * - `hashchange` / `popstate` (back, forward, a typed hash) jump the same way
2661
+ * - in a frame (VS Code's view), the parent's `{ spell: "go", hash }` too: the view showing the page it already
2662
+ * shows, at an id (`packages/vscode/src/DocView.ts`); a history entry, as a click's
2663
+ * - a jump that moves the address says so (`spell-doc:scrolled-to`): `pushState()` fires no `hashchange`
2664
+ * - returns `{ jump, go, canGo }`:
2665
+ * - `jump(id, { unfoldTarget })`: `unfoldTarget: false` unfolds only what's AROUND a folded target section
2666
+ * (`land()`: a reload lands on the section being read as it was, folded or not)
2667
+ * - `go(id)`: as a click on a link to `#id` (a history entry, then the jump), resolving once landed;
2668
+ * `canGo(id)`: is there one to land on
2669
+ */
1549
2670
  function wireAnchors(main, outline, sticky, follow, folds) {
1550
2671
  const landing = HashLanding.forDocument(document).use({
1551
2672
  // the page has drawn already (`start()`)
1552
- whenReady: /* @__PURE__ */ __name(() => Promise.resolve(), "whenReady"),
1553
- reveal: /* @__PURE__ */ __name((target, { opensTarget }) => folds.reveal(target, { self: opensTarget }), "reveal"),
2673
+ whenReady: () => Promise.resolve(),
2674
+ reveal: (target, { opensTarget }) => folds.reveal(target, { self: opensTarget }),
1554
2675
  revealFrames: UNFOLD_FRAMES,
1555
- lineFor: /* @__PURE__ */ __name((target) => sticky.offsetFor(target), "lineFor"),
1556
- topOf: /* @__PURE__ */ __name((target) => topOf(boxOf(target)), "topOf"),
2676
+ lineFor: (target) => sticky.offsetFor(target),
2677
+ topOf: (target) => topOf(boxOf(target)),
1557
2678
  // the target's entry is the current one, even where the page can't scroll it up to its line
1558
- onLanded: /* @__PURE__ */ __name((target) => {
1559
- const entry = outline.entryOf(target);
1560
- if (entry) follow?.pin(entry);
1561
- }, "onLanded"),
1562
- settleSeconds: SETTLE_MS * 2 / 1e3
1563
- });
2679
+ onLanded: (target) => {
2680
+ const entry = outline.entryOf(target)
2681
+ if (entry) follow?.pin(entry)
2682
+ },
2683
+ settleSeconds: (SETTLE_MS * 2) / 1000
2684
+ })
1564
2685
  document.addEventListener("click", (event) => {
1565
- if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey) return;
1566
- const id = targetIdOf(event);
1567
- if (!id || !(targetIn(id) || hostHolding(main, id))) return;
1568
- event.preventDefault();
1569
- go(id);
1570
- });
1571
- addEventListener("popstate", () => jump(hashId()));
1572
- addEventListener("hashchange", () => jump(hashId()));
1573
- if (window.parent !== window) addEventListener("message", onMessage);
1574
- return { jump, go, canGo: /* @__PURE__ */ __name((id) => !!(targetIn(id) || hostHolding(main, id)), "canGo") };
2686
+ if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey) return
2687
+ const id = targetIdOf(event)
2688
+ if (!id || !(targetIn(id) || hostHolding(main, id))) return
2689
+ event.preventDefault()
2690
+ go(id)
2691
+ })
2692
+ addEventListener("popstate", () => jump(hashId()))
2693
+ addEventListener("hashchange", () => jump(hashId()))
2694
+ if (window.parent !== window) addEventListener("message", onMessage)
2695
+ return { jump, go, canGo: (id) => !!(targetIn(id) || hostHolding(main, id)) }
2696
+
2697
+ /**
2698
+ * Follow a same-page link to `id`: a history entry (unless the address is there already), then the jump.
2699
+ * - Resolves once it has landed (`jump()`).
2700
+ */
1575
2701
  function go(id) {
1576
2702
  if (hashId() !== id) {
1577
- history.pushState(null, "", `#${id}`);
1578
- dispatchEvent(new Event("spell-doc:scrolled-to"));
2703
+ history.pushState(null, "", `#${id}`)
2704
+ dispatchEvent(new Event("spell-doc:scrolled-to"))
1579
2705
  }
1580
- return jump(id);
2706
+ return jump(id)
1581
2707
  }
1582
- __name(go, "go");
2708
+
2709
+ /** The frame's parent posted `{ spell: "go", hash }`: go there, as a link to it would. */
1583
2710
  function onMessage(event) {
1584
- const data = event.data;
1585
- if (event.source !== window.parent || data?.spell !== "go" || typeof data.hash !== "string") return;
1586
- const id = addressedId(TocIndex.decode(data.hash.replace(/^#/, "")));
1587
- if (targetIn(id) || hostHolding(main, id)) go(id);
2711
+ const data = event.data
2712
+ if (event.source !== window.parent || data?.spell !== "go" || typeof data.hash !== "string") return
2713
+ const id = addressedId(TocIndex.decode(data.hash.replace(/^#/, "")))
2714
+ if (targetIn(id) || hostHolding(main, id)) go(id)
1588
2715
  }
1589
- __name(onMessage, "onMessage");
2716
+
2717
+ /**
2718
+ * Scroll to `id` and make its entry the current one; once what it unfolded has drawn.
2719
+ * Returns a promise that settles once it has landed (or found nothing to land on).
2720
+ * - `id` inside a body not loaded yet (a split epic page's part: an Overview `h4`, an old `#d7` answer card):
2721
+ * its host loads the body first (`hostHolding()`, `load()`), then the jump goes on (caveat C8 of `claude-design`)
2722
+ */
1590
2723
  function jump(id, { unfoldTarget = true } = {}) {
1591
- const target = targetIn(id);
2724
+ const target = targetIn(id)
1592
2725
  if (!target) {
1593
- const host = hostHolding(main, id);
1594
- if (!host?.load) return Promise.resolve();
2726
+ const host = hostHolding(main, id)
2727
+ if (!host?.load) return Promise.resolve()
1595
2728
  return host.load().then(
1596
- () => targetIn(id) ? jump(id, { unfoldTarget }) : void 0,
1597
- () => void 0
1598
- );
2729
+ () => (targetIn(id) ? jump(id, { unfoldTarget }) : undefined),
2730
+ () => undefined
2731
+ )
1599
2732
  }
1600
- const root = document.documentElement;
1601
- root.setAttribute("data-spell-jumping", "");
1602
- setTimeout(() => root.removeAttribute("data-spell-jumping"), SETTLE_MS);
1603
- return landing.land(target, { opensTarget: unfoldTarget }).then(() => void 0);
2733
+ // what a jump unfolds opens at once, without the fold animation, so the page gets there quickly (Owen,
2734
+ // 2026-10-04): `spell-doc.css` zeroes `--ui-section-duration` under `data-spell-jumping`
2735
+ const root = document.documentElement
2736
+ root.setAttribute("data-spell-jumping", "")
2737
+ setTimeout(() => root.removeAttribute("data-spell-jumping"), SETTLE_MS)
2738
+ return landing.land(target, { opensTarget: unfoldTarget }).then(() => undefined)
1604
2739
  }
1605
- __name(jump, "jump");
2740
+
2741
+ /** The `id` a click goes to: a same-page `#hash` link's. */
1606
2742
  function targetIdOf(event) {
1607
2743
  for (const node of event.composedPath()) {
1608
- if (!(node instanceof Element)) continue;
1609
- const href = node.getAttribute("href");
2744
+ if (!(node instanceof Element)) continue
2745
+ const href = node.getAttribute("href")
1610
2746
  if (node.localName === "a" && href?.startsWith("#") && href.length > 1)
1611
- return addressedId(decodeURIComponent(href.slice(1)));
2747
+ return addressedId(decodeURIComponent(href.slice(1)))
1612
2748
  }
1613
- return void 0;
2749
+ return undefined
1614
2750
  }
1615
- __name(targetIdOf, "targetIdOf");
2751
+
2752
+ /** The element with `id` in `main`, if any. */
1616
2753
  function targetIn(id) {
1617
- const element = id ? document.getElementById(id) : null;
1618
- return element && main.contains(element) ? element : null;
2754
+ const element = id ? document.getElementById(id) : null
2755
+ return element && main.contains(element) ? element : null
1619
2756
  }
1620
- __name(targetIn, "targetIn");
1621
2757
  }
1622
- __name(wireAnchors, "wireAnchors");
2758
+
2759
+ /**
2760
+ * The box a jump to `target` measures: its own; a HEADINGS sticky heading's SECTION (it can't be measured where it is
2761
+ * while stuck). Where it lands is `offsetFor()`'s: the site header and its `scroll-margin-top`.
2762
+ */
1623
2763
  function boxOf(target) {
1624
- return target.parentElement?.localName === "ui-sticky" ? target.parentElement.parentElement : target;
2764
+ return target.parentElement?.localName === "ui-sticky" ? target.parentElement.parentElement : target
1625
2765
  }
1626
- __name(boxOf, "boxOf");
2766
+
2767
+ /**
2768
+ * Viewport top of `element`'s box;
2769
+ * for a host with no box of its own (`display: contents`, e.g. `<ui-item>`), of what it holds.
2770
+ */
1627
2771
  function topOf(element) {
1628
- if (element.getClientRects().length) return element.getBoundingClientRect().top;
1629
- const range = document.createRange();
1630
- range.selectNodeContents(element);
1631
- return range.getBoundingClientRect().top;
2772
+ if (element.getClientRects().length) return element.getBoundingClientRect().top
2773
+ const range = document.createRange()
2774
+ range.selectNodeContents(element)
2775
+ return range.getBoundingClientRect().top
1632
2776
  }
1633
- __name(topOf, "topOf");
2777
+
2778
+ ////////////////
2779
+ // ## Short addresses
2780
+ ////////////////
2781
+
2782
+ /**
2783
+ * Links to a SHORT ADDRESS (epic `epic-workflow` P15, J32), `<a href="SAGA:/drawable-spell/python-target#T1">`,
2784
+ * become links to the page and its `#id` (`EpicAddress`), so a page may link either way:
2785
+ * - the epic or saga page, from the checkout's root (`PageTargets.rootUrlOf()`), opening in that epic's tab (as every
2786
+ * link to an epic page) unless the link names one; the page there lands on the id, loading its part first
2787
+ * - into THIS page: a `#id` link, which `wireAnchors()` lands on
2788
+ * - every such link as the page starts, and one added later as it's clicked (before the anchors see the click)
2789
+ * - a malformed address, or no root to build from: left as it is
2790
+ */
1634
2791
  function wireAddresses() {
1635
- const root = PageTargets.rootUrlOf(document);
1636
- if (!root) return;
1637
- const here = EpicAddress.pageOf(location.href, root);
1638
- for (const link of document.querySelectorAll("a[href]")) rewrite(link);
2792
+ const root = PageTargets.rootUrlOf(document)
2793
+ if (!root) return
2794
+ const here = EpicAddress.pageOf(location.href, root)
2795
+ for (const link of document.querySelectorAll("a[href]")) rewrite(link)
1639
2796
  document.addEventListener(
1640
2797
  "click",
1641
2798
  (event) => {
1642
2799
  for (const node of event.composedPath())
1643
- if (node instanceof Element && node.localName === "a" && node.hasAttribute("href")) return rewrite(node);
2800
+ if (node instanceof Element && node.localName === "a" && node.hasAttribute("href")) return rewrite(node)
1644
2801
  },
1645
2802
  { capture: true }
1646
- );
2803
+ )
2804
+
2805
+ /** `link`'s address, if it has one, as the page and `#id` it means. */
1647
2806
  function rewrite(link) {
1648
- const href = link.getAttribute("href");
1649
- if (!EpicAddress.isAddress(href)) return;
1650
- let address;
2807
+ const href = link.getAttribute("href")
2808
+ if (!EpicAddress.isAddress(href)) return
2809
+ let address
1651
2810
  try {
1652
- address = EpicAddress.parse(href);
2811
+ address = EpicAddress.parse(href)
1653
2812
  } catch {
1654
- return;
2813
+ return
1655
2814
  }
1656
- const samePage = address.page === here;
1657
- link.setAttribute("href", samePage ? `#${address.id ?? ""}` : address.hrefFrom(root));
1658
- if (!samePage && !link.hasAttribute("target")) link.setAttribute("target", address.epic ?? `saga-${address.saga}`);
1659
- link.setAttribute("data-spell-address", href);
2815
+ const samePage = address.page === here
2816
+ link.setAttribute("href", samePage ? `#${address.id ?? ""}` : address.hrefFrom(root))
2817
+ if (!samePage && !link.hasAttribute("target")) link.setAttribute("target", address.epic ?? `saga-${address.saga}`)
2818
+ link.setAttribute("data-spell-address", href)
1660
2819
  }
1661
- __name(rewrite, "rewrite");
1662
2820
  }
1663
- __name(wireAddresses, "wireAddresses");
2821
+
2822
+ // ## Jump to an item (Cmd / Ctrl + K): `wireJumpKey()`, in `spell-doc-toolbar.js`
2823
+
2824
+ ////////////////
2825
+ // ## Paging
2826
+ ////////////////
2827
+
2828
+ /**
2829
+ * Page Down / Page Up / Space / Shift+Space page the document ourselves, so a page always continues just below the
2830
+ * stuck titles.
2831
+ * - why: the browser pages by the `scroll-padding-top` of where it STARTS (`StickyWatch`'s stuck edge), but paging
2832
+ * down can stick more titles (entering a nested section), which then cover the old bottom lines
2833
+ * - down: the old viewport bottom lands just below the lowest title stuck at the NEW position (`stuckBottom()`,
2834
+ * measured there: a sticky box's position is computed in layout, so an instant scroll and a read find it);
2835
+ * up: the old first line below the stuck titles lands at the viewport bottom
2836
+ * - measured with instant scrolls, then put back and scrolled there for real (smooth, unless reduced motion):
2837
+ * nothing paints in between
2838
+ * - left to the browser:
2839
+ * modifier keys, a key in a field, button, link or a scrolling box of its own (a wide `pre`), an open dialog
2840
+ */
1664
2841
  function wirePaging(main) {
1665
- const keys = { PageDown: 1, PageUp: -1, " ": 1 };
2842
+ const keys = { PageDown: 1, PageUp: -1, " ": 1 }
1666
2843
  document.addEventListener("keydown", (event) => {
1667
- let direction = keys[event.key];
1668
- if (!direction || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
1669
- if (event.key === " " && event.shiftKey) direction = -1;
1670
- if (document.querySelector("dialog[open]") || !pageOwnsKey(event, event.key === " ")) return;
1671
- event.preventDefault();
1672
- const from = scrollY;
1673
- const to = direction > 0 ? pageDownTo() : pageUpTo();
1674
- if (Math.abs(to - from) < 1) return;
1675
- const smooth = !matchMedia("(prefers-reduced-motion: reduce)").matches;
1676
- scrollTo({ top: from, behavior: "instant" });
1677
- scrollTo({ top: to, behavior: smooth ? "smooth" : "instant" });
1678
- });
2844
+ let direction = keys[event.key]
2845
+ if (!direction || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return
2846
+ if (event.key === " " && event.shiftKey) direction = -1
2847
+ if (document.querySelector("dialog[open]") || !pageOwnsKey(event, event.key === " ")) return
2848
+ event.preventDefault()
2849
+ const from = scrollY
2850
+ const to = direction > 0 ? pageDownTo() : pageUpTo()
2851
+ if (Math.abs(to - from) < 1) return
2852
+ const smooth = !matchMedia("(prefers-reduced-motion: reduce)").matches
2853
+ scrollTo({ top: from, behavior: "instant" })
2854
+ scrollTo({ top: to, behavior: smooth ? "smooth" : "instant" })
2855
+ })
2856
+
2857
+ /**
2858
+ * Where Page Down goes: the old viewport bottom just below the titles stuck THERE (settles in a few tries).
2859
+ * - the furthest try that leaves the old bottom uncovered: where the old bottom IS a title, the two positions
2860
+ * either side of its sticking alternate, and the nearer one shows it below the stack instead of stuck on it
2861
+ */
1679
2862
  function pageDownTo() {
1680
- const bottom = scrollY + innerHeight;
1681
- const max = document.documentElement.scrollHeight - innerHeight;
1682
- let top = scrollY;
1683
- let best = top;
2863
+ const bottom = scrollY + innerHeight
2864
+ const max = document.documentElement.scrollHeight - innerHeight
2865
+ let top = scrollY
2866
+ let best = top
1684
2867
  for (let tries = 0; tries < 4; tries++) {
1685
- const next = clamp(bottom - stuckBottom(main), 0, max);
1686
- if (Math.abs(next - top) < 1) break;
1687
- top = next;
1688
- scrollTo({ top, behavior: "instant" });
1689
- if (bottom - top >= stuckBottom(main) - 1) best = Math.max(best, top);
2868
+ const next = clamp(bottom - stuckBottom(main), 0, max)
2869
+ if (Math.abs(next - top) < 1) break
2870
+ top = next
2871
+ scrollTo({ top, behavior: "instant" })
2872
+ if (bottom - top >= stuckBottom(main) - 1) best = Math.max(best, top)
1690
2873
  }
1691
- return best;
2874
+ return best
1692
2875
  }
1693
- __name(pageDownTo, "pageDownTo");
2876
+
2877
+ /** Where Page Up goes: the first line below the stuck titles to the viewport bottom. */
1694
2878
  function pageUpTo() {
1695
- return Math.max(0, scrollY + stuckBottom(main) - innerHeight);
2879
+ return Math.max(0, scrollY + stuckBottom(main) - innerHeight)
1696
2880
  }
1697
- __name(pageUpTo, "pageUpTo");
1698
2881
  }
1699
- __name(wirePaging, "wirePaging");
2882
+
2883
+ /**
2884
+ * Whether a paging key belongs to the page: not to a field or a box that scrolls on its own;
2885
+ * Space not to a control either (it presses a button, follows a link).
2886
+ */
1700
2887
  function pageOwnsKey(event, space) {
1701
2888
  for (const node of event.composedPath()) {
1702
- if (!(node instanceof Element) || node === document.body || node === document.documentElement) continue;
1703
- if (node.isContentEditable || node.matches(FIELDS) || space && node.matches(CONTROLS)) return false;
1704
- const overflow = getComputedStyle(node).overflowY;
1705
- if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) return false;
2889
+ if (!(node instanceof Element) || node === document.body || node === document.documentElement) continue
2890
+ if (node.isContentEditable || node.matches(FIELDS) || (space && node.matches(CONTROLS))) return false
2891
+ const overflow = getComputedStyle(node).overflowY
2892
+ if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) return false
1706
2893
  }
1707
- return true;
2894
+ return true
1708
2895
  }
1709
- __name(pageOwnsKey, "pageOwnsKey");
1710
- var CONTROLS = "a[href], button, summary, [tabindex], ui-button, ui-checkbox, ui-title, ui-item";
2896
+
2897
+ /** What Space presses. */
2898
+ const CONTROLS = "a[href], button, summary, [tabindex], ui-button, ui-checkbox, ui-title, ui-item"
2899
+
2900
+ /**
2901
+ * The bottom of the lowest box stuck at the top now, from the viewport top: the site header, the page header, the
2902
+ * filter bar, every stuck (or being pushed out) section title or sticky heading in `main`.
2903
+ * - a sticky box is stuck when it sits at (or above: pushed out by its section's end) its computed `top`
2904
+ */
1711
2905
  function stuckBottom(main) {
1712
- let bottom = siteHeaderHeight();
1713
- const boxes = Array.from(main.querySelectorAll(".spell-filter"));
2906
+ let bottom = siteHeaderHeight()
2907
+ const boxes = Array.from(main.querySelectorAll(".spell-filter"))
2908
+ // a `<ui-sticky>` host is `display: contents`: the box that sticks is its shadow `sticky` part
1714
2909
  for (const sticky of main.querySelectorAll("ui-sticky"))
1715
- boxes.push(sticky.shadowRoot?.querySelector('[part~="sticky"]'));
1716
- for (const section of main.querySelectorAll(`ui-section[sticky], ${EPIC_FOLDS}`)) boxes.push(titleOf(section));
2910
+ boxes.push(sticky.shadowRoot?.querySelector('[part~="sticky"]'))
2911
+ for (const section of main.querySelectorAll(`ui-section[sticky], ${EPIC_FOLDS}`)) boxes.push(titleOf(section))
2912
+ // an epic page's page header and its toolbar's bar under it (the title between them scrolls away);
2913
+ // an OPEN item's line sticks below the titles (a closed one's isn't sticky: skipped)
1717
2914
  for (const page of main.querySelectorAll("epic-page"))
1718
- boxes.push(...page.shadowRoot?.querySelectorAll('[part~="header"], [part~="bar"]') ?? []);
1719
- for (const item of main.querySelectorAll("epic-item")) boxes.push(item.shadowRoot?.querySelector('[part~="line"]'));
2915
+ boxes.push(...(page.shadowRoot?.querySelectorAll('[part~="header"], [part~="bar"]') ?? []))
2916
+ for (const item of main.querySelectorAll("epic-item")) boxes.push(item.shadowRoot?.querySelector('[part~="line"]'))
1720
2917
  for (const box of boxes) {
1721
- if (!box) continue;
1722
- const style = getComputedStyle(box);
1723
- const line = parseFloat(style.top);
1724
- if (style.position !== "sticky" || Number.isNaN(line)) continue;
1725
- const rect = box.getBoundingClientRect();
1726
- if (rect.height && rect.top <= line + 1 && rect.bottom > bottom) bottom = rect.bottom;
2918
+ if (!box) continue
2919
+ const style = getComputedStyle(box)
2920
+ const line = parseFloat(style.top)
2921
+ if (style.position !== "sticky" || Number.isNaN(line)) continue
2922
+ const rect = box.getBoundingClientRect()
2923
+ if (rect.height && rect.top <= line + 1 && rect.bottom > bottom) bottom = rect.bottom
1727
2924
  }
1728
- return bottom;
2925
+ return bottom
1729
2926
  }
1730
- __name(stuckBottom, "stuckBottom");
2927
+
2928
+ /** The URL's `#hash` as an id, or ""; an old phase address as the phase's id (`addressedId()`). */
1731
2929
  function hashId() {
1732
- return addressedId(TocIndex.decode(location.hash.slice(1)));
2930
+ return addressedId(TocIndex.decode(location.hash.slice(1)))
1733
2931
  }
1734
- __name(hashId, "hashId");
2932
+
2933
+ /**
2934
+ * The id an address names on this page: `id`, unless it's an OLD phase id (`p7`, from before stable phase ids, epic
2935
+ * `epic-workflow` P15) that no element has: then the 7th phase's id (`p-epic-migrate`), so old links and bookmarks
2936
+ * still land. As `spell-epic` `PhaseIds.landing()`.
2937
+ */
1735
2938
  function addressedId(id) {
1736
- if (document.getElementById(id)) return id;
1737
- const n = /^p(\d+)$/i.exec(id)?.[1];
1738
- if (!n) return id.toLowerCase();
1739
- return document.querySelectorAll('epic-page > epic-section[kind="phases"] > epic-phase')[Number(n) - 1]?.id ?? id.toLowerCase();
2939
+ if (document.getElementById(id)) return id
2940
+ // ids in any case (`#T1` ~== `#t1`, epic `epic-workflow` J32): the page's own spelling when it has no other
2941
+ const n = /^p(\d+)$/i.exec(id)?.[1]
2942
+ if (!n) return id.toLowerCase()
2943
+ return (
2944
+ document.querySelectorAll('epic-page > epic-section[kind="phases"] > epic-phase')[Number(n) - 1]?.id ??
2945
+ id.toLowerCase()
2946
+ )
1740
2947
  }
1741
- __name(addressedId, "addressedId");
2948
+
2949
+ ////////////////
2950
+ // ## Scroll-follow
2951
+ ////////////////
2952
+
2953
+ /**
2954
+ * Mark the toolbar's entry of the section being read, and let the address follow it.
2955
+ * - "Current": the last entry (section, heading) whose top has reached its landing line (the site header and its
2956
+ * `scroll-margin-top`, plus a little); entries hidden by the filter or inside a folded section don't count
2957
+ * - the toolbar's entry of the current entry's top-level section is `selected`
2958
+ * - the ADDRESS follows too, once `followAddress()` has been called (`land()`, after the page has landed):
2959
+ * the current entry's `#id` replaces the URL's hash (`history.replaceState()`: no history entry, no jump);
2960
+ * not while a followed link is pinned (its click set the hash), and no hash above the first entry;
2961
+ * - so a reload, or VS Code restarting the view, lands on the section being read
2962
+ * - `replaceState()` fires no `hashchange`: `spell-doc:scrolled-to` on `window` tells the live client, which tells
2963
+ * VS Code's view (`liveClient.ts` `reportPlace()`)
2964
+ * - returns `{ update, pin, followAddress, rescan }`:
2965
+ * - `pin(entry)` makes it current until the page scrolls again (a link was followed)
2966
+ * - `rescan(rail)` reads the entries and the toolbar again: the page was updated in place (`rewire()`)
2967
+ */
1742
2968
  function followScroll(main, outline, rail) {
1743
- let headings = [];
1744
- let railItems = [];
1745
- let active = null;
1746
- let scheduled = false;
1747
- let pinned = null;
1748
- let addressing = false;
1749
- rescan(rail);
1750
- addEventListener("scroll", schedule, { passive: true });
1751
- addEventListener("resize", schedule, { passive: true });
1752
- return { update, pin, followAddress, rescan };
2969
+ let headings = []
2970
+ let railItems = []
2971
+ let active = null
2972
+ let scheduled = false
2973
+ let pinned = null
2974
+ let addressing = false
2975
+
2976
+ rescan(rail)
2977
+ addEventListener("scroll", schedule, { passive: true })
2978
+ addEventListener("resize", schedule, { passive: true })
2979
+ return { update, pin, followAddress, rescan }
2980
+
2981
+ /** Read the entries and the toolbar's items; a rebuilt toolbar gets its mark again on the next update. */
1753
2982
  function rescan(nextRail) {
1754
- headings = Array.from(main.querySelectorAll(outline.targets));
1755
- const items = Array.from(nextRail?.querySelectorAll("[data-rail]") ?? []);
1756
- if (items[0] !== railItems[0]) active = null;
1757
- railItems = items;
2983
+ headings = Array.from(main.querySelectorAll(outline.targets))
2984
+ const items = Array.from(nextRail?.querySelectorAll("[data-rail]") ?? [])
2985
+ if (items[0] !== railItems[0]) active = null
2986
+ railItems = items
1758
2987
  }
1759
- __name(rescan, "rescan");
2988
+
2989
+ /** From now on, the address follows the current entry. */
1760
2990
  function followAddress() {
1761
- addressing = true;
1762
- update();
2991
+ addressing = true
2992
+ update()
1763
2993
  }
1764
- __name(followAddress, "followAddress");
2994
+
2995
+ /** At most one update per frame. */
1765
2996
  function schedule() {
1766
- if (scheduled) return;
1767
- scheduled = true;
2997
+ if (scheduled) return
2998
+ scheduled = true
1768
2999
  requestAnimationFrame(() => {
1769
- scheduled = false;
1770
- update();
1771
- });
3000
+ scheduled = false
3001
+ update()
3002
+ })
1772
3003
  }
1773
- __name(schedule, "schedule");
3004
+
3005
+ /** Find the current heading and mark it; a pinned one stays while the page hasn't scrolled. */
1774
3006
  function update() {
1775
- if (pinned && Math.abs(scrollY - pinned.scrollY) < 2) return setActive(pinned.heading);
1776
- pinned = null;
3007
+ if (pinned && Math.abs(scrollY - pinned.scrollY) < 2) return setActive(pinned.heading)
3008
+ pinned = null
3009
+ // Spell UI's rule for the section being read (`TocIndex.reached()`), each heading's line its landing line:
3010
+ // a heading without a box is hidden by the filter; one replaced by an in-place update waits for `rescan()`;
3011
+ // one laid out in a folded box isn't shown
1777
3012
  const reached = TocIndex.reached(
1778
3013
  headings,
1779
3014
  (heading) => landingLine(heading) + 4,
1780
3015
  (heading) => heading.isConnected && !outline.folded(heading)
1781
- );
1782
- setActive(reached ?? headings[0]);
1783
- writeAddress(reached?.id ?? "");
3016
+ )
3017
+ setActive(reached ?? headings[0])
3018
+ writeAddress(reached?.id ?? "")
1784
3019
  }
1785
- __name(update, "update");
3020
+
3021
+ /**
3022
+ * Put `#id` in the address ("": no hash) without a history entry or a jump, and say so (`spell-doc:scrolled-to`).
3023
+ * - only once `followAddress()` was called, and only when it changes
3024
+ */
1786
3025
  function writeAddress(id) {
1787
- if (!addressing || hashId() === id) return;
1788
- history.replaceState(history.state, "", `${location.pathname}${location.search}${id ? `#${id}` : ""}`);
1789
- dispatchEvent(new Event("spell-doc:scrolled-to"));
3026
+ if (!addressing || hashId() === id) return
3027
+ history.replaceState(history.state, "", `${location.pathname}${location.search}${id ? `#${id}` : ""}`)
3028
+ dispatchEvent(new Event("spell-doc:scrolled-to"))
1790
3029
  }
1791
- __name(writeAddress, "writeAddress");
3030
+
3031
+ /** Mark the toolbar's entry of `heading`'s top-level section. */
1792
3032
  function setActive(heading) {
1793
- if (!heading || heading === active) return;
1794
- active = heading;
1795
- const group = outline.groupOf(heading);
1796
- for (const item of railItems) item.toggleAttribute("selected", item.dataset.rail === group?.id);
3033
+ if (!heading || heading === active) return
3034
+ active = heading
3035
+ const group = outline.groupOf(heading)
3036
+ for (const item of railItems) item.toggleAttribute("selected", item.dataset.rail === group?.id)
1797
3037
  }
1798
- __name(setActive, "setActive");
3038
+
3039
+ /** `heading` is current, wherever it is, until the page scrolls from here. */
1799
3040
  function pin(heading) {
1800
- pinned = { heading, scrollY };
1801
- setActive(heading);
3041
+ pinned = { heading, scrollY }
3042
+ setActive(heading)
1802
3043
  }
1803
- __name(pin, "pin");
1804
3044
  }
1805
- __name(followScroll, "followScroll");
3045
+
3046
+ ////////////////
3047
+ // ## Panels
3048
+ ////////////////
3049
+
3050
+ /** Is `title`'s panel open? */
1806
3051
  function isPanelOpen(title) {
1807
- return openIndexes(title.parentElement).includes(titlesOf(title.parentElement).indexOf(title));
3052
+ return openIndexes(title.parentElement).includes(titlesOf(title.parentElement).indexOf(title))
1808
3053
  }
1809
- __name(isPanelOpen, "isPanelOpen");
3054
+
3055
+ /** Open or close `title`'s panel, keeping the accordion's other panels as they are. */
1810
3056
  function setPanel(title, open) {
1811
- const accordion = title.parentElement;
1812
- const index = titlesOf(accordion).indexOf(title);
1813
- const indexes = new Set(openIndexes(accordion));
1814
- if (open) indexes.add(index);
1815
- else indexes.delete(index);
1816
- accordion.open = [...indexes].sort((a, b) => a - b).join(" ");
1817
- }
1818
- __name(setPanel, "setPanel");
3057
+ const accordion = title.parentElement
3058
+ const index = titlesOf(accordion).indexOf(title)
3059
+ const indexes = new Set(openIndexes(accordion))
3060
+ if (open) indexes.add(index)
3061
+ else indexes.delete(index)
3062
+ accordion.open = [...indexes].sort((a, b) => a - b).join(" ")
3063
+ }
3064
+
3065
+ /** An accordion's open panel indexes, from its `open` property (or attribute, before it upgraded). */
1819
3066
  function openIndexes(accordion) {
1820
- const text = accordion.open ?? accordion.getAttribute("open") ?? "";
1821
- return String(text).split(/[\s,]+/).filter((word) => /^\d+$/.test(word)).map(Number);
3067
+ const text = accordion.open ?? accordion.getAttribute("open") ?? ""
3068
+ return String(text)
3069
+ .split(/[\s,]+/)
3070
+ .filter((word) => /^\d+$/.test(word))
3071
+ .map(Number)
1822
3072
  }
1823
- __name(openIndexes, "openIndexes");
3073
+
3074
+ /** The `<ui-title>` children of `accordion`: one per panel, in order. */
1824
3075
  function titlesOf(accordion) {
1825
- return Array.from(accordion.children).filter((child) => child.localName === "ui-title");
3076
+ return Array.from(accordion.children).filter((child) => child.localName === "ui-title")
1826
3077
  }
1827
- __name(titlesOf, "titlesOf");
3078
+
3079
+ ////////////////
3080
+ // ## CHEATSHEET filter
3081
+ ////////////////
3082
+
3083
+ /**
3084
+ * `ui-input[data-spell-filter]` shows only the cards holding every typed word, and `ui-select[data-spell-filter-badge]`
3085
+ * only those with a `ui-label` badge of the chosen text ("" = any); sections without a visible card hide too, and
3086
+ * so do their toolbar buttons.
3087
+ * - reads values from the events' `detail`: during `ui-typed` / `ui-changed` the element's `value` is still the old one
3088
+ * - SIDE EFFECT: remembers the typed filter (not the badge) in `localStorage` (when the browser allows it), per
3089
+ * page: under the input's `data-spell-filter` value, or `FILTER_KEY_PREFIX` + the page's path
3090
+ */
1828
3091
  function wireFilter(main) {
1829
- const input = document.querySelector("ui-input[data-spell-filter]");
1830
- const badge = document.querySelector("ui-select[data-spell-filter-badge]");
1831
- if (!input && !badge) return;
1832
- const named = input?.dataset.spellFilter;
1833
- const key = `${FILTER_KEY_PREFIX}${named || location.pathname}`;
1834
- if (named) PrefStore.moveOldKey(named, key);
1835
- const cards = Array.from(main.querySelectorAll("ui-card"));
1836
- const sections = Array.from(main.querySelectorAll("section, ui-section")).filter(
1837
- (section) => section.querySelector("ui-card")
1838
- );
1839
- const empty = document.getElementById("empty");
1840
- let typed = input ? readSaved(key) : "";
1841
- let chosen = String(badge?.value ?? "");
1842
- const filterOpened = /* @__PURE__ */ new Set();
1843
- input?.addEventListener("ui-typed", onType);
1844
- input?.addEventListener("ui-changed", onType);
3092
+ const input = document.querySelector("ui-input[data-spell-filter]")
3093
+ const badge = document.querySelector("ui-select[data-spell-filter-badge]")
3094
+ if (!input && !badge) return
3095
+ const named = input?.dataset.spellFilter
3096
+ const key = `${FILTER_KEY_PREFIX}${named || location.pathname}`
3097
+ // TODO: drop the move once every browser has opened the page since epic `prefs-and-undo` P4
3098
+ if (named) PrefStore.moveOldKey(named, key)
3099
+ const cards = Array.from(main.querySelectorAll("ui-card"))
3100
+ // HEADINGS' `section`s, or `<ui-section>`s (`:host([hidden])` hides one)
3101
+ const sections = Array.from(main.querySelectorAll("section, ui-section")).filter((section) =>
3102
+ section.querySelector("ui-card")
3103
+ )
3104
+ const empty = document.getElementById("empty")
3105
+ let typed = input ? readSaved(key) : ""
3106
+ let chosen = String(badge?.value ?? "")
3107
+ /** Folded sections the filter unfolded, to fold back when it's cleared. */
3108
+ const filterOpened = new Set()
3109
+ input?.addEventListener("ui-typed", onType)
3110
+ input?.addEventListener("ui-changed", onType)
1845
3111
  badge?.addEventListener("ui-changed", (event) => {
1846
- chosen = String(event.detail?.value ?? badge.value ?? "");
1847
- apply();
1848
- });
1849
- if (typed) input.value = typed;
1850
- if (typed || chosen) apply();
3112
+ chosen = String(event.detail?.value ?? badge.value ?? "")
3113
+ apply()
3114
+ })
3115
+ if (typed) input.value = typed
3116
+ if (typed || chosen) apply()
3117
+
3118
+ /** The typed filter changed: apply and save it. */
1851
3119
  function onType(event) {
1852
- typed = String(event.detail?.value ?? input.value ?? "");
1853
- apply();
1854
- PrefStore.setAt(key, typed);
3120
+ typed = String(event.detail?.value ?? input.value ?? "")
3121
+ apply()
3122
+ PrefStore.setAt(key, typed)
1855
3123
  }
1856
- __name(onType, "onType");
3124
+
3125
+ /**
3126
+ * Hide what doesn't match.
3127
+ * - while a filter is set, a folded section holding a match unfolds
3128
+ * (not saved: sections start folded, so matches would hide in them);
3129
+ * clearing the filter folds back the ones it opened
3130
+ */
1857
3131
  function apply() {
1858
- const words = typed.toLowerCase().split(/\s+/).filter(Boolean);
1859
- const wanted = chosen.trim().toLowerCase();
1860
- let shown = 0;
3132
+ const words = typed.toLowerCase().split(/\s+/).filter(Boolean)
3133
+ const wanted = chosen.trim().toLowerCase()
3134
+ let shown = 0
1861
3135
  for (const card of cards) {
1862
- const content = card.textContent.toLowerCase();
1863
- const badges = Array.from(card.querySelectorAll("ui-label"), (label) => label.textContent.trim().toLowerCase());
1864
- card.hidden = !words.every((word) => content.includes(word)) || !!wanted && !badges.includes(wanted);
1865
- if (!card.hidden) shown++;
3136
+ const content = card.textContent.toLowerCase()
3137
+ const badges = Array.from(card.querySelectorAll("ui-label"), (label) => label.textContent.trim().toLowerCase())
3138
+ card.hidden = !words.every((word) => content.includes(word)) || (!!wanted && !badges.includes(wanted))
3139
+ if (!card.hidden) shown++
1866
3140
  }
1867
- const filtering = words.length > 0 || !!wanted;
3141
+ const filtering = words.length > 0 || !!wanted
1868
3142
  for (const section of sections) {
1869
- section.hidden = !section.querySelector("ui-card:not([hidden])");
1870
- if (section.localName !== "ui-section") continue;
3143
+ section.hidden = !section.querySelector("ui-card:not([hidden])")
3144
+ if (section.localName !== "ui-section") continue
1871
3145
  if (filtering && !section.hidden && isCollapsed(section)) {
1872
- setCollapsed(section, false);
1873
- filterOpened.add(section);
3146
+ setCollapsed(section, false)
3147
+ filterOpened.add(section)
1874
3148
  } else if (!filtering && filterOpened.has(section)) {
1875
- setCollapsed(section, true);
1876
- filterOpened.delete(section);
3149
+ setCollapsed(section, true)
3150
+ filterOpened.delete(section)
1877
3151
  }
1878
3152
  }
1879
- if (empty) empty.hidden = shown > 0;
3153
+ if (empty) empty.hidden = shown > 0
1880
3154
  for (const item of document.querySelectorAll("nav.spell-toolbar [data-rail]")) {
1881
- item.hidden = !!document.getElementById(item.dataset.rail)?.closest("[hidden]");
3155
+ item.hidden = !!document.getElementById(item.dataset.rail)?.closest("[hidden]")
1882
3156
  }
1883
3157
  }
1884
- __name(apply, "apply");
1885
3158
  }
1886
- __name(wireFilter, "wireFilter");
3159
+
3160
+ /** The filter saved under `key`, or "": none, or storage blocked. */
1887
3161
  function readSaved(key) {
1888
- const saved = PrefStore.getAt(key);
1889
- if (typeof saved === "string") return saved;
1890
- return typeof saved === "number" ? `${saved}` : "";
3162
+ const saved = PrefStore.getAt(key)
3163
+ if (typeof saved === "string") return saved
3164
+ // typed before P4 of epic `prefs-and-undo` as plain digits (`123`), it reads back as a number
3165
+ return typeof saved === "number" ? `${saved}` : ""
1891
3166
  }
1892
- __name(readSaved, "readSaved");
3167
+
3168
+ ////////////////
3169
+ // ## Page notes
3170
+ ////////////////
3171
+
3172
+ /**
3173
+ * PAGE NOTES (epic `airplane`, P3): notes written INTO a page, `<spell-notes>` / `<spell-note>`.
3174
+ * - the markup and its rules: `src/tools/PageNotes.js`
3175
+ * - each drawn as a folded card (`drawNoteCards()`),
3176
+ * its head line an `<epic-page-note-head>` (the epics pack; epic `epic-engine` P3)
3177
+ * - READ ONLY since P11: comments (below) replaced the bubbles and the Note pill that wrote them;
3178
+ * the notes already written still show, and `epic notes` still answers them
3179
+ * - every page, `file://` too; drawn again on `spell-doc:updated` (an answer changes the page)
3180
+ */
1893
3181
  function wireNotes(main) {
1894
- drawNoteCards(main);
1895
- addEventListener("spell-doc:updated", () => drawNoteCards(main));
3182
+ drawNoteCards(main)
3183
+ addEventListener("spell-doc:updated", () => drawNoteCards(main))
1896
3184
  }
1897
- __name(wireNotes, "wireNotes");
3185
+
3186
+ /**
3187
+ * Give each `<spell-note>` its head line, again after every update (the status or replies may have changed):
3188
+ * an `<epic-page-note-head>`, "Note · 10/10 14:02", the first line of the note while folded, its status, how many
3189
+ * replies.
3190
+ * - a click on it folds and unfolds the card (the note's `open`, which a live patch keeps)
3191
+ */
1898
3192
  function drawNoteCards(main) {
1899
3193
  for (const note of main.querySelectorAll("spell-note")) {
1900
- note.querySelector(":scope > epic-page-note-head")?.remove();
3194
+ note.querySelector(":scope > epic-page-note-head")?.remove()
1901
3195
  const head = el("epic-page-note-head", {
1902
3196
  "data-spell-added": true,
1903
- at: note.getAttribute("at") ?? void 0,
3197
+ at: note.getAttribute("at") ?? undefined,
1904
3198
  status: note.getAttribute("status") || "new",
1905
3199
  replies: note.querySelectorAll(":scope > spell-note-reply").length,
1906
3200
  preview: noteText(note).split("\n")[0],
1907
3201
  open: note.hasAttribute("open")
1908
- });
3202
+ })
1909
3203
  for (const type of ["epic-note-opened", "epic-note-closed"])
1910
- head.addEventListener(type, (event) => note.toggleAttribute("open", !!event.detail?.open));
1911
- note.prepend(head);
3204
+ head.addEventListener(type, (event) => note.toggleAttribute("open", !!event.detail?.open))
3205
+ note.prepend(head)
1912
3206
  }
1913
3207
  }
1914
- __name(drawNoteCards, "drawNoteCards");
3208
+
3209
+ ////////////////
3210
+ // ## Screenshots full size
3211
+ ////////////////
3212
+
3213
+ /**
3214
+ * SCREENSHOTS open full size (epic `epic-engine` I129; Owen, 2026-10-25: "Can't click on images in the page to
3215
+ * expand so I can't tell"): ONE pair of listeners for the whole page, `ImageZoom`'s.
3216
+ * - a click on a zoomable image shows it in `<ui-zoom>`, its link never followed (a `target="_blank"` one too)
3217
+ * - the pointer over one marks it `data-ui-zoom`, the zoom-in cursor (`spell-doc.css`); a patch keeps the mark
3218
+ * (`KEPT_ATTRIBUTES`)
3219
+ * - a request's thumbnail takes its own click first (`<epic-field>`): this one sees it prevented, and leaves it
3220
+ */
1915
3221
  function wireImageZoom() {
1916
- document.addEventListener("click", ImageZoom.onClick);
1917
- document.addEventListener("pointerover", ImageZoom.onPointerOver, { passive: true });
3222
+ document.addEventListener("click", ImageZoom.onClick)
3223
+ document.addEventListener("pointerover", ImageZoom.onPointerOver, { passive: true })
1918
3224
  }
1919
- __name(wireImageZoom, "wireImageZoom");
3225
+
3226
+ ////////////////
3227
+ // ## The Epics page's sort
3228
+ ////////////////
3229
+
3230
+ /**
3231
+ * The Epics page's SORT buttons: an `<epic-sort>` (the epics pack, epic `epic-engine` P3) in the page header,
3232
+ * beside the New epic pill.
3233
+ * - Owen, 2026-10-13: "Add buttons to epics header to sort by date or alphabetical, within the sessions"
3234
+ * - only where the page has an `<epic-list>`, which follows it
3235
+ * - the elements do the rest: the buttons, remembering, the sorting, the groups, the saga chips, the stars
3236
+ * - callable again (a page updated in place): one at most
3237
+ * - SIDE EFFECT: adds it to the header, marked `data-spell-added` so the live patch steps around it
3238
+ */
1920
3239
  function wireEpicSort(main) {
1921
- const head = main.querySelector(".spell-page-head");
1922
- if (!head || !main.querySelector("epic-list") || head.querySelector("epic-sort")) return;
1923
- addHeadTool(head, el("epic-sort", { "data-spell-added": true }), "page");
1924
- }
1925
- __name(wireEpicSort, "wireEpicSort");
1926
- var NEW_EPIC_API = "/api/epics/new";
1927
- var NEW_EPIC_DRAFT_KEY = "spell-epics:new-epic-draft";
1928
- var OLD_NEW_EPIC_DRAFT_KEY = "spell-new-epic-draft";
3240
+ const head = main.querySelector(".spell-page-head")
3241
+ if (!head || !main.querySelector("epic-list") || head.querySelector("epic-sort")) return
3242
+ addHeadTool(head, el("epic-sort", { "data-spell-added": true }), "page")
3243
+ }
3244
+
3245
+ ////////////////
3246
+ // ## New epic
3247
+ ////////////////
3248
+
3249
+ /** The page server's New epic route (`src/tool/epicRoutes.ts`). */
3250
+ const NEW_EPIC_API = "/api/epics/new"
3251
+
3252
+ /** `localStorage` key of the New epic box's unsaved text (`{ title, prompt }`), one for every Epics page. */
3253
+ const NEW_EPIC_DRAFT_KEY = "spell-epics:new-epic-draft"
3254
+
3255
+ /** Its key before epic `prefs-and-undo` P4, with no store: moved to `NEW_EPIC_DRAFT_KEY` once. */
3256
+ const OLD_NEW_EPIC_DRAFT_KEY = "spell-new-epic-draft"
3257
+
3258
+ /**
3259
+ * NEW EPIC (epic `airplane` P7): on the Epics page (`epics/index.html`), a New epic pill in the page header.
3260
+ * - its box: a title and the kickoff prompt (a textarea that grows with its text); ⌘ / Ctrl Enter saves
3261
+ * - the page server writes a FUTURE epic at once (`epicRoutes.ts`): no Claude needed, so it works on a plane;
3262
+ * the home page is rewritten, so the new card shows here with its seedling; `/airplane land` offers to start it
3263
+ * - only served by the page server with a token: from `file://`, no pill
3264
+ * - what's typed and not saved is kept (`NEW_EPIC_DRAFT_KEY`) until it's saved
3265
+ */
1929
3266
  function wireNewEpic(main) {
1930
- if (!/(^|\/)epics\/(index\.html)?$/.test(location.pathname)) return;
1931
- if (!ServerLink.isServed()) return;
1932
- const head = main.querySelector(".spell-page-head");
1933
- if (!head || head.querySelector(".spell-new-epic")) return;
1934
- const tip = "Write an idea down as a future epic";
3267
+ if (!/(^|\/)epics\/(index\.html)?$/.test(location.pathname)) return
3268
+ if (!ServerLink.isServed()) return
3269
+ const head = main.querySelector(".spell-page-head")
3270
+ if (!head || head.querySelector(".spell-new-epic")) return
3271
+ // the browser's own tooltip, a `title` (Owen, 2026-10-10: never a `<ui-popup>` as a tooltip)
3272
+ const tip = "Write an idea down as a future epic"
1935
3273
  const button = el(
1936
3274
  "ui-button",
1937
3275
  { appearance: "circular basic", size: "tiny", icon: "seedling", title: tip },
1938
3276
  "New epic"
1939
- );
1940
- button.addEventListener("click", openNewEpicBox);
1941
- titleInside(button);
1942
- addHeadTool(head, el("span", { class: "spell-new-epic", "data-spell-added": true }, button), "page");
3277
+ )
3278
+ button.addEventListener("click", openNewEpicBox)
3279
+ titleInside(button)
3280
+ addHeadTool(head, el("span", { class: "spell-new-epic", "data-spell-added": true }, button), "page")
1943
3281
  }
1944
- __name(wireNewEpic, "wireNewEpic");
3282
+
3283
+ /** Open the New epic box, with the draft typed so far. */
1945
3284
  function openNewEpicBox() {
1946
- const box = newEpicBox();
1947
- PrefStore.moveOldKey(OLD_NEW_EPIC_DRAFT_KEY, NEW_EPIC_DRAFT_KEY);
1948
- const draft = readJSON(NEW_EPIC_DRAFT_KEY);
1949
- const [title, prompt] = box.querySelectorAll("input, textarea");
1950
- title.value = typeof draft.title === "string" ? draft.title : "";
1951
- prompt.value = typeof draft.prompt === "string" ? draft.prompt : "";
1952
- box.visible = true;
3285
+ const box = newEpicBox()
3286
+ // TODO: drop the move once every browser has opened the Epics page since epic `prefs-and-undo` P4
3287
+ PrefStore.moveOldKey(OLD_NEW_EPIC_DRAFT_KEY, NEW_EPIC_DRAFT_KEY)
3288
+ const draft = readJSON(NEW_EPIC_DRAFT_KEY)
3289
+ const [title, prompt] = box.querySelectorAll("input, textarea")
3290
+ title.value = typeof draft.title === "string" ? draft.title : ""
3291
+ prompt.value = typeof draft.prompt === "string" ? draft.prompt : ""
3292
+ box.visible = true
1953
3293
  requestAnimationFrame(() => {
1954
- growField(prompt);
1955
- (title.value ? prompt : title).focus();
1956
- });
3294
+ growField(prompt)
3295
+ ;(title.value ? prompt : title).focus()
3296
+ })
1957
3297
  }
1958
- __name(openNewEpicBox, "openNewEpicBox");
3298
+
3299
+ /** The New epic box, made once (outside `main`: a live patch never sees it). */
1959
3300
  function newEpicBox() {
1960
- let box = document.getElementById("spell-new-epic-box");
1961
- if (box) return box;
1962
- const template = document.createElement("template");
3301
+ let box = document.getElementById("spell-new-epic-box")
3302
+ if (box) return box
3303
+ const template = document.createElement("template")
1963
3304
  template.innerHTML = `<ui-modal id="spell-new-epic-box" class="spell-note-box" size="small" closable>
1964
3305
  <ui-header><ui-icon name="seedling"></ui-icon> A new epic</ui-header>
1965
3306
  <ui-content>
@@ -1972,59 +3313,63 @@ function newEpicBox() {
1972
3313
  <ui-button class="spell-note-cancel" appearance="circular basic">Cancel</ui-button>
1973
3314
  <ui-button class="spell-note-save" appearance="circular" color="primary" icon="seedling">Make the epic</ui-button>
1974
3315
  </ui-actions>
1975
- </ui-modal>`;
1976
- box = template.content.firstElementChild;
1977
- const [title, prompt] = box.querySelectorAll("input, textarea");
1978
- const save = box.querySelector(".spell-note-save");
1979
- const close = /* @__PURE__ */ __name(() => box.visible = false, "close");
1980
- const keep = /* @__PURE__ */ __name(() => writeJSON(NEW_EPIC_DRAFT_KEY, { title: title.value, prompt: prompt.value }), "keep");
1981
- const submit = /* @__PURE__ */ __name(async () => {
1982
- if (!title.value.trim()) return title.focus();
1983
- save.setAttribute("loading", "");
3316
+ </ui-modal>`
3317
+ box = template.content.firstElementChild
3318
+ const [title, prompt] = box.querySelectorAll("input, textarea")
3319
+ const save = box.querySelector(".spell-note-save")
3320
+ const close = () => (box.visible = false)
3321
+ const keep = () => writeJSON(NEW_EPIC_DRAFT_KEY, { title: title.value, prompt: prompt.value })
3322
+ const submit = async () => {
3323
+ if (!title.value.trim()) return title.focus()
3324
+ save.setAttribute("loading", "")
1984
3325
  try {
1985
3326
  const { name } = await ServerLink.forPage().post(NEW_EPIC_API, {
1986
3327
  title: title.value.trim(),
1987
3328
  prompt: prompt.value.trim()
1988
- });
1989
- writeJSON(NEW_EPIC_DRAFT_KEY, {});
1990
- close();
1991
- noteToast(`Future epic ${name} written down`, "success");
3329
+ })
3330
+ writeJSON(NEW_EPIC_DRAFT_KEY, {})
3331
+ close()
3332
+ noteToast(`Future epic ${name} written down`, "success")
1992
3333
  } catch (error) {
1993
- noteToast(`Couldn't make the epic: ${error.message}`, "error");
3334
+ noteToast(`Couldn't make the epic: ${error.message}`, "error")
1994
3335
  } finally {
1995
- save.removeAttribute("loading");
3336
+ save.removeAttribute("loading")
1996
3337
  }
1997
- }, "submit");
1998
- title.addEventListener("input", keep);
3338
+ }
3339
+ title.addEventListener("input", keep)
1999
3340
  prompt.addEventListener("input", () => {
2000
- growField(prompt);
2001
- keep();
2002
- });
3341
+ growField(prompt)
3342
+ keep()
3343
+ })
2003
3344
  for (const field of [title, prompt])
2004
3345
  field.addEventListener("keydown", (event) => {
2005
- if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) void submit();
2006
- });
2007
- save.addEventListener("click", () => void submit());
2008
- box.querySelector(".spell-note-cancel").addEventListener("click", close);
2009
- document.body.append(box);
2010
- return box;
2011
- }
2012
- __name(newEpicBox, "newEpicBox");
3346
+ if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) void submit()
3347
+ })
3348
+ save.addEventListener("click", () => void submit())
3349
+ box.querySelector(".spell-note-cancel").addEventListener("click", close)
3350
+ document.body.append(box)
3351
+ return box
3352
+ }
3353
+
3354
+ /**
3355
+ * A note's text as typed: paragraphs split by blank lines, `<br>` a newline, `<code>` in backticks;
3356
+ * its head and replies left out. `PageNotes.js` `textOf()` is the same, on the server.
3357
+ */
2013
3358
  function noteText(note) {
2014
- const blocks = [];
3359
+ const blocks = []
2015
3360
  for (const child of note.childNodes) {
2016
- if (child.nodeType === Node.ELEMENT_NODE && child.matches("epic-page-note-head, spell-note-reply")) continue;
2017
- const words = child.nodeType === Node.ELEMENT_NODE ? inlineText(child) : child.textContent;
2018
- if (words.trim()) blocks.push(words.trim());
3361
+ if (child.nodeType === Node.ELEMENT_NODE && child.matches("epic-page-note-head, spell-note-reply")) continue
3362
+ const words = child.nodeType === Node.ELEMENT_NODE ? inlineText(child) : child.textContent
3363
+ if (words.trim()) blocks.push(words.trim())
2019
3364
  }
2020
- return blocks.join("\n\n");
3365
+ return blocks.join("\n\n")
3366
+
3367
+ /** `node`'s text: `<br>` a newline, `<code>` in backticks, white space as one space. */
2021
3368
  function inlineText(node) {
2022
- if (node.nodeType === Node.TEXT_NODE) return node.textContent.replace(/\s+/g, " ");
2023
- if (node.nodeType !== Node.ELEMENT_NODE) return "";
2024
- if (node.localName === "br") return "\n";
2025
- const inner = Array.from(node.childNodes, inlineText).join("");
2026
- return node.localName === "code" ? `\`${inner}\`` : inner;
3369
+ if (node.nodeType === Node.TEXT_NODE) return node.textContent.replace(/\s+/g, " ")
3370
+ if (node.nodeType !== Node.ELEMENT_NODE) return ""
3371
+ if (node.localName === "br") return "\n"
3372
+ const inner = Array.from(node.childNodes, inlineText).join("")
3373
+ return node.localName === "code" ? `\`${inner}\`` : inner
2027
3374
  }
2028
- __name(inlineText, "inlineText");
2029
3375
  }
2030
- __name(noteText, "noteText");