spell 0.8.7 → 0.8.8

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 (243) hide show
  1. package/README-epics.md +96 -36
  2. package/app/package.json +25 -1
  3. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  4. package/dist/cli/publish/PublishedPackage.js +6 -3
  5. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  6. package/dist/cli/publish/ScratchInstall.js +69 -8
  7. package/dist/epic/cli/EpicProgram.js +7 -1
  8. package/dist/epic/cli/epicGroups.js +2 -1
  9. package/dist/epic/command/BaseBranch.d.ts +35 -0
  10. package/dist/epic/command/BaseBranch.js +58 -0
  11. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  12. package/dist/epic/command/EpicCheckout.js +4 -4
  13. package/dist/epic/command/EpicGuide.js +3 -2
  14. package/dist/epic/command/EpicTools.d.ts +5 -0
  15. package/dist/epic/command/EpicTools.js +14 -3
  16. package/dist/epic/command/MainMerge.d.ts +26 -15
  17. package/dist/epic/command/MainMerge.js +60 -16
  18. package/dist/epic/command/RepoInit.d.ts +116 -8
  19. package/dist/epic/command/RepoInit.js +308 -13
  20. package/dist/epic/command/Requests.d.ts +1 -0
  21. package/dist/epic/command/Requests.js +6 -1
  22. package/dist/epic/command/SessionMoves.js +2 -1
  23. package/dist/epic/command/SkillsCheck.js +3 -2
  24. package/dist/epic/command/Stock.js +3 -1
  25. package/dist/epic/command/TurnEnd.d.ts +1 -1
  26. package/dist/epic/command/TurnEnd.js +4 -3
  27. package/dist/epic/command/Worktrees.d.ts +18 -3
  28. package/dist/epic/command/Worktrees.js +38 -7
  29. package/dist/epic/command/command.types.d.ts +3 -0
  30. package/dist/epic/components/__pack/epics.entry.js +43 -43
  31. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  32. package/dist/epic/config/EngineFiles.mjs +60 -0
  33. package/dist/epic/config/EpicConfig.d.ts +12 -2
  34. package/dist/epic/config/EpicConfig.js +9 -1
  35. package/dist/epic/config/GitHub.d.ts +41 -1
  36. package/dist/epic/config/GitHub.js +75 -3
  37. package/dist/epic/config/LayeredSettings.js +3 -2
  38. package/dist/epic/server/EpicServer.d.ts +1 -1
  39. package/dist/epic/server/EpicServer.js +26 -12
  40. package/dist/epic/tool/InboxPoller.mjs +2 -1
  41. package/dist/epic/tool/MigrateCommands.js +6 -8
  42. package/dist/epic/tool/PlanDocFiles.js +3 -2
  43. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  44. package/dist/epic/tool/ServedFolders.js +4 -4
  45. package/dist/epic/tools/PageInboxes.js +3 -3
  46. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  47. package/dist/epic/tools/_assets/commands.js +20 -2073
  48. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  49. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  50. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  51. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  52. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  53. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  54. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  55. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  56. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  57. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  58. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  59. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  60. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  61. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  62. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  63. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  64. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  65. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  66. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  67. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  68. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  69. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  103. package/dist/epic/tools/_assets/goals-live.js +318 -210
  104. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  105. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  106. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  107. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  108. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  109. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  110. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  111. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  112. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  113. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  114. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  115. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  116. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  117. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  118. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  119. package/dist/epic/tools/pages.d.ts +5 -6
  120. package/dist/epic/tools/pages.js +7 -6
  121. package/dist/epic/window.mjs +2 -3
  122. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  123. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  124. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  125. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  126. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  127. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  128. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  129. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  130. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  131. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  132. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  133. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  134. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  135. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  136. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  137. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  138. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  139. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  140. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  141. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  142. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  143. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  144. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  145. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  146. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  147. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  148. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  149. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  150. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  151. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  152. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  153. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  154. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  155. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  156. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  157. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  158. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  159. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  160. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  161. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  162. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  163. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  164. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  165. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  166. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  167. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  168. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  169. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  170. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  171. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  172. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  173. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  174. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  175. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  176. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  177. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  178. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  179. package/dist/ui/components/ui-parts/UIHeader.d.ts +3 -1
  180. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  181. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  182. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  183. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  184. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  185. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  186. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  187. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  188. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  189. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  190. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  191. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  192. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  193. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  194. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  195. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  196. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  197. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  198. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  199. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  200. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  201. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  202. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  203. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  204. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  205. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  206. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  207. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  208. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  209. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  210. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  211. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  212. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  213. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  214. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  215. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  216. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  217. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  218. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  219. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  220. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  221. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  222. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  223. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  224. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  225. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  226. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  227. package/dist/util/spell/constants.js +1 -1
  228. package/epic/.claude-plugin/plugin.json +1 -1
  229. package/epic/.codex-plugin/plugin.json +1 -1
  230. package/epic/hooks/handoff.mjs +4 -3
  231. package/epic/hooks/worktree.mjs +22 -3
  232. package/epic/package.json +41 -2
  233. package/epic/skills/details/SKILL.md +2 -1
  234. package/epic/skills/epic/SKILL.md +7 -1
  235. package/epic/skills/epic/guide.md +4 -0
  236. package/epic/skills/isolate/SKILL.md +35 -0
  237. package/epic/src/AGENTS.md +6 -2
  238. package/epic/templates/durable.html +1 -1
  239. package/epic/vscode/package.json +1 -1
  240. package/epic/vscode/spell-epic.vsix +0 -0
  241. package/package.json +1 -1
  242. package/parser/package.json +1 -1
  243. package/ui/package.json +15 -2
@@ -1,7 +1,25 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
1
+ /*
2
+ * COMMENTS on a docs page or an epic page: the bullhorns, the comment pane, the threads, a docs page's Send
3
+ * (epic `airplane` P11; `wireComments()` below says it all).
4
+ * - Its own module since epic `epic-engine` P2 (T3), so two scripts carry it:
5
+ * - the docs bundle, `spell-ui.js`, through the page runtime (`spell-doc-runtime.js`): guides, epic pages ...
6
+ * - `spell-comments.js` by itself (`spell-comments.entry.js`), on Epic UI's pages:
7
+ * they load Spell UI's site bundle, not the docs bundle, so nothing else of the runtime;
8
+ * it draws with the page's own Spell UI
9
+ * - Plain DOM: it makes elements and lets the page draw them, never imports Spell UI or the epics pack itself:
10
+ * - Spell UI's (`<ui-button>`), which the page's Spell UI draws
11
+ * - the epics pack's (epic `epic-engine` P3), which every page that takes comments loads
12
+ * (the docs runtime's `loadEpicsPack()`; Epic UI's layout), each upgrading as the pack registers:
13
+ * - each comment's thread, `<epic-thread>`, in an `<epic-threads>` box under its block
14
+ * - the comment pane, `<epic-comment-pane>`
15
+ * - Owen's field, in the pane or a thread: a native `<textarea>` this code owns, so it lives through every redraw
16
+ * - what a thread shows, and its ids and words: `ThreadFacts` (`spell/epic/comments`), which the elements share
17
+ * - Its look: `spell-comments.css`, beside it (the bullhorns, Send, Owen's field, where a thread sits);
18
+ * the elements' own sheets draw the rest.
19
+ * - What it keeps in the browser (drafts, what's been seen) goes through the kit's `PrefStore`:
20
+ * the helpers' `readJSON()` / `writeJSON()`.
21
+ */
3
22
 
4
- // src/tools/_assets/spell-doc-comments.js
5
23
  import {
6
24
  PAGE_ANCHOR,
7
25
  anchorOf,
@@ -17,12 +35,12 @@ import {
17
35
  quoteIn,
18
36
  sectionOf,
19
37
  sectionTitle
20
- } from "../BlockAnchors.js";
21
- import { nextFrame } from "spell/util/dom";
22
- import { toolbarTools } from "./spell-doc-toolbar.js";
23
- import { ThreadFacts } from "../../comments/index.js";
24
- import { DraftSaver } from "../../answers/index.js";
25
- import { ServerLink } from "../../review/index.js";
38
+ } from "spell/epic/tools/BlockAnchors.js"
39
+ import { nextFrame } from "spell/util/dom"
40
+ import { toolbarTools } from "./spell-doc-toolbar.js"
41
+ import { ThreadFacts } from "spell/epic/comments"
42
+ import { DraftSaver } from "spell/epic/answers"
43
+ import { ServerLink } from "spell/epic/review"
26
44
  import {
27
45
  addBlockAction,
28
46
  BLOCK_ROW,
@@ -35,104 +53,309 @@ import {
35
53
  readJSON,
36
54
  titleInside,
37
55
  writeJSON
38
- } from "./spell-doc-helpers.js";
39
- var COMMENTS_API = "/api/docs/comments";
40
- var pageComments = null;
41
- function commentsOnPage() {
42
- return pageComments;
56
+ } from "./spell-doc-helpers.js"
57
+
58
+ ////////////////
59
+ // ## Comments
60
+ ////////////////
61
+
62
+ /** The page server's comments routes (`src/tools/commentsRoutes.ts`). */
63
+ const COMMENTS_API = "/api/docs/comments"
64
+
65
+ /** The page's comments, once the page server says it takes them (`wireComments()`): Cmd / Ctrl + K reads them. */
66
+ let pageComments = null
67
+
68
+ /** The page's comments (`PageComments`), once the page server says it takes them; else `null`. */
69
+ export function commentsOnPage() {
70
+ return pageComments
43
71
  }
44
- __name(commentsOnPage, "commentsOnPage");
45
- var COMMENT_DRAFT_KEY_PREFIX = "spell-comment-draft:";
46
- var COMMENT_READ_KEY_PREFIX = "spell-comment-read:";
47
- var SEEN_MS = 1200;
48
- var TEXT_HOLDERS = "p, li, dt, dd, td, th, blockquote, pre, figcaption, h4, h5, h6";
49
- var HOLDS_INSIDE = /^(li|dt|dd|td|th)$/;
50
- var QUOTE_HIGHLIGHT = "spell-comment-quote";
51
- var PROMOTED = "spell-promoted";
52
- var SHOW_FRAMES = 8;
53
- var QUOTE_WAITING_HIGHLIGHT = "spell-comment-quote-waiting";
54
- var COMMENT_SAVE_MS = 600;
55
- var REDRAW_MS = 150;
56
- var SEND_POLL_MS = 3e4;
57
- var EPIC_PAGE = /\.(plan|saga)\.html$/;
58
- var TITLE_ROW_BLOCKS = "epic-overview, epic-item, epic-update[at], epic-aside, epic-code";
59
- var THREADS_FIRST = /^(ui-section|epic-overview)$/;
60
- async function wireComments(main, { go, pageFolds, signal } = {}) {
61
- if (!ServerLink.isServed()) return;
62
- const comments = new PageComments(main, { go, pageFolds, signal });
63
- if (!await comments.load() || signal?.aborted) return;
64
- pageComments = comments;
65
- comments.draw();
66
- const reload = /* @__PURE__ */ __name(() => void comments.load().then((takes) => takes && !signal?.aborted && comments.draw()), "reload");
67
- const listening = { signal };
68
- addEventListener("spell-doc:updated", () => comments.draw(), listening);
69
- const epicPage = EPIC_PAGE.test(location.pathname);
72
+
73
+ /** `localStorage` key prefix of a page's unsaved comments (`{ [anchor | comment id]: text }`), per page. */
74
+ const COMMENT_DRAFT_KEY_PREFIX = "spell-comment-draft:"
75
+
76
+ /**
77
+ * `localStorage` key prefix of the Claude replies Owen has SEEN on a page, per page:
78
+ * `{ [comment id]: time of the latest Claude reply seen }`.
79
+ * - the store the news-only cards kept before threads, read the same way:
80
+ * a time at or after the latest reply means seen
81
+ */
82
+ const COMMENT_READ_KEY_PREFIX = "spell-comment-read:"
83
+
84
+ /** How long an open thread with an unseen reply must stay on screen to count as seen, ms. */
85
+ const SEEN_MS = 1200
86
+
87
+ /** The smallest blocks a quote's thread goes under (`holderOf()`): a paragraph, a list item, a cell ... */
88
+ const TEXT_HOLDERS = "p, li, dt, dd, td, th, blockquote, pre, figcaption, h4, h5, h6"
89
+
90
+ /** Of those, the ones a thread goes INSIDE, at the end, so the list or table stays valid. */
91
+ const HOLDS_INSIDE = /^(li|dt|dd|td|th)$/
92
+
93
+ /** The CSS highlight the quoted text of every comment is drawn with (`::highlight()` in `spell-comments.css`). */
94
+ const QUOTE_HIGHLIGHT = "spell-comment-quote"
95
+
96
+ /** The class of the rows of comments shown past a folded section (`drawPromoted()`). */
97
+ const PROMOTED = "spell-promoted"
98
+
99
+ /** How many frames a promoted comment is held where its row was (`showPromoted()`), while what opened settles. */
100
+ const SHOW_FRAMES = 8
101
+
102
+ /**
103
+ * The one a comment's quote is drawn with while it WAITS for Claude (its turn `agent`): purple, Owen's comments
104
+ * not taken in yet (Owen, 2026-10-25: "highlight bullhorn items still-to-be-processed ... purple for my comments")
105
+ */
106
+ const QUOTE_WAITING_HIGHLIGHT = "spell-comment-quote-waiting"
107
+
108
+ /** How long after Owen stops typing the comment box saves itself, ms. */
109
+ const COMMENT_SAVE_MS = 600
110
+
111
+ /** How long after the page's content changes (an epic page's part loading) the comments draw again, ms. */
112
+ const REDRAW_MS = 150
113
+
114
+ /**
115
+ * How often a docs page with a Send asks again who is listening, and an epic page for its comments, ms.
116
+ * - the server calls a session gone once its heartbeat is 90s old (`ReviewInbox` `LISTEN_STALE_MS`),
117
+ * with no file change to announce it
118
+ */
119
+ const SEND_POLL_MS = 30_000
120
+
121
+ /** An epic page's or a saga page's path: its comments live in the epic's review inbox. */
122
+ const EPIC_PAGE = /\.(plan|saga)\.html$/
123
+
124
+ /**
125
+ * The blocks with a title row and an `actions` slot in it (epic `epic-workflow` P25).
126
+ * - their bullhorn goes in that slot, never over their own buttons:
127
+ * after the title, before the review pills, the date, the fold
128
+ * - an epic page's item, update (drawn as a block, with its date), aside and code block:
129
+ * `Fold.types.ts`, in the epics pack
130
+ * - the Overview (`<epic-overview>`, a comment on all of it): first in its title row,
131
+ * before its review buttons, expand-all, collapse-all and the fold (epic `epic-engine` I55)
132
+ * - Owen, 2026-10-20: "The buttons on the left should move into the 1. Overview header, as well as a bullhorn"
133
+ * - its summary and prose keep their own, on their corners
134
+ * - a docs section has its own (`ui-section`'s `actions` slot, `.at-section`)
135
+ * - every other block (a paragraph, a table, a list, a message, cards, a phase's field, the summary) has no title row:
136
+ * its bullhorn sits over its corner, first in its actions row
137
+ * (`.at-block`, in its `<epic-actions>`: `addBlockAction()`)
138
+ */
139
+ const TITLE_ROW_BLOCKS = "epic-overview, epic-item, epic-update[at], epic-aside, epic-code"
140
+
141
+ /** The blocks whose box of threads goes FIRST in them, under their title: a docs section, the Overview. */
142
+ const THREADS_FIRST = /^(ui-section|epic-overview)$/
143
+
144
+ /**
145
+ * COMMENTS (epic `airplane`, P11): Owen's comments for Claude, on a page's blocks or on text he selected,
146
+ * kept by the page server (`commentsRoutes.ts`).
147
+ * - a docs page's in its inbox file (`<page>.inbox.json5`), an epic page's in the epic's review inbox
148
+ * - No Claude, no network: only the page server, so it works on a plane.
149
+ * - served by the page server with a token, on a page that takes comments (the `GET` says `takesComments`):
150
+ * - a BULLHORN beside every major block, and in the page header (the whole page): shown while the block is hovered
151
+ * - the blocks (`BlockAnchors.js` `blocksIn()`): sections, tables, asides, code, messages, cards, steps,
152
+ * top-level lists; an epic page's items, phase fields, summary and Overview prose
153
+ * - in the block's title row, when it has one (its `actions` slot):
154
+ * a docs section's, an epic page item's, update's, aside's or code block's
155
+ * - else over the block's top right corner
156
+ * - SELECTED TEXT: ⌘ / Ctrl I, or the bullhorn that floats beside the selection
157
+ * - the box opens for that block, its header the text's first words
158
+ * - the comment keeps the quote, highlighted on the page while it exists
159
+ * - the box is a small PANE, fixed on the screen, just under the selection (or the button clicked):
160
+ * the page never scrolls, and Owen drags it by its header
161
+ * - Owen, 2026-10-10: "a little floating pane below the selected text that I can move around --
162
+ * don't scroll the page and lose context!"
163
+ * - in it (`<epic-comment-pane>`): a header (the first words, a floppy, a trash once saved, ×),
164
+ * and a textarea that grows, with no placeholder
165
+ * - ivory, no buttons below (Owen, 2026-10-10)
166
+ * - it saves itself as Owen types, the floppy says so
167
+ * - ×, Escape or the focus leaving it (Tab, a click elsewhere) closes it
168
+ * - what's typed and not saved yet is kept in this browser (`COMMENT_DRAFT_KEY_PREFIX`)
169
+ * - NEVER an empty comment: nothing typed saves nothing; emptied, it's deleted at once
170
+ * - the pane is for writing a NEW comment; once saved and closed, it's a THREAD (below)
171
+ * - THREADS (Owen, 2026-10-10: "the entire comment thread should be in one collapsable/accordion pane"):
172
+ * every comment shows as one, folding: an `<epic-thread>` (`thread()`), in an `<epic-threads>` box
173
+ * - where: under the paragraph (list item, cell ...) holding its quote (`holderOf()`), else under its block
174
+ * - all ivory, the pane's outline and corners, whoever spoke last
175
+ * - its edges: an epic page item's note box's, else the block's it's under (spell-comments.css)
176
+ * - its header: a chevron, the bullhorn (a check circle once done), the pane's summary (`ThreadFacts.headline()`)
177
+ * - then Owen's answer while it's his turn (Claude spoke last): an epic page item's review pills
178
+ * (`<epic-review buttons="thread">`), Approve / Revisit / the x, as "that's good" / reply / "skip it"
179
+ * - Reopen once done; the trash, always
180
+ * - the messages in order, a bold "You:" / "Claude:" first
181
+ * - his plain on the ivory, Claude's in a light violet box
182
+ * - each one's time in its top right corner (the first's with the day)
183
+ * - then a green Done line once closed; "Claude: thinking…" last while Claude is at work on it (`working`)
184
+ * - open while it's Owen's turn, or Claude is thinking, or he opened it; else folded to its header
185
+ * - a REPLY BOX last while it's open, saved as he types (`reply`), and as the focus leaves it
186
+ * - Revisit puts the cursor in it
187
+ * - the pen edits his first words while Claude hasn't had them
188
+ * - a click on a highlighted quote opens its thread
189
+ * - the trash, on a thread or the pane: one click (`delete` while it waits, else `clear`); Undo in the toast
190
+ * - the BULLHORN only ever starts a new comment: no count, since the block's threads are right there
191
+ * (Owen, 2026-10-10: "Bullhorn to the far right is unnecessary")
192
+ * - IDS (epic `epic-engine` P44; Owen, 2026-10-25: "Can `Mark` be `Comment (C)`"; `M3` from epic `epic-workflow` P23):
193
+ * shown `C3`, small and muted in each thread's header, before its summary (`<epic-thread>`)
194
+ * - the server keys them `c3`, and a typed id takes `C3`, `c3` or `cm3` (`ThreadFacts.numberOf()`); `M3` is a
195
+ * manual test's
196
+ * - JUMPING to the threads waiting on Owen (Claude spoke last;
197
+ * Owen, 2026-10-10: "Is there a way to jump to comments in replies?"):
198
+ * - a BULLHORN at the right of the page's toolbar, an orange count of them on it;
199
+ * none waiting: no count, and it goes through the open threads; no open thread: hidden
200
+ * - each click lands on the next (`nextWaiting()`), in page order, round again after the last:
201
+ * opened, below the stuck titles
202
+ * - Cmd / Ctrl + K takes a comment's id, and lists them (`openJumpPrompt()`)
203
+ * - drawn again:
204
+ * - after a live patch (`spell-doc:updated`)
205
+ * - when the page's content changes (an epic page's part loading)
206
+ * - when the inbox file changes (`spell-server:changed`: another window, Claude)
207
+ * - when the page comes back into view
208
+ * - every 30s on an epic or saga page, for a change the live socket missed (I169), and on a docs page with a Send
209
+ * - what it adds in `main` carries `data-spell-added`: a patch steps around it, the anchors never count it
210
+ * - NEVER throws: a page with no server, or a server without the routes, shows no bullhorns
211
+ * - options:
212
+ * - `go(id)`: lands on an id as a link to it does (the runtime's `wireAnchors()`);
213
+ * without it, the browser's `scrollIntoView()`
214
+ * - `signal`: an `AbortSignal` that takes it all down again
215
+ * - for Epic UI's pages, whose `main` the site's router swaps for the next page's (`spell-comments.entry.js`)
216
+ * - every listener, observer and timer, the floating bullhorn
217
+ * - what's typed and not saved yet is sent first, as on leaving the page
218
+ */
219
+ export async function wireComments(main, { go, pageFolds, signal } = {}) {
220
+ if (!ServerLink.isServed()) return
221
+ const comments = new PageComments(main, { go, pageFolds, signal })
222
+ if (!(await comments.load()) || signal?.aborted) return
223
+ pageComments = comments
224
+ comments.draw()
225
+ const reload = () => void comments.load().then((takes) => takes && !signal?.aborted && comments.draw())
226
+ const listening = { signal }
227
+ addEventListener("spell-doc:updated", () => comments.draw(), listening)
228
+ // its inbox files changing, the page coming into view; and every 30s:
229
+ // - a docs page's Send: who is listening, as a session that stopped leaves no file change, only an old heartbeat
230
+ // - an epic or saga page: a change the live socket missed (epic `epic-engine` I169: a thread said "thinking…"
231
+ // 20 minutes after its answer, while the review client's own 4s poll had the inbox right)
232
+ const epicPage = EPIC_PAGE.test(location.pathname)
70
233
  const unwatch = ServerLink.watch(window, (path) => comments.inboxPaths.includes(path), reload, {
71
234
  every: SEND_POLL_MS,
72
- polls: /* @__PURE__ */ __name(() => !!comments.send || epicPage, "polls")
73
- });
74
- const flush = /* @__PURE__ */ __name(() => {
75
- comments.open?.flush?.();
76
- for (const each of comments.fields()) each.flush?.();
77
- }, "flush");
78
- addEventListener("pagehide", flush, listening);
79
- const sizes = typeof ResizeObserver === "function" ? new ResizeObserver(() => comments.makeRoom()) : null;
80
- sizes?.observe(main);
81
- comments.watchContent();
82
- comments.watchFolds();
83
- comments.wireSelection();
235
+ polls: () => !!comments.send || epicPage
236
+ })
237
+ // leaving (a reload, another page): what's typed in the pane or a reply box and not saved yet goes now
238
+ const flush = () => {
239
+ comments.open?.flush?.()
240
+ for (const each of comments.fields()) each.flush?.()
241
+ }
242
+ addEventListener("pagehide", flush, listening)
243
+ // the page's layout changing (a width, an item folding) can bring a corner bullhorn over a thread's header
244
+ const sizes = typeof ResizeObserver === "function" ? new ResizeObserver(() => comments.makeRoom()) : null
245
+ sizes?.observe(main)
246
+ comments.watchContent()
247
+ comments.watchFolds()
248
+ comments.wireSelection()
84
249
  signal?.addEventListener(
85
250
  "abort",
86
251
  () => {
87
- flush();
88
- unwatch();
89
- sizes?.disconnect();
90
- comments.stop();
91
- if (pageComments === comments) pageComments = null;
252
+ flush()
253
+ unwatch()
254
+ sizes?.disconnect()
255
+ comments.stop()
256
+ if (pageComments === comments) pageComments = null
92
257
  },
93
258
  { once: true }
94
- );
259
+ )
95
260
  }
96
- __name(wireComments, "wireComments");
261
+
262
+ /**
263
+ * The URL paths the page server may announce inbox file `inbox` (`<page>.inbox.json5`) by:
264
+ * - it, and the same without a worktree's prefix (`/worktrees/<w>/`: a shared folder's changes come without it)
265
+ * - each by its old name too, `.inbox.json` (`ServerLink.dataFileNames()`)
266
+ */
97
267
  function inboxPathsOf(inbox) {
98
- const paths = [inbox, inbox.replace(/^\/worktrees\/[^/]+(?=\/)/, "")];
99
- return [...new Set(paths.flatMap((path) => ServerLink.dataFileNames(path)))];
268
+ const paths = [inbox, inbox.replace(/^\/worktrees\/[^/]+(?=\/)/, "")]
269
+ return [...new Set(paths.flatMap((path) => ServerLink.dataFileNames(path)))]
100
270
  }
101
- __name(inboxPathsOf, "inboxPathsOf");
102
- var PageComments = class {
103
- static {
104
- __name(this, "PageComments");
105
- }
271
+
272
+ /****************
273
+ * ### `PageComments`
274
+ * One page's comments:
275
+ * - what the server holds, drawn under their blocks
276
+ * - the one comment pane open
277
+ * - the floating bullhorn of a text selection
278
+ * - `list`: the comments as the server last answered; every write answers the whole list, which is drawn again
279
+ * - NEVER throws: a failed save says so (the floppy turns red), the text kept in the pane
280
+ ****************/
281
+ class PageComments {
106
282
  /**
107
283
  * - `main`: the page's `main`, where the blocks are
108
284
  * - `go(id)`: lands on the element with `id` as a link to it does (`wireAnchors()`), resolving once landed
109
285
  * - `signal`: as `wireComments()` takes it
110
286
  */
111
287
  constructor(main, { go, pageFolds, signal } = {}) {
112
- this.main = main;
113
- this.go = go;
114
- this.pageFolds = pageFolds;
115
- this.signal = signal;
116
- this.contentWatch = null;
117
- this.lastWaiting = "";
118
- this.list = [];
119
- this.open = null;
120
- this.pane = null;
121
- this.threads = /* @__PURE__ */ new Map();
122
- this.replyBoxes = /* @__PURE__ */ new Map();
123
- this.editing = null;
124
- this.quotes = [];
125
- this.folds = /* @__PURE__ */ new Map();
126
- const page = decodeURIComponent(location.pathname);
127
- const inbox = page.replace(/(\.plan|\.saga)?\.html$/, ".inbox.json5");
128
- this.inboxPaths = inboxPathsOf(inbox);
129
- this.draftKey = `${COMMENT_DRAFT_KEY_PREFIX}${location.pathname}`;
130
- this.readKey = `${COMMENT_READ_KEY_PREFIX}${location.pathname}`;
131
- this.read = {};
132
- this.seenWatch = null;
133
- this.seenTimers = /* @__PURE__ */ new Map();
134
- this.send = null;
288
+ /** the page's `main` */
289
+ this.main = main
290
+ /** lands on an id as a link does */
291
+ this.go = go
292
+ /** the page's folds, for threads inside folded sections (`drawPromoted()`): none on Epic UI's pages */
293
+ this.pageFolds = pageFolds
294
+ /** takes it all down again (`stop()`): every listener added with it */
295
+ this.signal = signal
296
+ /** what `watchContent()` watches the page's content with */
297
+ this.contentWatch = null
298
+ /** the thread the toolbar's bullhorn last landed on (`nextWaiting()`): the next click goes on from it */
299
+ this.lastWaiting = ""
300
+ /** the comments, as the server last answered (`CommentList` `all`) */
301
+ this.list = []
302
+ /**
303
+ * the pane open for a NEW comment, if any: `{ key, place, id?, finish? }`
304
+ * - `place`: `{ anchor, kind, label, excerpt, quote? ... }`
305
+ * - `id`: once its first save made it
306
+ * - `finish()`: saves what's typed, then forgets its draft
307
+ */
308
+ this.open = null
309
+ /**
310
+ * the open pane's element (`showPane()`, an `<epic-comment-pane>`), in `main` but fixed on the screen:
311
+ * a redraw never touches it
312
+ */
313
+ this.pane = null
314
+ /**
315
+ * each comment's THREAD, by comment id (`thread()`): ONE `<epic-thread>` for the visit,
316
+ * given what the server holds at each redraw, and moved only when its place changes,
317
+ * so Owen's box in it and the cursor stay
318
+ */
319
+ this.threads = new Map()
320
+ /**
321
+ * each open thread's REPLY BOX, by comment id (`replyBoxFor()`):
322
+ * `{ id, how: "reply", box, field, floppy, saved(), busy(), finish(), flush() }`
323
+ * - `box` (`field`): its `<textarea>`, slotted into the thread,
324
+ * kept across redraws while Owen is in it or it holds words not saved yet
325
+ * - `floppy`: how its last save went (`{ tip, failed }`, none before one), which the thread shows
326
+ */
327
+ this.replyBoxes = new Map()
328
+ /**
329
+ * the pen's box, editing his first words while Claude hasn't had them (`startEdit()`), if open:
330
+ * as a reply box, `how: "edit"`; it stands in for the thread's reply box meanwhile
331
+ */
332
+ this.editing = null
333
+ /** each quote's range on the page, by comment id (`highlightQuotes()`): a click on one opens its thread */
334
+ this.quotes = []
335
+ /** each thread's fold, by comment id, as the reader left it on this visit; else open while it's Owen's turn */
336
+ this.folds = new Map()
337
+ const page = decodeURIComponent(location.pathname)
338
+ /**
339
+ * the URL paths of the inbox files the comments may be in, as the page server announces their changes
340
+ * - a worktree's page (`/worktrees/<w>/epics/...`) is in a shared folder,
341
+ * whose changes it announces without that prefix
342
+ * - each by its old name too, `.inbox.json`, which a checkout on older code writes (epic `epic-workflow` P21)
343
+ */
344
+ const inbox = page.replace(/(\.plan|\.saga)?\.html$/, ".inbox.json5")
345
+ this.inboxPaths = inboxPathsOf(inbox)
346
+ /** the `localStorage` key of this page's drafts */
347
+ this.draftKey = `${COMMENT_DRAFT_KEY_PREFIX}${location.pathname}`
348
+ /** the `localStorage` key of the Claude replies Owen has seen on this page (`markSeen()`) */
349
+ this.readKey = `${COMMENT_READ_KEY_PREFIX}${location.pathname}`
350
+ /** what's in it, as `draw()` last read it */
351
+ this.read = {}
352
+ /** watches the open threads with an unseen reply (`watchSeen()`); a timer per one on screen, by comment id */
353
+ this.seenWatch = null
354
+ this.seenTimers = new Map()
355
+ /** a docs page's Send, as the server last answered (`keepSend()`); `null` on an epic page */
356
+ this.send = null
135
357
  }
358
+
136
359
  /**
137
360
  * Whether `comment` is ORANGE: Claude spoke last and Owen hasn't answered yet (✓, a reply, ×).
138
361
  * - Looking at it doesn't clear it (Owen, 2026-10-10: "I was expecting this to be orange, not ivory"):
@@ -140,59 +363,66 @@ var PageComments = class {
140
363
  * - Never once it's done.
141
364
  */
142
365
  unseen(comment) {
143
- return comment.turn === "person" && !!ThreadFacts.latestAgentAt(comment);
366
+ // orange while it's Owen's turn, seen or not, until he answers (✓, a reply, ×): Owen, 2026-10-10, on a thread
367
+ // gone ivory once looked at: "I was expecting this to be orange, not ivory"
368
+ return comment.turn === "person" && !!ThreadFacts.latestAgentAt(comment)
144
369
  }
370
+
145
371
  /**
146
372
  * Owen has seen comment `id`'s latest reply from Claude (he opened it, or it was open on screen for `SEEN_MS`):
147
373
  * remembered in this browser, its orange gone; a newer reply makes it orange again.
148
374
  */
149
375
  markSeen(id) {
150
- const comment = this.list.find((each) => each.id === id);
151
- if (!comment || !this.unseen(comment)) return;
152
- const read = readJSON(this.readKey);
153
- const latest = ThreadFacts.latestAgentAt(comment);
154
- if ((read[id] ?? "") >= latest) return;
155
- read[id] = latest;
156
- writeJSON(this.readKey, read);
157
- this.draw();
376
+ const comment = this.list.find((each) => each.id === id)
377
+ if (!comment || !this.unseen(comment)) return
378
+ const read = readJSON(this.readKey)
379
+ // read already: nothing to change (the thread stays orange until Owen answers, so the watcher fires again)
380
+ const latest = ThreadFacts.latestAgentAt(comment)
381
+ if ((read[id] ?? "") >= latest) return
382
+ read[id] = latest
383
+ writeJSON(this.readKey, read)
384
+ this.draw()
158
385
  }
386
+
159
387
  /**
160
388
  * Watch the open threads with an unseen reply: one on screen (half of it, or half the screen) for `SEEN_MS` while
161
389
  * the page is in view is seen (`markSeen()`).
162
390
  */
163
391
  watchSeen() {
164
- this.seenWatch?.disconnect();
165
- const threads = this.main.querySelectorAll("epic-thread[unseen][open]");
392
+ this.seenWatch?.disconnect()
393
+ const threads = this.main.querySelectorAll("epic-thread[unseen][open]")
166
394
  for (const [id, timer] of this.seenTimers)
167
395
  if (![...threads].some((each) => each.id === `comment-${id}`)) {
168
- clearTimeout(timer);
169
- this.seenTimers.delete(id);
396
+ clearTimeout(timer)
397
+ this.seenTimers.delete(id)
170
398
  }
171
- if (!threads.length || typeof IntersectionObserver !== "function") return;
399
+ if (!threads.length || typeof IntersectionObserver !== "function") return
172
400
  this.seenWatch = new IntersectionObserver(
173
401
  (entries) => {
174
402
  for (const entry of entries) {
175
- const id = entry.target.id.replace(/^comment-/, "");
176
- const screen = entry.rootBounds?.height ?? innerHeight;
177
- const shown = entry.isIntersecting && (entry.intersectionRatio >= 0.5 || entry.intersectionRect.height >= screen / 2);
403
+ const id = entry.target.id.replace(/^comment-/, "")
404
+ const screen = entry.rootBounds?.height ?? innerHeight
405
+ const shown =
406
+ entry.isIntersecting && (entry.intersectionRatio >= 0.5 || entry.intersectionRect.height >= screen / 2)
178
407
  if (!shown) {
179
- clearTimeout(this.seenTimers.get(id));
180
- this.seenTimers.delete(id);
408
+ clearTimeout(this.seenTimers.get(id))
409
+ this.seenTimers.delete(id)
181
410
  } else if (!this.seenTimers.has(id))
182
411
  this.seenTimers.set(
183
412
  id,
184
413
  setTimeout(() => {
185
- this.seenTimers.delete(id);
186
- if (document.visibilityState === "visible") this.markSeen(id);
187
- else this.watchSeen();
414
+ this.seenTimers.delete(id)
415
+ if (document.visibilityState === "visible") this.markSeen(id)
416
+ else this.watchSeen()
188
417
  }, SEEN_MS)
189
- );
418
+ )
190
419
  }
191
420
  },
192
421
  { threshold: [0, 0.25, 0.5, 0.75, 1] }
193
- );
194
- for (const each of threads) this.seenWatch.observe(each);
422
+ )
423
+ for (const each of threads) this.seenWatch.observe(each)
195
424
  }
425
+
196
426
  /**
197
427
  * Keep a corner bullhorn off a thread's buttons (Owen, 2026-10-10: "Overlap in bullhorn buttons").
198
428
  * - a block with no title row has its bullhorn over its top right corner, in its actions row
@@ -206,36 +436,45 @@ var PageComments = class {
206
436
  * and an update's left of its date.
207
437
  */
208
438
  makeRoom() {
209
- alignBlockActions(this.main);
210
- const horns = [...this.main.querySelectorAll(`${BLOCK_ROW} ui-button`)].filter((each) => each?.checkVisibility?.({ contentVisibilityAuto: true }) !== false).map((each) => each?.getBoundingClientRect()).filter((rect) => rect?.width);
439
+ alignBlockActions(this.main)
440
+ const horns = [...this.main.querySelectorAll(`${BLOCK_ROW} ui-button`)]
441
+ .filter((each) => each?.checkVisibility?.({ contentVisibilityAuto: true }) !== false)
442
+ .map((each) => each?.getBoundingClientRect())
443
+ .filter((rect) => rect?.width)
211
444
  for (const thread of this.threads.values()) {
212
- thread.style.removeProperty(HEAD_ROOM);
213
- const head = thread.isConnected ? thread.header : void 0;
214
- if (!head) continue;
215
- const box = head.getBoundingClientRect();
216
- if (!box.width || head.checkVisibility?.({ contentVisibilityAuto: true }) === false) continue;
445
+ thread.style.removeProperty(HEAD_ROOM)
446
+ // not drawn yet (the pack still loading): a resize comes once it is
447
+ const head = thread.isConnected ? thread.header : undefined
448
+ if (!head) continue
449
+ const box = head.getBoundingClientRect()
450
+ // hidden (a folded part's, `until-found`): its place means nothing until it shows, and that's a resize
451
+ if (!box.width || head.checkVisibility?.({ contentVisibilityAuto: true }) === false) continue
217
452
  const over = horns.filter(
218
453
  (rect) => rect.left < box.right && rect.right > box.left && rect.top < box.bottom && rect.bottom > box.top
219
- );
454
+ )
220
455
  if (over.length)
221
- thread.style.setProperty(HEAD_ROOM, `${Math.ceil(box.right - Math.min(...over.map((r) => r.left))) + 4}px`);
456
+ thread.style.setProperty(HEAD_ROOM, `${Math.ceil(box.right - Math.min(...over.map((r) => r.left))) + 4}px`)
222
457
  }
223
458
  }
459
+
224
460
  /** Fetch the page's comments; resolves to whether the page takes comments. NEVER throws. */
225
461
  async load() {
226
462
  try {
227
- const answer = await ServerLink.forPage().get(COMMENTS_API, { query: { page: location.pathname }, missing: {} });
228
- if (answer.takesComments !== true) return false;
229
- this.list = ThreadFacts.withTurns(answer.comments);
230
- this.keepSend(answer);
231
- return true;
463
+ // the page now: Epic UI's router swaps pages under one link
464
+ const answer = await ServerLink.forPage().get(COMMENTS_API, { query: { page: location.pathname }, missing: {} })
465
+ if (answer.takesComments !== true) return false
466
+ this.list = ThreadFacts.withTurns(answer.comments)
467
+ this.keepSend(answer)
468
+ return true
232
469
  } catch {
233
- return false;
470
+ return false
234
471
  }
235
472
  }
473
+
236
474
  ////////////////
237
475
  // ## Send
238
476
  ////////////////
477
+
239
478
  /**
240
479
  * Keep a docs page's Send state from a comments route's answer:
241
480
  * `send`, `{ epic, owned, wakes, listening, sent, unsent, waiting }` (`commentsRoutes.ts` `PageSend`).
@@ -243,11 +482,12 @@ var PageComments = class {
243
482
  * - the epic's review inbox joins the files whose change redraws the page: who is listening is in it
244
483
  */
245
484
  keepSend(answer) {
246
- if (!answer?.send) return;
247
- this.send = answer.send;
248
- const inbox = `/epics/${answer.send.epic}/${answer.send.epic}.inbox.json5`;
249
- for (const path of inboxPathsOf(inbox)) if (!this.inboxPaths.includes(path)) this.inboxPaths.push(path);
485
+ if (!answer?.send) return
486
+ this.send = answer.send
487
+ const inbox = `/epics/${answer.send.epic}/${answer.send.epic}.inbox.json5`
488
+ for (const path of inboxPathsOf(inbox)) if (!this.inboxPaths.includes(path)) this.inboxPaths.push(path)
250
489
  }
490
+
251
491
  /**
252
492
  * The page header's SEND (epic `epic-workflow` P13): a docs page's comments go to the session of the epic the page
253
493
  * belongs to, as an epic page's do with its Send.
@@ -264,43 +504,55 @@ var PageComments = class {
264
504
  * - drawn again with the comments; none on an epic page, or from a server without it
265
505
  */
266
506
  drawSend() {
267
- const sticky = pageHeadIn(this.main);
268
- const head = sticky?.matches(".spell-page-head") ? sticky : sticky?.querySelector(".spell-page-head") ?? sticky;
269
- head?.querySelector(":scope > .spell-send, :scope > .spell-head-tools > .spell-send")?.remove();
270
- const send = this.send;
271
- if (!head || !send) return;
272
- const unsent = send.unsent.length;
273
- const state = unsent ? "unsent" : send.waiting.length ? "sent" : "idle";
274
- const button = el(SEND_BUTTONS_TAG, { state, count: unsent || void 0, "send-tip": sendWords(send, state) });
275
- button.addEventListener(SEND_ASKED, () => void this.sendNow());
507
+ const sticky = pageHeadIn(this.main)
508
+ const head = sticky?.matches(".spell-page-head") ? sticky : (sticky?.querySelector(".spell-page-head") ?? sticky)
509
+ head?.querySelector(":scope > .spell-send, :scope > .spell-head-tools > .spell-send")?.remove()
510
+ const send = this.send
511
+ if (!head || !send) return
512
+ const unsent = send.unsent.length
513
+ const state = unsent ? "unsent" : send.waiting.length ? "sent" : "idle"
514
+ const button = el(SEND_BUTTONS_TAG, { state, count: unsent || undefined, "send-tip": sendWords(send, state) })
515
+ button.addEventListener(SEND_ASKED, () => void this.sendNow())
276
516
  const who = el(
277
517
  "span",
278
518
  { class: "spell-send-who", "data-listening": send.listening ? "yes" : "no", title: whoWords(send) },
279
519
  whoLabel(send)
280
- );
520
+ )
521
+ // the header's tools row, first (`addHeadTool()`)
281
522
  addHeadTool(
282
523
  head,
283
524
  el("span", { class: "spell-send", "data-spell-added": true, "data-state": state }, button, who),
284
525
  "send"
285
- );
526
+ )
286
527
  }
528
+
287
529
  /** Send, clicked: every comment waiting so far goes to the page's epic; a toast says so. NEVER throws. */
288
530
  async sendNow() {
289
- const send = this.send;
290
- if (!send) return;
291
- if (!send.unsent.length) return noteToast("Nothing new to send: every comment here went with an earlier Send.");
531
+ const send = this.send
532
+ if (!send) return
533
+ if (!send.unsent.length) return noteToast("Nothing new to send: every comment here went with an earlier Send.")
292
534
  try {
293
- const answer = await ServerLink.forPage().post(`${COMMENTS_API}/send`, { page: location.pathname });
294
- this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list;
295
- this.keepSend(answer);
296
- const count = `${send.unsent.length} comment${send.unsent.length === 1 ? "" : "s"}`;
297
- const later = this.send.listening ? "" : answer.wake?.message ? `. ${answer.wake.message.replace(/\.$/, "")}` : !send.wakes ? `: nobody is listening, so /airplane land gathers them into ${send.epic}` : `: nobody is listening, so they wait for /epic review ${send.epic}`;
298
- noteToast(`Sent ${count} to ${send.epic}${later}.`, later ? "warning" : "success");
299
- this.draw();
535
+ const answer = await ServerLink.forPage().post(`${COMMENTS_API}/send`, { page: location.pathname })
536
+ this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list
537
+ this.keepSend(answer)
538
+ const count = `${send.unsent.length} comment${send.unsent.length === 1 ? "" : "s"}`
539
+ // nobody listening: the server woke the epic and says what it did
540
+ // (P16; a page no epic owns: `feedback`, epic `epic-engine` T9);
541
+ // else they wait for its review, or (`feedback` not made yet) for /airplane land
542
+ const later = this.send.listening
543
+ ? ""
544
+ : answer.wake?.message
545
+ ? `. ${answer.wake.message.replace(/\.$/, "")}`
546
+ : !send.wakes
547
+ ? `: nobody is listening, so /airplane land gathers them into ${send.epic}`
548
+ : `: nobody is listening, so they wait for /epic review ${send.epic}`
549
+ noteToast(`Sent ${count} to ${send.epic}${later}.`, later ? "warning" : "success")
550
+ this.draw()
300
551
  } catch (error) {
301
- noteToast(`Couldn't send: ${error.message}`, "error");
552
+ noteToast(`Couldn't send: ${error.message}`, "error")
302
553
  }
303
554
  }
555
+
304
556
  /**
305
557
  * Draw it all again: every bullhorn, every comment's thread, the quotes' highlight.
306
558
  * - a thread goes under the paragraph (list item, cell ...) holding its quote, else under its block (`holderOf()`),
@@ -312,95 +564,113 @@ var PageComments = class {
312
564
  * - a thread that had to move takes back the cursor it had: in its box (the selection kept), or on its fold
313
565
  */
314
566
  draw() {
315
- const { main } = this;
316
- const field = this.fields().find((each) => document.activeElement === each.field)?.field;
317
- const [start, end] = field ? [field.selectionStart, field.selectionEnd] : [0, 0];
318
- const onFold = [...this.threads.values()].find((each) => each.isFoldFocused);
319
- this.read = readJSON(this.readKey);
320
- const blocks = blocksIn(main);
321
- const head = pageHeadIn(main);
322
- const wanted = new Set(head ? [head, ...blocks] : blocks);
323
- const kept = /* @__PURE__ */ new Set();
567
+ const { main } = this
568
+ const field = this.fields().find((each) => document.activeElement === each.field)?.field
569
+ const [start, end] = field ? [field.selectionStart, field.selectionEnd] : [0, 0]
570
+ const onFold = [...this.threads.values()].find((each) => each.isFoldFocused)
571
+ this.read = readJSON(this.readKey)
572
+ const blocks = blocksIn(main)
573
+ const head = pageHeadIn(main)
574
+ // the bullhorns KEPT where they still stand (epic `epic-engine` P28): taking down and redrawing every one, on
575
+ // every inbox change, poll and patch, redrew each item's title row under Owen's cursor
576
+ const wanted = new Set(head ? [head, ...blocks] : blocks)
577
+ const kept = new Set()
324
578
  for (const old of main.querySelectorAll(".spell-comment-mark")) {
325
- const block = bullhornBlocks.get(old);
326
- if (block && wanted.has(block) && !kept.has(block) && standsBy(old, block)) kept.add(block);
327
- else dropBlockAction(old);
579
+ const block = bullhornBlocks.get(old)
580
+ if (block && wanted.has(block) && !kept.has(block) && standsBy(old, block)) kept.add(block)
581
+ else dropBlockAction(old)
328
582
  }
329
- const groups = /* @__PURE__ */ new Map();
330
- const quotes = [];
583
+ const groups = new Map()
584
+ const quotes = []
331
585
  for (const comment of this.list) {
332
- const { block, exact } = findBlock(main, comment, blocks);
333
- const at = block ?? head;
334
- if (!at) continue;
335
- const quoted = block && comment.quote && quoteIn(block, comment.quote, comment.offset);
336
- if (quoted) quotes.push({ ...quoted, id: comment.id, waiting: comment.turn === "agent" });
337
- if (this.open?.id === comment.id) continue;
338
- const under = quoted ? holderOf(block, quoted) : at;
339
- if (!groups.has(under)) groups.set(under, []);
340
- groups.get(under).push({ comment, exact: exact && Boolean(block) });
586
+ const { block, exact } = findBlock(main, comment, blocks)
587
+ const at = block ?? head
588
+ if (!at) continue
589
+ const quoted = block && comment.quote && quoteIn(block, comment.quote, comment.offset)
590
+ if (quoted) quotes.push({ ...quoted, id: comment.id, waiting: comment.turn === "agent" })
591
+ if (this.open?.id === comment.id) continue
592
+ const under = quoted ? holderOf(block, quoted) : at
593
+ if (!groups.has(under)) groups.set(under, [])
594
+ groups.get(under).push({ comment, exact: exact && Boolean(block) })
341
595
  }
342
- const ids = new Set(this.list.map((each) => each.id));
343
- if (this.editing && !ids.has(this.editing.id)) this.editing = null;
344
- for (const id of this.replyBoxes.keys()) if (!ids.has(id)) this.replyBoxes.delete(id);
596
+ const ids = new Set(this.list.map((each) => each.id))
597
+ if (this.editing && !ids.has(this.editing.id)) this.editing = null
598
+ for (const id of this.replyBoxes.keys()) if (!ids.has(id)) this.replyBoxes.delete(id)
599
+ // gone, or being written in the pane again: no thread
345
600
  for (const [id, thread] of this.threads)
346
601
  if (!ids.has(id) || this.open?.id === id) {
347
- thread.remove();
348
- this.threads.delete(id);
602
+ thread.remove()
603
+ this.threads.delete(id)
349
604
  }
350
- for (const block of wanted) if (!kept.has(block)) this.addBullhorn(block);
351
- this.drawSend();
352
- const boxes = /* @__PURE__ */ new Map();
605
+ for (const block of wanted) if (!kept.has(block)) this.addBullhorn(block)
606
+ this.drawSend()
607
+ const boxes = new Map()
353
608
  for (const [under, found] of groups) {
354
- const box = this.boxFor(under);
355
- boxes.set(box, found.length);
356
- found.forEach((each, at) => placeAt(box, this.thread(each), at));
609
+ const box = this.boxFor(under)
610
+ boxes.set(box, found.length)
611
+ found.forEach((each, at) => placeAt(box, this.thread(each), at))
357
612
  }
358
- for (const [box, count] of boxes) while (box.children.length > count) box.lastElementChild.remove();
359
- for (const old of main.querySelectorAll(`${THREADS_TAG}[data-spell-added]`)) if (!boxes.has(old)) old.remove();
360
- this.quotes = highlightQuotes(quotes);
361
- this.makeRoom();
362
- this.watchSeen();
363
- this.drawWaiting();
364
- this.drawPromoted();
365
- requestAnimationFrame(() => this.growFields());
366
- if (onFold?.isConnected && !onFold.isFoldFocused) onFold.focusFold();
367
- if (!field?.isConnected || document.activeElement === field) return;
368
- field.focus({ preventScroll: true });
369
- field.setSelectionRange(start, end);
613
+ // what's left in a box after its threads moved on, and the boxes no block has now
614
+ for (const [box, count] of boxes) while (box.children.length > count) box.lastElementChild.remove()
615
+ for (const old of main.querySelectorAll(`${THREADS_TAG}[data-spell-added]`)) if (!boxes.has(old)) old.remove()
616
+ this.quotes = highlightQuotes(quotes)
617
+ this.makeRoom()
618
+ this.watchSeen()
619
+ this.drawWaiting()
620
+ this.drawPromoted()
621
+ // grown to their words once shown: a thread just opened draws its box on the next frame
622
+ requestAnimationFrame(() => this.growFields())
623
+ if (onFold?.isConnected && !onFold.isFoldFocused) onFold.focusFold()
624
+ if (!field?.isConnected || document.activeElement === field) return
625
+ field.focus({ preventScroll: true })
626
+ field.setSelectionRange(start, end)
370
627
  }
628
+
371
629
  /** Every box in an open thread as tall as its words (`growField()`): a folded thread's has no height to measure. */
372
630
  growFields() {
373
- for (const replying of this.fields()) if (replying.field.getClientRects().length) growField(replying.field);
631
+ for (const replying of this.fields()) if (replying.field.getClientRects().length) growField(replying.field)
374
632
  }
633
+
375
634
  ////////////////
376
635
  // ## Jumping to the threads waiting on Owen
377
636
  ////////////////
637
+
378
638
  /** The comments waiting on Owen: Claude spoke last on their threads (`turn` `person`). */
379
639
  get waitingOnOwen() {
380
- return this.list.filter((comment) => comment.turn === "person");
640
+ return this.list.filter((comment) => comment.turn === "person")
381
641
  }
642
+
382
643
  /** The comments waiting on Owen whose threads are drawn, in page order. */
383
644
  waitingInPageOrder() {
384
- return this.inPageOrder(this.waitingOnOwen);
645
+ return this.inPageOrder(this.waitingOnOwen)
385
646
  }
647
+
386
648
  /** What the toolbar's bullhorn goes through: the threads waiting on Owen, else every open one, in page order. */
387
649
  jumpTargets() {
388
- const waiting = this.waitingInPageOrder();
389
- return waiting.length ? waiting : this.inPageOrder(this.list.filter((comment) => !comment.done));
650
+ const waiting = this.waitingInPageOrder()
651
+ return waiting.length ? waiting : this.inPageOrder(this.list.filter((comment) => !comment.done))
390
652
  }
653
+
391
654
  /** `comments` whose threads are drawn, folded sections' too, in page order. */
392
655
  inPageOrder(comments) {
393
- return comments.map((comment) => ({ comment, thread: this.threadOf(comment.id) })).filter((each) => each.thread).sort((a, b) => a.thread.compareDocumentPosition(b.thread) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1).map((each) => each.comment);
656
+ return comments
657
+ .map((comment) => ({ comment, thread: this.threadOf(comment.id) }))
658
+ .filter((each) => each.thread)
659
+ .sort((a, b) => (a.thread.compareDocumentPosition(b.thread) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1))
660
+ .map((each) => each.comment)
394
661
  }
662
+
395
663
  /** Comment `id`'s thread, if drawn. */
396
664
  threadOf(id) {
397
- return this.main.querySelector(`#comment-${CSS.escape(id)}`);
665
+ return this.main.querySelector(`#comment-${CSS.escape(id)}`)
398
666
  }
667
+
399
668
  /** The comment with id `typed` (`C3`, `c3`, the old `cm3`, a `#` aside), else `undefined`. */
400
669
  find(typed) {
401
- const number = ThreadFacts.numberOf(typed);
402
- return number === void 0 ? void 0 : this.list.find((each) => ThreadFacts.numberOf(each.id) === number);
670
+ const number = ThreadFacts.numberOf(typed)
671
+ return number === undefined ? undefined : this.list.find((each) => ThreadFacts.numberOf(each.id) === number)
403
672
  }
673
+
404
674
  /**
405
675
  * The toolbar's BULLHORN: at the right of the page's toolbar (`.spell-toolbar`, an epic page's and a guide's alike),
406
676
  * an orange count of the threads waiting on Owen; none waiting, no count, and it jumps through the open threads;
@@ -414,61 +684,70 @@ var PageComments = class {
414
684
  * - where it goes: `waitingHome()`, the one place to change to move it
415
685
  */
416
686
  drawWaiting() {
417
- const home = this.waitingHome();
418
- if (!home) return;
419
- let bullhorn = home.querySelector(":scope > .spell-toolbar-waiting");
687
+ const home = this.waitingHome()
688
+ if (!home) return
689
+ let bullhorn = home.querySelector(":scope > .spell-toolbar-waiting")
420
690
  if (!bullhorn) {
421
- const count2 = el("ui-label", {
691
+ const count = el("ui-label", {
422
692
  class: "spell-toolbar-count replied",
423
693
  slot: "badge",
424
694
  appearance: "circular",
425
695
  size: "mini"
426
- });
427
- bullhorn = home.matches(".spell-toolbar-tools") ? el(
428
- "span",
429
- { class: "spell-toolbar-waiting", hidden: true },
430
- el("ui-button", { appearance: "circular basic", size: "mini", icon: "bullhorn" }),
431
- count2
432
- ) : el(
433
- "ui-item",
434
- { class: "spell-toolbar-item spell-toolbar-waiting", appearance: "link", icon: "bullhorn", hidden: true },
435
- count2
436
- );
437
- bullhorn.addEventListener("click", () => this.nextWaiting());
696
+ })
697
+ bullhorn = home.matches(".spell-toolbar-tools")
698
+ ? el(
699
+ "span",
700
+ { class: "spell-toolbar-waiting", hidden: true },
701
+ el("ui-button", { appearance: "circular basic", size: "mini", icon: "bullhorn" }),
702
+ count
703
+ )
704
+ : el(
705
+ "ui-item",
706
+ { class: "spell-toolbar-item spell-toolbar-waiting", appearance: "link", icon: "bullhorn", hidden: true },
707
+ count
708
+ )
709
+ bullhorn.addEventListener("click", () => this.nextWaiting())
438
710
  }
439
- if (home.lastElementChild !== bullhorn) home.append(bullhorn);
440
- const count = this.waitingInPageOrder().length;
441
- const open = this.jumpTargets().length;
442
- const jumps = count ? `${count} ${count === 1 ? "thread waits" : "threads wait"} on you: jump to the next` : `${open} ${open === 1 ? "comment" : "comments"}: jump to the next`;
443
- const edits = document.querySelector("ui-markdown[editable]:not([editable=tabs])");
444
- const tip = edits ? `${jumps}. ⌥-click text to edit it` : jumps;
445
- const badge = bullhorn.querySelector(".spell-toolbar-count");
446
- badge.textContent = String(count);
447
- badge.hidden = !count;
448
- bullhorn.title = tip;
449
- bullhorn.setAttribute("aria-label", tip);
450
- if (bullhorn.localName === "ui-item") titleInside(bullhorn, "item");
451
- bullhorn.hidden = !open;
711
+ if (home.lastElementChild !== bullhorn) home.append(bullhorn)
712
+ const count = this.waitingInPageOrder().length
713
+ const open = this.jumpTargets().length
714
+ const jumps = count
715
+ ? `${count} ${count === 1 ? "thread waits" : "threads wait"} on you: jump to the next`
716
+ : `${open} ${open === 1 ? "comment" : "comments"}: jump to the next`
717
+ // a page whose markdown is edited in place says how (epic `epic-engine` P60): ⌥ is the only way in
718
+ const edits = document.querySelector("ui-markdown[editable]:not([editable=tabs])")
719
+ const tip = edits ? `${jumps}. ⌥-click text to edit it` : jumps
720
+ const badge = bullhorn.querySelector(".spell-toolbar-count")
721
+ badge.textContent = String(count)
722
+ badge.hidden = !count
723
+ bullhorn.title = tip
724
+ bullhorn.setAttribute("aria-label", tip)
725
+ if (bullhorn.localName === "ui-item") titleInside(bullhorn, "item")
726
+ // a guide's titles share the row with it: its menu fits them again (`<ui-toolbar shrinkable>`)
727
+ bullhorn.hidden = !open
452
728
  }
729
+
453
730
  /**
454
731
  * Where the toolbar's bullhorn goes: the page's toolbar (`.spell-toolbar`, Spell UI's menu), last in its row,
455
732
  * after a page's own tools there (the spell syntax guide's Expand all and Collapse all); none without a toolbar.
456
733
  */
457
734
  waitingHome() {
458
- const toolbar = document.querySelector(".spell-toolbar");
459
- return toolbarTools(toolbar) ?? toolbar;
735
+ const toolbar = document.querySelector(".spell-toolbar")
736
+ return toolbarTools(toolbar) ?? toolbar
460
737
  }
738
+
461
739
  /**
462
740
  * The toolbar's bullhorn, clicked: land on the next of `jumpTargets()` after the one it last landed on, in
463
741
  * page order; after the last, the first again.
464
742
  * - a thread in a folded section: landing unfolds it (`landOn()`)
465
743
  */
466
744
  nextWaiting() {
467
- const waiting = this.jumpTargets();
468
- if (!waiting.length) return;
469
- const at = waiting.findIndex((each) => each.id === this.lastWaiting);
470
- void this.landOn(waiting[(at + 1) % waiting.length].id);
745
+ const waiting = this.jumpTargets()
746
+ if (!waiting.length) return
747
+ const at = waiting.findIndex((each) => each.id === this.lastWaiting)
748
+ void this.landOn(waiting[(at + 1) % waiting.length].id)
471
749
  }
750
+
472
751
  /**
473
752
  * Land on comment `id`'s thread, opened, then the focus to its header without scrolling.
474
753
  * - as a link to it would (`go()`): what hides it unfolds, it lands below the stuck titles,
@@ -476,19 +755,21 @@ var PageComments = class {
476
755
  * - seen (`markSeen()`)
477
756
  */
478
757
  async landOn(id) {
479
- if (!this.list.some((each) => each.id === id)) return;
480
- this.lastWaiting = id;
481
- this.folds.set(id, true);
482
- this.draw();
483
- this.markSeen(id);
484
- const anchor = `comment-${id}`;
485
- if (this.go) await this.go(anchor);
486
- else document.getElementById(anchor)?.scrollIntoView({ block: "start" });
487
- this.threadOf(id)?.focusFold?.();
758
+ if (!this.list.some((each) => each.id === id)) return
759
+ this.lastWaiting = id
760
+ this.folds.set(id, true)
761
+ this.draw()
762
+ this.markSeen(id)
763
+ const anchor = `comment-${id}`
764
+ if (this.go) await this.go(anchor)
765
+ else document.getElementById(anchor)?.scrollIntoView({ block: "start" })
766
+ this.threadOf(id)?.focusFold?.()
488
767
  }
768
+
489
769
  ////////////////
490
770
  // ## Comments promoted past their folds
491
771
  ////////////////
772
+
492
773
  /**
493
774
  * Each open comment in a folded section, PROMOTED: a row right after the outermost fold hiding it, so it shows.
494
775
  * - Owen, 2026-11-01: "Comments should be promoted to be visible when their sections are collapsed"
@@ -496,128 +777,140 @@ var PageComments = class {
496
777
  * - rows are redrawn only when what they say changes
497
778
  */
498
779
  drawPromoted() {
499
- if (!this.pageFolds) return;
500
- const wanted = /* @__PURE__ */ new Map();
780
+ if (!this.pageFolds) return
781
+ const wanted = new Map()
501
782
  for (const comment of this.inPageOrder(this.list.filter((each) => !each.done))) {
502
- const fold = this.pageFolds.outermostFolded(this.threadOf(comment.id));
503
- if (!fold) continue;
504
- if (!wanted.has(fold)) wanted.set(fold, []);
505
- wanted.get(fold).push(comment);
783
+ const fold = this.pageFolds.outermostFolded(this.threadOf(comment.id))
784
+ if (!fold) continue
785
+ if (!wanted.has(fold)) wanted.set(fold, [])
786
+ wanted.get(fold).push(comment)
506
787
  }
507
788
  for (const old of this.main.querySelectorAll(`.${PROMOTED}`))
508
- if (!wanted.has(old.previousElementSibling)) old.remove();
789
+ if (!wanted.has(old.previousElementSibling)) old.remove()
509
790
  for (const [fold, comments] of wanted) {
510
- let box = fold.nextElementSibling;
791
+ let box = fold.nextElementSibling
511
792
  if (!box?.classList.contains(PROMOTED)) {
512
- box = el("div", { class: PROMOTED, "data-spell-added": true });
513
- fold.after(box);
793
+ box = el("div", { class: PROMOTED, "data-spell-added": true })
794
+ fold.after(box)
514
795
  }
515
- const key = comments.map((each) => `${each.id}:${each.turn}:${ThreadFacts.headline(each)}`).join("|");
796
+ const key = comments.map((each) => `${each.id}:${each.turn}:${ThreadFacts.headline(each)}`).join("|")
516
797
  if (box.dataset.shows !== key) {
517
- box.dataset.shows = key;
518
- box.replaceChildren(...comments.map((each) => this.promotedRow(each)));
798
+ box.dataset.shows = key
799
+ box.replaceChildren(...comments.map((each) => this.promotedRow(each)))
519
800
  }
520
801
  }
521
802
  }
803
+
522
804
  /** One comment's row: a button with its bullhorn, its id and its first words. */
523
805
  promotedRow(comment) {
524
- const id = `C${ThreadFacts.numberOf(comment.id)}`;
806
+ const id = `C${ThreadFacts.numberOf(comment.id)}`
525
807
  const row = el(
526
808
  "button",
527
809
  { type: "button", class: `${PROMOTED}-row`, title: `${id}: show this comment` },
528
810
  el("ui-icon", { name: "bullhorn" }),
529
811
  el("b", {}, id),
530
812
  el("span", {}, ThreadFacts.headline(comment))
531
- );
532
- row.classList.toggle("waiting", comment.turn === "person");
533
- row.addEventListener("click", () => this.showPromoted(comment.id, row));
534
- return row;
813
+ )
814
+ row.classList.toggle("waiting", comment.turn === "person")
815
+ row.addEventListener("click", () => this.showPromoted(comment.id, row))
816
+ return row
535
817
  }
818
+
536
819
  /**
537
820
  * A promoted row clicked: open the sections its thread needs, and only those, with the thread where the row was.
538
821
  * - no visible scroll: the folds open at once, and the page moves in the same frame
539
822
  * - held for a few frames, as what's opened settles
540
823
  */
541
824
  async showPromoted(id, row) {
542
- const top = row.getBoundingClientRect().top;
543
- this.lastWaiting = id;
544
- this.folds.set(id, true);
545
- this.draw();
546
- this.markSeen(id);
547
- const thread = this.threadOf(id);
548
- if (!thread) return;
549
- this.pageFolds.reveal(thread, { self: true });
825
+ const top = row.getBoundingClientRect().top
826
+ this.lastWaiting = id
827
+ this.folds.set(id, true)
828
+ this.draw()
829
+ this.markSeen(id)
830
+ const thread = this.threadOf(id)
831
+ if (!thread) return
832
+ this.pageFolds.reveal(thread, { self: true })
550
833
  for (let frame = 0; frame < SHOW_FRAMES; frame++) {
551
- scrollBy({ top: thread.getBoundingClientRect().top - top, behavior: "instant" });
552
- await nextFrame(1);
834
+ scrollBy({ top: thread.getBoundingClientRect().top - top, behavior: "instant" })
835
+ await nextFrame(1)
553
836
  }
554
- history.replaceState(history.state, "", `#comment-${id}`);
555
- thread.focusFold?.();
837
+ history.replaceState(history.state, "", `#comment-${id}`)
838
+ thread.focusFold?.()
556
839
  }
840
+
557
841
  /** Promoted rows follow the folds: a section opened or folded, by any route. */
558
842
  watchFolds() {
559
- if (!this.pageFolds) return;
560
- let queued = false;
843
+ if (!this.pageFolds) return
844
+ let queued = false
561
845
  this.foldWatch = new MutationObserver((records) => {
562
- if (queued || records.every((record) => record.target.localName === THREAD_TAG)) return;
563
- queued = true;
846
+ if (queued || records.every((record) => record.target.localName === THREAD_TAG)) return
847
+ queued = true
564
848
  requestAnimationFrame(() => {
565
- queued = false;
566
- this.drawPromoted();
567
- });
568
- });
569
- this.foldWatch.observe(this.main, { attributes: true, attributeFilter: ["open", "class"], subtree: true });
849
+ queued = false
850
+ this.drawPromoted()
851
+ })
852
+ })
853
+ this.foldWatch.observe(this.main, { attributes: true, attributeFilter: ["open", "class"], subtree: true })
570
854
  }
855
+
571
856
  /** Every reply box there is: each thread's (`replyBoxes`), and the pen's (`editing`). */
572
857
  fields() {
573
- return [...this.replyBoxes.values(), ...this.editing ? [this.editing] : []];
858
+ return [...this.replyBoxes.values(), ...(this.editing ? [this.editing] : [])]
574
859
  }
860
+
575
861
  /**
576
862
  * Draw again when the page's own content changes: an epic page's part loads its blocks when it opens.
577
863
  * - changes inside what this adds (`data-spell-added`) don't count: drawing would wake it again
578
864
  */
579
865
  watchContent() {
580
- let timer = 0;
581
- const ours = /* @__PURE__ */ __name((node) => node.nodeType === 1 && (node.matches("[data-spell-added]") || node.closest("[data-spell-added]")), "ours");
866
+ let timer = 0
867
+ const ours = (node) =>
868
+ node.nodeType === 1 && (node.matches("[data-spell-added]") || node.closest("[data-spell-added]"))
582
869
  this.contentWatch = new MutationObserver((records) => {
583
870
  const theirs = records.some(
584
- (record) => !ours(record.target) && [...record.addedNodes, ...record.removedNodes].some((node) => node.nodeType === 1 && !ours(node))
585
- );
586
- if (!theirs) return;
587
- clearTimeout(timer);
588
- timer = setTimeout(() => this.draw(), REDRAW_MS);
589
- }).observe(this.main, { childList: true, subtree: true });
871
+ (record) =>
872
+ !ours(record.target) &&
873
+ [...record.addedNodes, ...record.removedNodes].some((node) => node.nodeType === 1 && !ours(node))
874
+ )
875
+ if (!theirs) return
876
+ clearTimeout(timer)
877
+ timer = setTimeout(() => this.draw(), REDRAW_MS)
878
+ }).observe(this.main, { childList: true, subtree: true })
879
+ // a `<ui-markdown>` drew its text: the quotes in it can be found now
590
880
  this.main.addEventListener(
591
881
  "ui-drawn",
592
882
  () => {
593
- clearTimeout(timer);
594
- timer = setTimeout(() => this.draw(), REDRAW_MS);
883
+ clearTimeout(timer)
884
+ timer = setTimeout(() => this.draw(), REDRAW_MS)
595
885
  },
596
886
  { signal: this.signal }
597
- );
598
- this.signal?.addEventListener("abort", () => clearTimeout(timer), { once: true });
887
+ )
888
+ this.signal?.addEventListener("abort", () => clearTimeout(timer), { once: true })
599
889
  }
890
+
600
891
  /**
601
892
  * Take down what this drew outside the page's content, and stop watching: the floating bullhorn (in `body`), the
602
893
  * open pane, the content and seen watchers, the seen timers (`wireComments()`'s `signal`).
603
894
  * - the page's `main` keeps the rest: it's on its way out
604
895
  */
605
896
  stop() {
606
- this.contentWatch?.disconnect();
607
- this.foldWatch?.disconnect();
608
- this.seenWatch?.disconnect();
609
- for (const timer of this.seenTimers.values()) clearTimeout(timer);
610
- this.seenTimers.clear();
611
- this.floating?.remove();
612
- this.floating = null;
613
- this.pane?.remove();
614
- this.pane = null;
615
- this.open = null;
616
- document.documentElement.classList.remove("spell-over-quote");
897
+ this.contentWatch?.disconnect()
898
+ this.foldWatch?.disconnect()
899
+ this.seenWatch?.disconnect()
900
+ for (const timer of this.seenTimers.values()) clearTimeout(timer)
901
+ this.seenTimers.clear()
902
+ this.floating?.remove()
903
+ this.floating = null
904
+ this.pane?.remove()
905
+ this.pane = null
906
+ this.open = null
907
+ document.documentElement.classList.remove("spell-over-quote")
617
908
  }
909
+
618
910
  ////////////////
619
911
  // ## Bullhorns
620
912
  ////////////////
913
+
621
914
  /**
622
915
  * The bullhorn of `block`, wherever its block keeps its own controls:
623
916
  * - a docs section's title (its `actions` slot)
@@ -633,39 +926,48 @@ var PageComments = class {
633
926
  * - Before, a block with comments showed "📢 N" always, its click listing them.
634
927
  */
635
928
  addBullhorn(block) {
636
- const place = this.placeOf(block);
637
- const what = place.kind === "page" ? "this page" : `this ${ThreadFacts.kindName(place.kind)}`;
638
- const tip = `Comment on ${what}`;
639
- const where = place.kind === "section" || place.kind === "page" ? place.kind : block.matches(TITLE_ROW_BLOCKS) ? "title" : "block";
640
- const button = iconButton("bullhorn", tip);
641
- const mark = el("span", { class: `spell-comment-mark at-${where}`, "data-spell-added": true }, button);
642
- bullhornBlocks.set(mark, block);
929
+ const place = this.placeOf(block)
930
+ const what = place.kind === "page" ? "this page" : `this ${ThreadFacts.kindName(place.kind)}`
931
+ const tip = `Comment on ${what}`
932
+ const where =
933
+ place.kind === "section" || place.kind === "page"
934
+ ? place.kind
935
+ : block.matches(TITLE_ROW_BLOCKS)
936
+ ? "title"
937
+ : "block"
938
+ const button = iconButton("bullhorn", tip)
939
+ const mark = el("span", { class: `spell-comment-mark at-${where}`, "data-spell-added": true }, button)
940
+ bullhornBlocks.set(mark, block)
643
941
  button.addEventListener("click", (event) => {
644
- event.stopPropagation();
645
- const now = this.placeOf(block);
646
- this.openBox({ key: now.anchor, place: now }, event.currentTarget.getBoundingClientRect());
647
- });
942
+ event.stopPropagation()
943
+ // where it is NOW: a kept bullhorn's block may have moved since it was drawn (an anchor is its place)
944
+ const now = this.placeOf(block)
945
+ this.openBox({ key: now.anchor, place: now }, event.currentTarget.getBoundingClientRect())
946
+ })
648
947
  if (where === "section" || where === "title") {
649
- mark.slot = "actions";
650
- block.append(mark);
948
+ mark.slot = "actions"
949
+ block.append(mark)
651
950
  } else if (where === "page") {
652
- const head = block.querySelector(".spell-page-head");
653
- if (head) addHeadTool(head, mark, "comment");
654
- else block.append(mark);
655
- } else addBlockAction(block, mark, "comment");
951
+ // in the page header's tools row, last (`addHeadTool()`): the toolbar stays its last row
952
+ const head = block.querySelector(".spell-page-head")
953
+ if (head) addHeadTool(head, mark, "comment")
954
+ else block.append(mark)
955
+ } else addBlockAction(block, mark, "comment")
656
956
  }
957
+
657
958
  /** Where `block` is, as a comment on it is saved: `{ anchor, kind, label, excerpt }` (`BlockAnchors.js`). */
658
959
  placeOf(block) {
659
- if (block === pageHeadIn(this.main)) return { anchor: PAGE_ANCHOR, kind: "page", label: "", excerpt: "" };
660
- const kind = kindOf(block);
661
- const section = kind === "section" || kind === "item" ? block : sectionOf(block, this.main);
960
+ if (block === pageHeadIn(this.main)) return { anchor: PAGE_ANCHOR, kind: "page", label: "", excerpt: "" }
961
+ const kind = kindOf(block)
962
+ const section = kind === "section" || kind === "item" ? block : sectionOf(block, this.main)
662
963
  return {
663
964
  anchor: anchorOf(block, this.main),
664
965
  kind,
665
966
  label: section ? sectionTitle(section) : "",
666
967
  excerpt: excerptOf(block)
667
- };
968
+ }
668
969
  }
970
+
669
971
  /**
670
972
  * The box of threads under `under` (a block, or the paragraph holding a quote: `holderOf()`):
671
973
  * an `<epic-threads>`, made on first use.
@@ -676,17 +978,23 @@ var PageComments = class {
676
978
  * - only one this code made (`data-spell-added`): never one a page writes as an example (Epic UI's)
677
979
  */
678
980
  boxFor(under) {
679
- if (hostOf(under)?.localName === "ui-markdown") return this.boxInMarkdown(under);
680
- const where = THREADS_FIRST.test(under.localName) ? "first" : HOLDS_INSIDE.test(under.localName) ? "last" : "after";
681
- const next = where === "first" ? firstContentChild(under) : where === "last" ? under.lastElementChild : under.nextElementSibling;
682
- if (next?.localName === THREADS_TAG && next.hasAttribute("data-spell-added")) return next;
683
- const box = el(THREADS_TAG, { "data-spell-added": true });
684
- if (where === "after") under.after(box);
685
- else if (where === "last") under.append(box);
686
- else if (next) next.before(box);
687
- else under.append(box);
688
- return box;
981
+ if (hostOf(under)?.localName === "ui-markdown") return this.boxInMarkdown(under)
982
+ const where = THREADS_FIRST.test(under.localName) ? "first" : HOLDS_INSIDE.test(under.localName) ? "last" : "after"
983
+ const next =
984
+ where === "first"
985
+ ? firstContentChild(under)
986
+ : where === "last"
987
+ ? under.lastElementChild
988
+ : under.nextElementSibling
989
+ if (next?.localName === THREADS_TAG && next.hasAttribute("data-spell-added")) return next
990
+ const box = el(THREADS_TAG, { "data-spell-added": true })
991
+ if (where === "after") under.after(box)
992
+ else if (where === "last") under.append(box)
993
+ else if (next) next.before(box)
994
+ else under.append(box)
995
+ return box
689
996
  }
997
+
690
998
  /**
691
999
  * The box of threads under `under`, text a `<ui-markdown>` drew in its shadow root.
692
1000
  * - the box is the element's light child, so the page finds its threads as any others;
@@ -694,24 +1002,26 @@ var PageComments = class {
694
1002
  * - a render takes the slots away: `ui-drawn` draws the comments again (`watchContent()`)
695
1003
  */
696
1004
  boxInMarkdown(under) {
697
- const host = hostOf(under);
698
- const inside = HOLDS_INSIDE.test(under.localName);
699
- const next = inside ? under.lastElementChild : under.nextElementSibling;
700
- let slot = next?.matches("slot[data-spell-added]") ? next : null;
1005
+ const host = hostOf(under)
1006
+ const inside = HOLDS_INSIDE.test(under.localName)
1007
+ const next = inside ? under.lastElementChild : under.nextElementSibling
1008
+ let slot = next?.matches("slot[data-spell-added]") ? next : null
701
1009
  if (!slot) {
702
- slot = el("slot", { name: `spell-threads-${++threadSlots}`, "data-spell-added": true });
703
- if (inside) under.append(slot);
704
- else under.after(slot);
1010
+ slot = el("slot", { name: `spell-threads-${++threadSlots}`, "data-spell-added": true })
1011
+ if (inside) under.append(slot)
1012
+ else under.after(slot)
705
1013
  }
706
- const box = host.querySelector(`:scope > [slot="${slot.name}"]`);
707
- if (box) return box;
708
- const made = el(THREADS_TAG, { slot: slot.name, "data-spell-added": true });
709
- host.append(made);
710
- return made;
1014
+ const box = host.querySelector(`:scope > [slot="${slot.name}"]`)
1015
+ if (box) return box
1016
+ const made = el(THREADS_TAG, { slot: slot.name, "data-spell-added": true })
1017
+ host.append(made)
1018
+ return made
711
1019
  }
1020
+
712
1021
  ////////////////
713
1022
  // ## Selected text
714
1023
  ////////////////
1024
+
715
1025
  /**
716
1026
  * Comment on selected text: ⌘ / Ctrl I, or the bullhorn floating beside the selection (`floatingBullhorn()`).
717
1027
  * - only a selection inside one of the page's blocks; never in a comment box or a field
@@ -720,145 +1030,155 @@ var PageComments = class {
720
1030
  * the pointer says so over one
721
1031
  */
722
1032
  wireSelection() {
723
- let timer = 0;
724
- const listening = { signal: this.signal };
1033
+ let timer = 0
1034
+ const listening = { signal: this.signal }
725
1035
  document.addEventListener(
726
1036
  "selectionchange",
727
1037
  () => {
728
- clearTimeout(timer);
729
- timer = setTimeout(() => this.showFloating(), 120);
1038
+ clearTimeout(timer)
1039
+ timer = setTimeout(() => this.showFloating(), 120)
730
1040
  },
731
1041
  listening
732
- );
1042
+ )
733
1043
  document.addEventListener(
734
1044
  "click",
735
1045
  (event) => {
736
- if (!getSelection()?.isCollapsed) return;
737
- if (event.target.closest?.("a, button, ui-button, input, textarea, [data-spell-added]")) return;
738
- const hit = this.quoteAt(event.clientX, event.clientY);
739
- if (hit) this.openComment(hit.id);
1046
+ if (!getSelection()?.isCollapsed) return
1047
+ if (event.target.closest?.("a, button, ui-button, input, textarea, [data-spell-added]")) return
1048
+ const hit = this.quoteAt(event.clientX, event.clientY)
1049
+ if (hit) this.openComment(hit.id)
740
1050
  },
741
1051
  listening
742
- );
743
- let pending = false;
1052
+ )
1053
+ let pending = false
744
1054
  document.addEventListener(
745
1055
  "pointermove",
746
1056
  (event) => {
747
- if (pending || !this.quotes.length) return;
748
- pending = true;
1057
+ if (pending || !this.quotes.length) return
1058
+ pending = true
749
1059
  requestAnimationFrame(() => {
750
- pending = false;
751
- document.documentElement.classList.toggle("spell-over-quote", !!this.quoteAt(event.clientX, event.clientY));
752
- });
1060
+ pending = false
1061
+ document.documentElement.classList.toggle("spell-over-quote", !!this.quoteAt(event.clientX, event.clientY))
1062
+ })
753
1063
  },
754
1064
  { passive: true, ...listening }
755
- );
756
- addEventListener("scroll", () => this.floating?.setAttribute("hidden", ""), { passive: true, ...listening });
1065
+ )
1066
+ addEventListener("scroll", () => this.floating?.setAttribute("hidden", ""), { passive: true, ...listening })
757
1067
  document.addEventListener(
758
1068
  "keydown",
759
1069
  (event) => {
760
1070
  if (!(event.metaKey || event.ctrlKey) || event.altKey || event.shiftKey || event.key.toLowerCase() !== "i")
761
- return;
762
- const selected = this.selected();
763
- if (!selected) return;
764
- event.preventDefault();
765
- this.commentOn(selected);
1071
+ return
1072
+ const selected = this.selected()
1073
+ if (!selected) return
1074
+ event.preventDefault()
1075
+ this.commentOn(selected)
766
1076
  },
767
1077
  listening
768
- );
769
- this.signal?.addEventListener("abort", () => clearTimeout(timer), { once: true });
1078
+ )
1079
+ this.signal?.addEventListener("abort", () => clearTimeout(timer), { once: true })
770
1080
  }
1081
+
771
1082
  /** The selection, when it's text in one of the page's blocks: `{ block, quote, offset, range }`; else `null`. */
772
1083
  selected() {
773
- const selection = getSelection();
774
- const range = selection && this.selectedRange(selection);
775
- if (!range || range.collapsed) return null;
776
- const start = range.startContainer;
777
- if (!holds(this.main, start)) return null;
778
- const element = start.nodeType === 1 ? start : start.parentElement;
779
- if (element?.closest("[data-spell-added], textarea, input")) return null;
780
- const block = blockAround(start, blocksIn(this.main));
781
- const quote = (selection.toString() || range.toString()).trim();
782
- if (!block || !quote) return null;
783
- return { block, quote, offset: offsetIn(block, start, range.startOffset), range };
1084
+ const selection = getSelection()
1085
+ const range = selection && this.selectedRange(selection)
1086
+ if (!range || range.collapsed) return null
1087
+ const start = range.startContainer
1088
+ if (!holds(this.main, start)) return null
1089
+ const element = start.nodeType === 1 ? start : start.parentElement
1090
+ if (element?.closest("[data-spell-added], textarea, input")) return null
1091
+ const block = blockAround(start, blocksIn(this.main))
1092
+ const quote = (selection.toString() || range.toString()).trim()
1093
+ if (!block || !quote) return null
1094
+ return { block, quote, offset: offsetIn(block, start, range.startOffset), range }
784
1095
  }
1096
+
785
1097
  /**
786
1098
  * The selection's range, its real nodes: inside a `<ui-markdown>`'s shadow root too, which `getRangeAt()` hides.
787
1099
  * - across two shadow roots: `null`, no one block holds it
788
1100
  */
789
1101
  selectedRange(selection) {
790
- if (!selection.rangeCount) return null;
791
- if (!selection.getComposedRanges) return selection.getRangeAt(0);
792
- const shadowRoots = [...this.main.querySelectorAll("ui-markdown")].flatMap((each) => each.shadowRoot ?? []);
793
- const [picked] = selection.getComposedRanges({ shadowRoots });
794
- if (!picked) return null;
795
- if (picked.startContainer.getRootNode() !== picked.endContainer.getRootNode()) return null;
796
- const range = document.createRange();
797
- range.setStart(picked.startContainer, picked.startOffset);
798
- range.setEnd(picked.endContainer, picked.endOffset);
799
- return range;
1102
+ if (!selection.rangeCount) return null
1103
+ if (!selection.getComposedRanges) return selection.getRangeAt(0)
1104
+ const shadowRoots = [...this.main.querySelectorAll("ui-markdown")].flatMap((each) => each.shadowRoot ?? [])
1105
+ const [picked] = selection.getComposedRanges({ shadowRoots })
1106
+ if (!picked) return null
1107
+ if (picked.startContainer.getRootNode() !== picked.endContainer.getRootNode()) return null
1108
+ const range = document.createRange()
1109
+ range.setStart(picked.startContainer, picked.startOffset)
1110
+ range.setEnd(picked.endContainer, picked.endOffset)
1111
+ return range
800
1112
  }
1113
+
801
1114
  /** Open the comment pane on the selection's block, its text quoted, just under the selection. */
802
1115
  commentOn({ block, quote, offset, range }) {
803
- this.floating?.setAttribute("hidden", "");
804
- const rects = range.getClientRects();
805
- const near = rects[rects.length - 1] ?? range.getBoundingClientRect();
806
- const place = { ...this.placeOf(block), quote: quote.slice(0, 2e3), offset };
807
- this.openBox({ key: `${place.anchor}~${offset}`, place }, near);
1116
+ this.floating?.setAttribute("hidden", "")
1117
+ const rects = range.getClientRects()
1118
+ const near = rects[rects.length - 1] ?? range.getBoundingClientRect()
1119
+ const place = { ...this.placeOf(block), quote: quote.slice(0, 2000), offset }
1120
+ this.openBox({ key: `${place.anchor}~${offset}`, place }, near)
808
1121
  }
1122
+
809
1123
  /** The quote under the point (`x`, `y`): `{ id, rect }`, the comment's id and the line hit; else `null`. */
810
1124
  quoteAt(x, y) {
811
1125
  for (const { id, range } of this.quotes) {
812
1126
  const rect = Array.from(range.getClientRects()).find(
813
1127
  (each) => x >= each.left && x <= each.right && y >= each.top && y <= each.bottom
814
- );
815
- if (rect) return { id, rect };
1128
+ )
1129
+ if (rect) return { id, rect }
816
1130
  }
817
- return null;
1131
+ return null
818
1132
  }
1133
+
819
1134
  /**
820
1135
  * Open comment `id`'s thread (a click on its quote), and take the focus to its
821
1136
  * header; the page scrolls only as far as it must to show it. Still being written in the pane: back into it.
822
1137
  */
823
1138
  openComment(id) {
824
- if (this.open?.id === id && this.pane) return this.focusPane();
825
- if (!this.list.some((each) => each.id === id)) return;
826
- this.folds.set(id, true);
827
- this.draw();
828
- this.markSeen(id);
829
- const thread = this.threadOf(id);
830
- thread?.header?.scrollIntoView({ block: "nearest" });
831
- thread?.focusFold?.();
1139
+ if (this.open?.id === id && this.pane) return this.focusPane()
1140
+ if (!this.list.some((each) => each.id === id)) return
1141
+ this.folds.set(id, true)
1142
+ this.draw()
1143
+ this.markSeen(id)
1144
+ const thread = this.threadOf(id)
1145
+ thread?.header?.scrollIntoView({ block: "nearest" })
1146
+ thread?.focusFold?.()
832
1147
  }
1148
+
833
1149
  /** Show the floating bullhorn beside a selection in a block; hide it otherwise. */
834
1150
  showFloating() {
835
- const selected = this.selected();
836
- const button = this.floatingBullhorn();
837
- if (!selected) return button.setAttribute("hidden", "");
838
- const rects = selected.range.getClientRects();
839
- const last = rects[rects.length - 1] ?? selected.range.getBoundingClientRect();
840
- button.style.left = `${Math.min(innerWidth - 36, last.right + 6)}px`;
841
- button.style.top = `${Math.max(4, last.top - 4)}px`;
842
- button.removeAttribute("hidden");
1151
+ const selected = this.selected()
1152
+ const button = this.floatingBullhorn()
1153
+ if (!selected) return button.setAttribute("hidden", "")
1154
+ const rects = selected.range.getClientRects()
1155
+ const last = rects[rects.length - 1] ?? selected.range.getBoundingClientRect()
1156
+ button.style.left = `${Math.min(innerWidth - 36, last.right + 6)}px`
1157
+ button.style.top = `${Math.max(4, last.top - 4)}px`
1158
+ button.removeAttribute("hidden")
843
1159
  }
1160
+
844
1161
  /** The floating bullhorn, made once (in `body`, outside `main`): a click comments on the selection. */
845
1162
  floatingBullhorn() {
846
- if (this.floating) return this.floating;
847
- const tip = `Comment on this text (${/Mac|iPhone|iPad/.test(navigator.platform) ? "⌘" : "Ctrl "}I)`;
848
- const button = iconButton("bullhorn", tip);
849
- button.classList.add("spell-comment-float");
850
- button.hidden = true;
851
- button.addEventListener("pointerdown", (event) => event.preventDefault());
1163
+ if (this.floating) return this.floating
1164
+ const tip = `Comment on this text (${/Mac|iPhone|iPad/.test(navigator.platform) ? "⌘" : "Ctrl "}I)`
1165
+ const button = iconButton("bullhorn", tip)
1166
+ button.classList.add("spell-comment-float")
1167
+ button.hidden = true
1168
+ // keep the selection: a press would otherwise clear it before the click
1169
+ button.addEventListener("pointerdown", (event) => event.preventDefault())
852
1170
  button.addEventListener("click", () => {
853
- const selected = this.selected();
854
- if (selected) this.commentOn(selected);
855
- });
856
- document.body.append(button);
857
- return this.floating = button;
1171
+ const selected = this.selected()
1172
+ if (selected) this.commentOn(selected)
1173
+ })
1174
+ document.body.append(button)
1175
+ return (this.floating = button)
858
1176
  }
1177
+
859
1178
  ////////////////
860
1179
  // ## Threads
861
1180
  ////////////////
1181
+
862
1182
  /**
863
1183
  * A comment's THREAD (Owen, 2026-10-10: "the entire comment thread should be in one collapsable/accordion pane"):
864
1184
  * its `<epic-thread>` (the epics pack), made on first use and kept for the visit, given what to show now.
@@ -872,34 +1192,38 @@ var PageComments = class {
872
1192
  * - `exact` false: its block changed or moved since, so it says what it was on
873
1193
  */
874
1194
  thread({ comment, exact }) {
875
- let thread = this.threads.get(comment.id);
1195
+ let thread = this.threads.get(comment.id)
876
1196
  if (!thread) {
877
- thread = el(THREAD_TAG, { id: `comment-${comment.id}` });
878
- this.wireThread(thread, comment.id);
879
- this.threads.set(comment.id, thread);
1197
+ thread = el(THREAD_TAG, { id: `comment-${comment.id}` })
1198
+ this.wireThread(thread, comment.id)
1199
+ this.threads.set(comment.id, thread)
880
1200
  }
881
- const editing = this.editing?.id === comment.id ? this.editing : null;
882
- const replying = editing ?? (comment.turn === "done" ? null : this.replyBoxFor(comment));
883
- const writing = !!replying && (replying.busy() || !!editing);
884
- if (comment.turn === "done") this.replyBoxes.delete(comment.id);
885
- const thinking = !!comment.working && comment.turn !== "done";
886
- const open = writing || (this.folds.get(comment.id) ?? (comment.turn === "person" || thinking));
887
- thread.comment = comment;
888
- thread.toggleAttribute("open", open);
889
- thread.toggleAttribute("unseen", this.unseen(comment));
890
- thread.toggleAttribute("moved", !exact);
891
- setOrDrop(thread, "boxed", editing ? "first" : replying?.saved() ? "pending" : void 0);
892
- this.showFloppy(thread, replying);
893
- const box = replying?.box;
1201
+ const editing = this.editing?.id === comment.id ? this.editing : null
1202
+ const replying = editing ?? (comment.turn === "done" ? null : this.replyBoxFor(comment))
1203
+ const writing = !!replying && (replying.busy() || !!editing)
1204
+ if (comment.turn === "done") this.replyBoxes.delete(comment.id)
1205
+ const thinking = !!comment.working && comment.turn !== "done"
1206
+ const open = writing || (this.folds.get(comment.id) ?? (comment.turn === "person" || thinking))
1207
+ thread.comment = comment
1208
+ thread.toggleAttribute("open", open)
1209
+ // orange while it has a reply from Claude Owen hasn't answered (`unseen()`): the whole thread, that reply stronger
1210
+ thread.toggleAttribute("unseen", this.unseen(comment))
1211
+ thread.toggleAttribute("moved", !exact)
1212
+ setOrDrop(thread, "boxed", editing ? "first" : replying?.saved() ? "pending" : undefined)
1213
+ this.showFloppy(thread, replying)
1214
+ // its box: the reply box, or the pen's; moved in only when it isn't there already (the cursor stays)
1215
+ const box = replying?.box
894
1216
  if (box ? thread.firstElementChild !== box || thread.childElementCount !== 1 : thread.childElementCount)
895
- thread.replaceChildren(...box ? [box] : []);
896
- return thread;
1217
+ thread.replaceChildren(...(box ? [box] : []))
1218
+ return thread
897
1219
  }
1220
+
898
1221
  /** Thread `thread`'s floppy, as Owen's box in it last saved (`replying.floppy`): none before a save. */
899
1222
  showFloppy(thread, replying) {
900
- setOrDrop(thread, "saved", replying?.floppy?.tip);
901
- thread.toggleAttribute("failed", !!replying?.floppy?.failed);
1223
+ setOrDrop(thread, "saved", replying?.floppy?.tip)
1224
+ thread.toggleAttribute("failed", !!replying?.floppy?.failed)
902
1225
  }
1226
+
903
1227
  /**
904
1228
  * Thread `comment`'s reply box (Owen, 2026-10-10: "How do I reply? Probably should have a comment box at the
905
1229
  * bottom for me"): under its messages whenever it's open, Owen's turn or Claude's, so he can always add more.
@@ -909,14 +1233,15 @@ var PageComments = class {
909
1233
  * holds, so Claude taking his reply empties it
910
1234
  */
911
1235
  replyBoxFor(comment) {
912
- const saved = ThreadFacts.pendingReplyOf(comment)?.text ?? "";
913
- const kept = this.replyBoxes.get(comment.id);
914
- if (kept && (kept.busy() || kept.saved() === saved)) return kept;
915
- kept?.drop();
916
- const replying = this.makeBox(comment.id, "reply", saved);
917
- this.replyBoxes.set(comment.id, replying);
918
- return replying;
1236
+ const saved = ThreadFacts.pendingReplyOf(comment)?.text ?? ""
1237
+ const kept = this.replyBoxes.get(comment.id)
1238
+ if (kept && (kept.busy() || kept.saved() === saved)) return kept
1239
+ kept?.drop()
1240
+ const replying = this.makeBox(comment.id, "reply", saved)
1241
+ this.replyBoxes.set(comment.id, replying)
1242
+ return replying
919
1243
  }
1244
+
920
1245
  /**
921
1246
  * A reply box for comment `id`, wired by `wireReply()`.
922
1247
  * - `how`: `reply` (his reply) or `edit` (his first words); `saved`: the words the server holds for it
@@ -931,11 +1256,12 @@ var PageComments = class {
931
1256
  class: "spell-comment-field",
932
1257
  rows: 1,
933
1258
  "aria-label": how === "edit" ? "Your comment" : "Your reply"
934
- });
935
- const replying = { id, how, box: field, field, floppy: null };
936
- this.wireReply(replying, saved);
937
- return replying;
1259
+ })
1260
+ const replying = { id, how, box: field, field, floppy: null }
1261
+ this.wireReply(replying, saved)
1262
+ return replying
938
1263
  }
1264
+
939
1265
  /**
940
1266
  * Wire `thread`, comment `id`'s: what Owen does on it, as it says (`<epic-thread>`'s events).
941
1267
  * - its header folded or unfolded: remembered for the visit; unfolded, seen (`markSeen()`)
@@ -943,115 +1269,124 @@ var PageComments = class {
943
1269
  * - the pen: his first words into a box to change; the trash: deleted at once, Undo in the toast
944
1270
  */
945
1271
  wireThread(thread, id) {
946
- const onFold = /* @__PURE__ */ __name((event) => {
947
- const opening = !!event.detail?.open;
948
- this.folds.set(id, opening);
949
- if (!opening) return;
950
- requestAnimationFrame(() => this.growFields());
951
- this.markSeen(id);
952
- }, "onFold");
953
- thread.addEventListener("epic-thread-opened", onFold);
954
- thread.addEventListener("epic-thread-closed", onFold);
1272
+ const onFold = (event) => {
1273
+ const opening = !!event.detail?.open
1274
+ this.folds.set(id, opening)
1275
+ if (!opening) return
1276
+ requestAnimationFrame(() => this.growFields())
1277
+ this.markSeen(id)
1278
+ }
1279
+ thread.addEventListener("epic-thread-opened", onFold)
1280
+ thread.addEventListener("epic-thread-closed", onFold)
955
1281
  thread.addEventListener("epic-thread-answered", (event) => {
956
- const act = event.detail?.act;
957
- if (act === "reply") void this.focusReply(id);
958
- else if (act === "reopen") void this.reopen(id);
959
- else if (act === "good" || act === "skip") void this.resolve(id, act);
960
- });
961
- thread.addEventListener("epic-thread-editing", () => this.startEdit(id));
962
- thread.addEventListener("epic-thread-removing", () => void this.remove(id));
1282
+ const act = event.detail?.act
1283
+ if (act === "reply") void this.focusReply(id)
1284
+ else if (act === "reopen") void this.reopen(id)
1285
+ else if (act === "good" || act === "skip") void this.resolve(id, act)
1286
+ })
1287
+ thread.addEventListener("epic-thread-editing", () => this.startEdit(id))
1288
+ thread.addEventListener("epic-thread-removing", () => void this.remove(id))
963
1289
  }
1290
+
964
1291
  /**
965
1292
  * Close thread `id`: `good` ("that's good") or `skip` ("skip it"). NEVER throws.
966
1293
  * - It folds, with a check circle in its header and a green Done line at its end.
967
1294
  * - A toast says so, with Undo (`reopen()`).
968
1295
  */
969
1296
  async resolve(id, how) {
970
- if (this.editing?.id === id && !await this.closeEdit()) return;
971
- if (this.replyBoxes.has(id) && !await this.replyBoxes.get(id).finish()) return;
1297
+ if (this.editing?.id === id && !(await this.closeEdit())) return
1298
+ // what he typed in its reply box goes first
1299
+ if (this.replyBoxes.has(id) && !(await this.replyBoxes.get(id).finish())) return
972
1300
  try {
973
- await this.post({ action: "resolve", id, how });
974
- this.folds.delete(id);
975
- this.draw();
976
- let undone = false;
977
- const undo = /* @__PURE__ */ __name(() => {
978
- if (undone) return;
979
- undone = true;
980
- void this.reopen(id);
981
- }, "undo");
1301
+ await this.post({ action: "resolve", id, how })
1302
+ this.folds.delete(id)
1303
+ this.draw()
1304
+ let undone = false
1305
+ const undo = () => {
1306
+ if (undone) return
1307
+ undone = true
1308
+ void this.reopen(id)
1309
+ }
982
1310
  noteToast(how === "skip" ? "Skipped: nothing more to do" : "Done: that's good", "success", {
983
1311
  displayTime: UNDO_MS,
984
1312
  actions: [{ text: "Undo", icon: "rotate left", click: undo }]
985
- });
1313
+ })
986
1314
  } catch (error) {
987
- noteToast(`Couldn't close the thread: ${error.message}`, "error");
1315
+ noteToast(`Couldn't close the thread: ${error.message}`, "error")
988
1316
  }
989
1317
  }
1318
+
990
1319
  /** Open thread `id` again (Reopen, the toast's Undo): Owen's turn again, so it opens. NEVER throws. */
991
1320
  async reopen(id) {
992
1321
  try {
993
- await this.post({ action: "reopen", id });
994
- this.folds.delete(id);
995
- this.draw();
1322
+ await this.post({ action: "reopen", id })
1323
+ this.folds.delete(id)
1324
+ this.draw()
996
1325
  } catch (error) {
997
- noteToast(`Couldn't reopen the thread: ${error.message}`, "error");
1326
+ noteToast(`Couldn't reopen the thread: ${error.message}`, "error")
998
1327
  }
999
1328
  }
1329
+
1000
1330
  /** POST `change` to the comments route for this page, and keep the list it answers; throws what `ServerLink.forPage().post()` does. */
1001
1331
  async post(change, options) {
1002
- const answer = await ServerLink.forPage().post(COMMENTS_API, { page: location.pathname, ...change }, options);
1003
- this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list;
1004
- this.keepSend(answer);
1005
- return answer;
1332
+ const answer = await ServerLink.forPage().post(COMMENTS_API, { page: location.pathname, ...change }, options)
1333
+ this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list
1334
+ this.keepSend(answer)
1335
+ return answer
1006
1336
  }
1337
+
1007
1338
  ////////////////
1008
1339
  // ## The reply box
1009
1340
  ////////////////
1341
+
1010
1342
  /**
1011
1343
  * The cursor into thread `id`'s reply box, at the end (Revisit: "reply"); the thread opens, and the page scrolls
1012
1344
  * only as far as it must to show it. The pen's box open on it: that one.
1013
1345
  * - once the thread has drawn its body: a thread just opened shows its box on the next frame
1014
1346
  */
1015
1347
  async focusReply(id) {
1016
- this.folds.set(id, true);
1017
- this.draw();
1018
- await nextFrame();
1019
- const replying = this.editing?.id === id ? this.editing : this.replyBoxes.get(id);
1020
- const field = replying?.field;
1021
- if (!field?.isConnected) return;
1022
- growField(field);
1023
- field.scrollIntoView({ block: "nearest" });
1024
- field.focus({ preventScroll: true });
1025
- field.setSelectionRange(field.value.length, field.value.length);
1348
+ this.folds.set(id, true)
1349
+ this.draw()
1350
+ await nextFrame()
1351
+ const replying = this.editing?.id === id ? this.editing : this.replyBoxes.get(id)
1352
+ const field = replying?.field
1353
+ if (!field?.isConnected) return
1354
+ growField(field)
1355
+ field.scrollIntoView({ block: "nearest" })
1356
+ field.focus({ preventScroll: true })
1357
+ field.setSelectionRange(field.value.length, field.value.length)
1026
1358
  }
1359
+
1027
1360
  /**
1028
1361
  * The pen: edit his first words on thread `id` while Claude hasn't had them, in a box that stands in for them
1029
1362
  * (and for the thread's reply box), the cursor in it. Another one open is saved and closed first.
1030
1363
  */
1031
1364
  startEdit(id) {
1032
- if (this.editing?.id === id) return void this.focusReply(id);
1033
- void this.closeEdit();
1034
- const comment = this.list.find((each) => each.id === id);
1035
- if (!comment) return;
1036
- this.editing = this.makeBox(id, "edit", comment.text);
1037
- void this.focusReply(id);
1365
+ if (this.editing?.id === id) return void this.focusReply(id)
1366
+ void this.closeEdit()
1367
+ const comment = this.list.find((each) => each.id === id)
1368
+ if (!comment) return
1369
+ this.editing = this.makeBox(id, "edit", comment.text)
1370
+ void this.focusReply(id)
1038
1371
  }
1372
+
1039
1373
  /**
1040
1374
  * Save and close the pen's box, if open; resolves to whether it closed.
1041
1375
  * - Emptied, the comment goes (Undo in the toast).
1042
1376
  * - A save that failed keeps it open, and says why in a toast.
1043
1377
  */
1044
1378
  async closeEdit() {
1045
- const editing = this.editing;
1046
- if (!editing) return true;
1047
- if (!await editing.finish()) {
1048
- noteToast(editing.floppy?.tip ?? "Not saved", "error");
1049
- return false;
1379
+ const editing = this.editing
1380
+ if (!editing) return true
1381
+ if (!(await editing.finish())) {
1382
+ noteToast(editing.floppy?.tip ?? "Not saved", "error")
1383
+ return false
1050
1384
  }
1051
- if (this.editing === editing) this.editing = null;
1052
- this.draw();
1053
- return true;
1385
+ if (this.editing === editing) this.editing = null
1386
+ this.draw()
1387
+ return true
1054
1388
  }
1389
+
1055
1390
  /**
1056
1391
  * Wire reply box `replying` (`makeBox()`); `saved`: the words the server holds for it.
1057
1392
  * - saves itself as Owen types, `COMMENT_SAVE_MS` after he stops, as the pane does (a `DraftSaver`: a failed save
@@ -1068,78 +1403,87 @@ var PageComments = class {
1068
1403
  * - `busy()`: Owen is in it, or it holds words not saved yet: a redraw keeps it as it is
1069
1404
  */
1070
1405
  wireReply(replying, saved) {
1071
- const { id, how, box, field } = replying;
1072
- const slot = `${id}~${how}`;
1073
- const showFloppy = /* @__PURE__ */ __name((floppy) => {
1074
- replying.floppy = floppy;
1075
- const thread = this.threads.get(id);
1076
- if (thread && box.parentElement === thread) this.showFloppy(thread, replying);
1077
- }, "showFloppy");
1078
- field.value = readJSON(this.draftKey)[slot] ?? saved;
1079
- const keep = /* @__PURE__ */ __name(() => {
1080
- const drafts2 = readJSON(this.draftKey);
1081
- if (field.value.trim() !== saved) drafts2[slot] = field.value;
1082
- else delete drafts2[slot];
1083
- writeJSON(this.draftKey, drafts2);
1084
- }, "keep");
1406
+ const { id, how, box, field } = replying
1407
+ const slot = `${id}~${how}`
1408
+ // how the last save went, shown by the thread the box is in (its floppy)
1409
+ const showFloppy = (floppy) => {
1410
+ replying.floppy = floppy
1411
+ const thread = this.threads.get(id)
1412
+ if (thread && box.parentElement === thread) this.showFloppy(thread, replying)
1413
+ }
1414
+ field.value = readJSON(this.draftKey)[slot] ?? saved
1415
+ const keep = () => {
1416
+ const drafts = readJSON(this.draftKey)
1417
+ if (field.value.trim() !== saved) drafts[slot] = field.value
1418
+ else delete drafts[slot]
1419
+ writeJSON(this.draftKey, drafts)
1420
+ }
1085
1421
  const drafts = new DraftSaver({
1086
1422
  wait: COMMENT_SAVE_MS,
1087
- save: /* @__PURE__ */ __name(async ({ keepalive }) => {
1088
- const words = field.value.trim();
1089
- if (words === saved || !words && how === "edit") return;
1090
- await this.post({ action: how, id, text: words }, { keepalive });
1091
- saved = words;
1092
- keep();
1093
- showFloppy(words ? { tip: savedTip() } : null);
1094
- if (this.replyBoxes.get(id) === replying || this.editing === replying) this.draw();
1095
- }, "save"),
1096
- onChange: /* @__PURE__ */ __name(() => {
1097
- if (drafts.state.kind === "failed") showFloppy({ tip: notSavedTip(drafts.state.why), failed: true });
1098
- }, "onChange")
1099
- });
1100
- drafts.isUnsaved = field.value.trim() !== saved;
1101
- const saveNow = /* @__PURE__ */ __name(() => drafts.save(), "saveNow");
1102
- replying.saved = () => saved;
1103
- replying.busy = () => document.activeElement === field || field.value.trim() !== saved || drafts.isPending || drafts.isUnsaved;
1104
- replying.drop = () => drafts.stop();
1423
+ save: async ({ keepalive }) => {
1424
+ const words = field.value.trim()
1425
+ if (words === saved || (!words && how === "edit")) return
1426
+ await this.post({ action: how, id, text: words }, { keepalive })
1427
+ saved = words
1428
+ keep()
1429
+ showFloppy(words ? { tip: savedTip() } : null)
1430
+ // whose turn it is changed: its header's buttons with it
1431
+ if (this.replyBoxes.get(id) === replying || this.editing === replying) this.draw()
1432
+ },
1433
+ onChange: () => {
1434
+ if (drafts.state.kind === "failed") showFloppy({ tip: notSavedTip(drafts.state.why), failed: true })
1435
+ }
1436
+ })
1437
+ // a draft kept in this browser differs from what's saved: the next save sends it
1438
+ drafts.isUnsaved = field.value.trim() !== saved
1439
+ const saveNow = () => drafts.save()
1440
+ replying.saved = () => saved
1441
+ replying.busy = () =>
1442
+ document.activeElement === field || field.value.trim() !== saved || drafts.isPending || drafts.isUnsaved
1443
+ replying.drop = () => drafts.stop()
1105
1444
  replying.finish = async () => {
1106
1445
  if (how === "edit" && !field.value.trim()) {
1107
- drafts.stop();
1108
- this.forget(slot);
1109
- if (this.editing === replying) this.editing = null;
1110
- await this.remove(id);
1111
- return true;
1446
+ drafts.stop()
1447
+ this.forget(slot)
1448
+ if (this.editing === replying) this.editing = null
1449
+ await this.remove(id)
1450
+ return true
1112
1451
  }
1113
- const ok = await saveNow();
1114
- if (ok) this.forget(slot);
1115
- return ok;
1116
- };
1117
- replying.flush = () => void drafts.save({ keepalive: true });
1452
+ const ok = await saveNow()
1453
+ if (ok) this.forget(slot)
1454
+ return ok
1455
+ }
1456
+ // the page is going: a request that outlives it
1457
+ replying.flush = () => void drafts.save({ keepalive: true })
1118
1458
  field.addEventListener("input", () => {
1119
- growField(field);
1120
- keep();
1121
- drafts.changed();
1122
- });
1459
+ growField(field)
1460
+ keep()
1461
+ drafts.changed()
1462
+ })
1123
1463
  field.addEventListener("keydown", (event) => {
1124
- const leaving = event.key === "Escape" || event.key === "Enter" && (event.metaKey || event.ctrlKey);
1125
- if (!leaving) return;
1126
- event.preventDefault();
1127
- event.stopPropagation();
1128
- if (how === "edit") void this.closeEdit();
1129
- else field.blur();
1130
- });
1464
+ const leaving = event.key === "Escape" || (event.key === "Enter" && (event.metaKey || event.ctrlKey))
1465
+ if (!leaving) return
1466
+ event.preventDefault()
1467
+ event.stopPropagation()
1468
+ if (how === "edit") void this.closeEdit()
1469
+ else field.blur()
1470
+ })
1131
1471
  field.addEventListener("blur", () => {
1472
+ // a redraw moves the box, and takes the cursor back into it; another window or tab keeps it here:
1473
+ // only a real leave counts
1132
1474
  setTimeout(() => {
1133
- if (!box.isConnected || document.activeElement === field) return;
1475
+ if (!box.isConnected || document.activeElement === field) return
1134
1476
  if (how === "edit") {
1135
- if (this.editing === replying) void this.closeEdit();
1136
- } else if (this.replyBoxes.get(id) === replying) void saveNow();
1137
- });
1138
- });
1477
+ if (this.editing === replying) void this.closeEdit()
1478
+ } else if (this.replyBoxes.get(id) === replying) void saveNow()
1479
+ })
1480
+ })
1139
1481
  }
1482
+
1140
1483
  ////////////////
1141
1484
  // ## Deleting
1142
1485
  ////////////////
1486
+
1143
1487
  /**
1144
1488
  * Delete comment `id`, whatever its state, at once: gone from the inbox, its thread and highlight with it.
1145
1489
  * NEVER throws.
@@ -1148,47 +1492,50 @@ var PageComments = class {
1148
1492
  * - its pane or reply box, if open, closes; any draft of it is forgotten
1149
1493
  */
1150
1494
  async remove(id) {
1151
- const action = this.waiting(id) ? "delete" : "clear";
1152
- const was = this.list.find((each) => each.id === id);
1495
+ const action = this.waiting(id) ? "delete" : "clear"
1496
+ const was = this.list.find((each) => each.id === id)
1153
1497
  try {
1154
- await this.post({ action, id });
1155
- this.forget(id);
1156
- this.forget(`${id}~reply`);
1157
- if (this.editing?.id === id) this.editing = null;
1158
- this.replyBoxes.get(id)?.drop();
1159
- this.replyBoxes.delete(id);
1160
- if (this.open?.id === id) this.closePane();
1161
- else this.draw();
1162
- let undone = false;
1163
- const undo = /* @__PURE__ */ __name(() => {
1164
- if (undone) return;
1165
- undone = true;
1166
- void this.restore(was);
1167
- }, "undo");
1498
+ await this.post({ action, id })
1499
+ this.forget(id)
1500
+ this.forget(`${id}~reply`)
1501
+ if (this.editing?.id === id) this.editing = null
1502
+ this.replyBoxes.get(id)?.drop()
1503
+ this.replyBoxes.delete(id)
1504
+ if (this.open?.id === id) this.closePane()
1505
+ else this.draw()
1506
+ let undone = false
1507
+ const undo = () => {
1508
+ if (undone) return
1509
+ undone = true
1510
+ void this.restore(was)
1511
+ }
1168
1512
  noteToast("Comment deleted", "success", {
1169
1513
  displayTime: UNDO_MS,
1170
- actions: was ? [{ text: "Undo", icon: "rotate left", click: undo }] : void 0
1171
- });
1514
+ actions: was ? [{ text: "Undo", icon: "rotate left", click: undo }] : undefined
1515
+ })
1172
1516
  } catch (error) {
1173
- noteToast(`Couldn't delete the comment: ${error.message}`, "error");
1517
+ noteToast(`Couldn't delete the comment: ${error.message}`, "error")
1174
1518
  }
1175
1519
  }
1520
+
1176
1521
  /**
1177
1522
  * Undo a delete: comment `was` (as the server last gave it) back as it was, on its block, its quote highlighted
1178
1523
  * again; its id the same unless a new comment took it meanwhile (the server's `restore`). NEVER throws.
1179
1524
  */
1180
1525
  async restore(was) {
1181
1526
  try {
1182
- const { id, ...comment } = was;
1183
- await this.post({ action: "restore", id, comment });
1184
- this.draw();
1527
+ const { id, ...comment } = was
1528
+ await this.post({ action: "restore", id, comment })
1529
+ this.draw()
1185
1530
  } catch (error) {
1186
- noteToast(`Couldn't bring the comment back: ${error.message}`, "error");
1531
+ noteToast(`Couldn't bring the comment back: ${error.message}`, "error")
1187
1532
  }
1188
1533
  }
1534
+
1189
1535
  ////////////////
1190
1536
  // ## The comment pane
1191
1537
  ////////////////
1538
+
1192
1539
  /**
1193
1540
  * Open the comment pane for `open` (`{ key, place }`): a NEW comment on `place`'s block (`quote`: on that text).
1194
1541
  * - just under `near`, a `DOMRect`: the selection's last line, the button clicked
@@ -1198,20 +1545,22 @@ var PageComments = class {
1198
1545
  * - the page never scrolls (Owen, 2026-10-10: "don't scroll the page and lose context!")
1199
1546
  */
1200
1547
  openBox(open, near) {
1201
- if (this.pane && this.open?.key === open.key) return this.focusPane();
1202
- void this.open?.finish?.();
1203
- this.pane?.remove();
1204
- this.open = open;
1205
- this.draw();
1206
- this.showPane(near);
1548
+ if (this.pane && this.open?.key === open.key) return this.focusPane()
1549
+ void this.open?.finish?.()
1550
+ this.pane?.remove()
1551
+ this.open = open
1552
+ this.draw()
1553
+ this.showPane(near)
1207
1554
  }
1555
+
1208
1556
  /** Close the pane, and draw the comments again (the comment it wrote shows as a thread). */
1209
1557
  closePane() {
1210
- this.pane?.remove();
1211
- this.pane = null;
1212
- this.open = null;
1213
- this.draw();
1558
+ this.pane?.remove()
1559
+ this.pane = null
1560
+ this.open = null
1561
+ this.draw()
1214
1562
  }
1563
+
1215
1564
  /**
1216
1565
  * Put the pane on the screen under `near`, else above it when there's no room below, never past the window's
1217
1566
  * edges; the cursor in its field.
@@ -1221,9 +1570,9 @@ var PageComments = class {
1221
1570
  * - the cursor goes in once the pane has drawn (it upgrades as the pack registers)
1222
1571
  */
1223
1572
  showPane(near) {
1224
- const open = this.open;
1225
- const field = el("textarea", { class: "spell-comment-field", rows: 3, "aria-label": "Your comment" });
1226
- const pane = this.pane = el(
1573
+ const open = this.open
1574
+ const field = el("textarea", { class: "spell-comment-field", rows: 3, "aria-label": "Your comment" })
1575
+ const pane = (this.pane = el(
1227
1576
  PANE_TAG,
1228
1577
  {
1229
1578
  "data-spell-added": true,
@@ -1231,23 +1580,25 @@ var PageComments = class {
1231
1580
  about: ThreadFacts.aboutTip(open)
1232
1581
  },
1233
1582
  field
1234
- );
1235
- pane.near = near ? { left: near.left, top: near.top, bottom: near.bottom } : void 0;
1236
- this.wirePane(pane, field, open);
1237
- this.main.append(pane);
1583
+ ))
1584
+ pane.near = near ? { left: near.left, top: near.top, bottom: near.bottom } : undefined
1585
+ this.wirePane(pane, field, open)
1586
+ this.main.append(pane)
1238
1587
  void drawn(pane).then(() => {
1239
- if (this.pane !== pane) return;
1240
- growField(field);
1241
- this.focusPane();
1242
- });
1588
+ if (this.pane !== pane) return
1589
+ growField(field)
1590
+ this.focusPane()
1591
+ })
1243
1592
  }
1593
+
1244
1594
  /** The cursor into the open pane's field, at the end; no scrolling. */
1245
1595
  focusPane() {
1246
- const field = this.pane?.querySelector(":scope > textarea");
1247
- if (!field) return;
1248
- field.focus({ preventScroll: true });
1249
- field.setSelectionRange(field.value.length, field.value.length);
1596
+ const field = this.pane?.querySelector(":scope > textarea")
1597
+ if (!field) return
1598
+ field.focus({ preventScroll: true })
1599
+ field.setSelectionRange(field.value.length, field.value.length)
1250
1600
  }
1601
+
1251
1602
  /**
1252
1603
  * Wire pane `pane` and its `field`, for `open` (`openBox()`'s).
1253
1604
  * - × or Escape closes it (⌘ / Ctrl Enter too, in the field), saving what's typed first
@@ -1256,23 +1607,29 @@ var PageComments = class {
1256
1607
  * - the field has no placeholder (Owen, 2026-10-10: "remove the 'Anything: a correction...' placeholder")
1257
1608
  */
1258
1609
  wirePane(pane, field, open) {
1259
- const close = this.wireField(pane, field, open);
1260
- pane.addEventListener("epic-comment-closing", () => void close());
1610
+ const close = this.wireField(pane, field, open)
1611
+ pane.addEventListener("epic-comment-closing", () => void close())
1261
1612
  pane.addEventListener("keydown", (event) => {
1262
- const closing = event.key === "Escape" || event.key === "Enter" && (event.metaKey || event.ctrlKey);
1263
- if (!closing) return;
1264
- event.preventDefault();
1265
- event.stopPropagation();
1266
- void close();
1267
- });
1613
+ const closing = event.key === "Escape" || (event.key === "Enter" && (event.metaKey || event.ctrlKey))
1614
+ if (!closing) return
1615
+ event.preventDefault()
1616
+ event.stopPropagation()
1617
+ void close()
1618
+ })
1619
+ // focus leaving the pane (Tab, a click elsewhere): closed as × closes it,
1620
+ // so what's typed is saved, and an emptied comment goes, with no Undo
1621
+ // - Owen, 2026-10-10: "Tabbing out of a bullhorn modal saves it automatically. If it's empty, delete it"
1622
+ // - another window or tab keeps the focus here: it stays open
1623
+ // - its own buttons (in its shadow root) count as in it: the focus there is the pane's
1268
1624
  pane.addEventListener("focusout", () => {
1269
1625
  setTimeout(() => {
1270
- if (this.pane !== pane || pane.contains(document.activeElement)) return;
1271
- void close();
1272
- });
1273
- });
1274
- pane.addEventListener("epic-comment-removing", () => void (open.discard ? open.discard() : this.remove(open.id)));
1626
+ if (this.pane !== pane || pane.contains(document.activeElement)) return
1627
+ void close()
1628
+ })
1629
+ })
1630
+ pane.addEventListener("epic-comment-removing", () => void (open.discard ? open.discard() : this.remove(open.id)))
1275
1631
  }
1632
+
1276
1633
  /**
1277
1634
  * Wire the pane's field for `open`; returns what closes it.
1278
1635
  * - saves itself as Owen types, `COMMENT_SAVE_MS` after he stops (a `DraftSaver`: a failed save tried again
@@ -1289,172 +1646,221 @@ var PageComments = class {
1289
1646
  * - leaving the page (`pagehide`): what's typed and not saved yet goes at once (`flush()`)
1290
1647
  */
1291
1648
  wireField(pane, field, open) {
1292
- const { key, place } = open;
1293
- let floppy = "";
1294
- let saved = (open.text ?? "").trim();
1295
- let gone = false;
1296
- const slot = /* @__PURE__ */ __name(() => open.id ?? key, "slot");
1297
- field.value = this.draftOf(open) ?? open.text ?? "";
1298
- const keep = /* @__PURE__ */ __name((before = slot()) => {
1299
- const drafts2 = readJSON(this.draftKey);
1300
- delete drafts2[before];
1301
- const words = field.value.trim();
1302
- if (words && words !== saved) drafts2[slot()] = field.value;
1303
- else delete drafts2[slot()];
1304
- writeJSON(this.draftKey, drafts2);
1305
- }, "keep");
1306
- const save = /* @__PURE__ */ __name(async ({ keepalive }) => {
1307
- const words = field.value.trim();
1308
- if (gone || words === saved) return;
1309
- if (!words && !open.id) return;
1310
- const change = !words ? { action: this.waiting(open.id) ? "delete" : "clear", id: open.id } : open.id ? { action: "edit", id: open.id, text: words } : { action: "add", ...place, text: words };
1649
+ const { key, place } = open
1650
+ // the floppy, in the pane's header, says how the last save went; `floppy`: its tooltip then
1651
+ let floppy = ""
1652
+ // what the server holds; one save at a time, in order, so a quick typist never adds the comment twice
1653
+ let saved = (open.text ?? "").trim()
1654
+ // deleted with the trash: nothing more is saved
1655
+ let gone = false
1656
+ // where its draft is kept
1657
+ const slot = () => open.id ?? key
1658
+ field.value = this.draftOf(open) ?? open.text ?? ""
1659
+ // keep what's typed as the draft while it differs from what's saved; else none (`before`: its old slot)
1660
+ const keep = (before = slot()) => {
1661
+ const drafts = readJSON(this.draftKey)
1662
+ delete drafts[before]
1663
+ const words = field.value.trim()
1664
+ if (words && words !== saved) drafts[slot()] = field.value
1665
+ else delete drafts[slot()]
1666
+ writeJSON(this.draftKey, drafts)
1667
+ }
1668
+ const save = async ({ keepalive }) => {
1669
+ const words = field.value.trim()
1670
+ if (gone || words === saved) return
1671
+ if (!words && !open.id) return
1672
+ const change = !words
1673
+ ? { action: this.waiting(open.id) ? "delete" : "clear", id: open.id }
1674
+ : open.id
1675
+ ? { action: "edit", id: open.id, text: words }
1676
+ : { action: "add", ...place, text: words }
1311
1677
  const answer = await ServerLink.forPage().post(
1312
1678
  COMMENTS_API,
1313
1679
  { page: location.pathname, ...change },
1314
1680
  { keepalive }
1315
- );
1316
- const before = slot();
1317
- open.id = words ? open.id ?? answer.id : void 0;
1318
- saved = words;
1319
- this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list;
1320
- this.keepSend(answer);
1321
- keep(before);
1322
- floppy = words ? savedTip() : "";
1323
- setOrDrop(pane, "saved", floppy || void 0);
1324
- pane.removeAttribute("failed");
1325
- pane.toggleAttribute("deletable", !!open.id);
1326
- if (this.open === open) this.draw();
1327
- }, "save");
1681
+ )
1682
+ const before = slot()
1683
+ open.id = words ? (open.id ?? answer.id) : undefined
1684
+ saved = words
1685
+ this.list = answer.comments ? ThreadFacts.withTurns(answer.comments) : this.list
1686
+ this.keepSend(answer)
1687
+ keep(before)
1688
+ floppy = words ? savedTip() : ""
1689
+ setOrDrop(pane, "saved", floppy || undefined)
1690
+ pane.removeAttribute("failed")
1691
+ pane.toggleAttribute("deletable", !!open.id)
1692
+ // its highlight on the page, at once; its thread waits until the pane closes
1693
+ if (this.open === open) this.draw()
1694
+ }
1328
1695
  const drafts = new DraftSaver({
1329
1696
  wait: COMMENT_SAVE_MS,
1330
1697
  save,
1331
- onChange: /* @__PURE__ */ __name(() => {
1332
- if (drafts.state.kind !== "failed") return;
1333
- floppy = notSavedTip(drafts.state.why);
1334
- pane.setAttribute("saved", floppy);
1335
- pane.setAttribute("failed", "");
1336
- }, "onChange")
1337
- });
1338
- drafts.isUnsaved = field.value.trim() !== saved;
1339
- const saveNow = /* @__PURE__ */ __name(() => drafts.save(), "saveNow");
1698
+ onChange: () => {
1699
+ if (drafts.state.kind !== "failed") return
1700
+ floppy = notSavedTip(drafts.state.why)
1701
+ pane.setAttribute("saved", floppy)
1702
+ pane.setAttribute("failed", "")
1703
+ }
1704
+ })
1705
+ // a draft kept in this browser differs from what's saved: the next save sends it
1706
+ drafts.isUnsaved = field.value.trim() !== saved
1707
+ const saveNow = () => drafts.save()
1340
1708
  open.finish = async () => {
1341
- if (!await saveNow()) return false;
1342
- this.forget(slot());
1343
- this.forget(key);
1344
- return true;
1345
- };
1346
- open.flush = () => void drafts.save({ keepalive: true });
1709
+ if (!(await saveNow())) return false
1710
+ this.forget(slot())
1711
+ this.forget(key)
1712
+ return true
1713
+ }
1714
+ // the page is going: a request that outlives it
1715
+ open.flush = () => void drafts.save({ keepalive: true })
1347
1716
  open.discard = async () => {
1348
- drafts.stop();
1349
- await drafts.settled;
1350
- gone = true;
1351
- this.forget(slot());
1352
- this.forget(key);
1353
- if (open.id) return this.remove(open.id);
1354
- if (this.open === open) this.closePane();
1355
- };
1717
+ drafts.stop()
1718
+ // a save on its way first: it may bring the comment's id
1719
+ await drafts.settled
1720
+ gone = true
1721
+ this.forget(slot())
1722
+ this.forget(key)
1723
+ if (open.id) return this.remove(open.id)
1724
+ if (this.open === open) this.closePane()
1725
+ }
1356
1726
  field.addEventListener("input", () => {
1357
- growField(field);
1358
- keep();
1359
- drafts.changed();
1360
- });
1361
- field.addEventListener("blur", () => void saveNow());
1727
+ growField(field)
1728
+ keep()
1729
+ drafts.changed()
1730
+ })
1731
+ field.addEventListener("blur", () => void saveNow())
1362
1732
  return async () => {
1363
- if (!await open.finish()) return noteToast(floppy, "error");
1364
- if (this.open === open) this.closePane();
1365
- };
1733
+ if (!(await open.finish())) return noteToast(floppy, "error")
1734
+ if (this.open === open) this.closePane()
1735
+ }
1366
1736
  }
1737
+
1367
1738
  /**
1368
1739
  * The draft kept for `open`'s pane (`wireField()`), or `undefined`: none, blank, or (a new comment's) a copy of a
1369
1740
  * comment already on its block, which is dropped.
1370
1741
  */
1371
1742
  draftOf(open) {
1372
- const slot = open.id ?? open.key;
1373
- const draft = readJSON(this.draftKey)[slot];
1374
- if (typeof draft !== "string" || !draft.trim()) return void 0;
1375
- const { anchor, quote } = open.place;
1376
- const copy = !open.id && this.list.some(
1377
- (each) => each.anchor === anchor && (each.quote ?? "") === (quote ?? "") && each.text === draft.trim()
1378
- );
1379
- if (!copy) return draft;
1380
- this.forget(slot);
1381
- return void 0;
1743
+ const slot = open.id ?? open.key
1744
+ const draft = readJSON(this.draftKey)[slot]
1745
+ if (typeof draft !== "string" || !draft.trim()) return undefined
1746
+ const { anchor, quote } = open.place
1747
+ const copy =
1748
+ !open.id &&
1749
+ this.list.some(
1750
+ (each) => each.anchor === anchor && (each.quote ?? "") === (quote ?? "") && each.text === draft.trim()
1751
+ )
1752
+ if (!copy) return draft
1753
+ this.forget(slot)
1754
+ return undefined
1382
1755
  }
1756
+
1383
1757
  /** Whether comment `id` is still `new` (Claude hasn't had it), as the server last answered: Owen may delete it. */
1384
1758
  waiting(id) {
1385
- const comment = this.list.find((each) => each.id === id);
1386
- return !comment || comment.status === "new";
1759
+ const comment = this.list.find((each) => each.id === id)
1760
+ return !comment || comment.status === "new"
1387
1761
  }
1762
+
1388
1763
  /** Drop the draft under `key`. */
1389
1764
  forget(key) {
1390
- const drafts = readJSON(this.draftKey);
1391
- delete drafts[key];
1392
- writeJSON(this.draftKey, drafts);
1765
+ const drafts = readJSON(this.draftKey)
1766
+ delete drafts[key]
1767
+ writeJSON(this.draftKey, drafts)
1393
1768
  }
1394
- };
1769
+ }
1770
+
1771
+ /**
1772
+ * A docs page's Send's tooltip (`drawSend()`): what a click sends, and to which epic; or why it sends nothing.
1773
+ * - `state`: `unsent`, `sent` or `idle`
1774
+ */
1395
1775
  function sendWords({ epic, unsent, waiting }, state) {
1396
- const count = /* @__PURE__ */ __name((n) => `${n} comment${n === 1 ? "" : "s"}`, "count");
1397
- if (state === "unsent") return `Send ${count(unsent.length)} to epic ${epic}`;
1398
- if (state === "sent") return `Sent to ${epic}: ${count(waiting.length)} waiting for Claude`;
1399
- return "Nothing to send: no comment here is waiting for Claude";
1776
+ const count = (n) => `${n} comment${n === 1 ? "" : "s"}`
1777
+ if (state === "unsent") return `Send ${count(unsent.length)} to epic ${epic}`
1778
+ if (state === "sent") return `Sent to ${epic}: ${count(waiting.length)} waiting for Claude`
1779
+ return "Nothing to send: no comment here is waiting for Claude"
1400
1780
  }
1401
- __name(sendWords, "sendWords");
1781
+
1782
+ /**
1783
+ * Who is listening, beside a docs page's Send (`drawSend()`): `python-target is listening`, `nobody is listening`.
1784
+ * - a page no epic owns names the standing epic its comments go to (epic `epic-engine` T9):
1785
+ * `feedback is listening`, `nobody is listening: Send wakes feedback`
1786
+ */
1402
1787
  function whoLabel({ epic, owned, wakes, listening }) {
1403
- if (listening) return `${epic} is listening`;
1404
- if (owned) return "nobody is listening";
1405
- return wakes ? `nobody is listening: Send wakes ${epic}` : "no epic owns this page";
1788
+ if (listening) return `${epic} is listening`
1789
+ if (owned) return "nobody is listening"
1790
+ return wakes ? `nobody is listening: Send wakes ${epic}` : "no epic owns this page"
1406
1791
  }
1407
- __name(whoLabel, "whoLabel");
1792
+
1793
+ /** The tooltip of who is listening, beside a docs page's Send (`drawSend()`): where its comments go, and when. */
1408
1794
  function whoWords({ epic, owned, wakes, listening }) {
1409
- const where = owned ? `epic ${epic}` : `epic ${epic}, the standing epic for every page no epic owns (no epic's See Also lists this one)`;
1410
- if (listening) return `A Claude session is reviewing ${where}: Send hands it these comments now`;
1411
- if (wakes) return `No Claude session is reviewing ${where}: Send wakes its session`;
1412
- return `No epic's See Also lists this page, and epic ${epic} isn't made yet: /airplane land gathers its comments`;
1795
+ const where = owned
1796
+ ? `epic ${epic}`
1797
+ : `epic ${epic}, the standing epic for every page no epic owns (no epic's See Also lists this one)`
1798
+ if (listening) return `A Claude session is reviewing ${where}: Send hands it these comments now`
1799
+ if (wakes) return `No Claude session is reviewing ${where}: Send wakes its session`
1800
+ return `No epic's See Also lists this page, and epic ${epic} isn't made yet: /airplane land gathers its comments`
1413
1801
  }
1414
- __name(whoWords, "whoWords");
1415
- function firstWords(words) {
1416
- const line = String(words ?? "").split("\n")[0].trim();
1417
- return line.length > 60 ? `${line.slice(0, 60).trimEnd()}…` : line;
1802
+
1803
+ /** The first line of `words`, cut to a short line with `…`. */
1804
+ export function firstWords(words) {
1805
+ const line = String(words ?? "")
1806
+ .split("\n")[0]
1807
+ .trim()
1808
+ return line.length > 60 ? `${line.slice(0, 60).trimEnd()}…` : line
1418
1809
  }
1419
- __name(firstWords, "firstWords");
1810
+
1811
+ /**
1812
+ * Where a quote's thread goes (Owen, 2026-10-10: "show them under the paragraph where they were defined"): the
1813
+ * smallest paragraph, list item, cell ... (`TEXT_HOLDERS`) in `block` holding the quote (`quoted`: `quoteIn()`'s);
1814
+ * else `block` itself.
1815
+ * - never inside an element that would hide it: one drawing its children in a shadow root with no default slot
1816
+ */
1420
1817
  function holderOf(block, { start, end }) {
1421
1818
  try {
1422
- const range = document.createRange();
1423
- range.setStart(...start);
1424
- range.setEnd(...end);
1425
- const node = range.commonAncestorContainer;
1426
- const holder = (node.nodeType === 1 ? node : node.parentElement)?.closest(TEXT_HOLDERS);
1427
- if (!holder || holder === block || !holds(block, holder)) return block;
1428
- const shadow = holder.parentElement?.shadowRoot;
1429
- if (shadow && !shadow.querySelector("slot:not([name])")) return block;
1430
- return holder;
1819
+ const range = document.createRange()
1820
+ range.setStart(...start)
1821
+ range.setEnd(...end)
1822
+ const node = range.commonAncestorContainer
1823
+ const holder = (node.nodeType === 1 ? node : node.parentElement)?.closest(TEXT_HOLDERS)
1824
+ if (!holder || holder === block || !holds(block, holder)) return block
1825
+ const shadow = holder.parentElement?.shadowRoot
1826
+ if (shadow && !shadow.querySelector("slot:not([name])")) return block
1827
+ return holder
1431
1828
  } catch {
1432
- return block;
1829
+ return block
1433
1830
  }
1434
1831
  }
1435
- __name(holderOf, "holderOf");
1832
+
1833
+ /**
1834
+ * Highlight each quote's text on the page: softly once Claude has had it (`QUOTE_HIGHLIGHT`), purple while it waits
1835
+ * for him (`QUOTE_WAITING_HIGHLIGHT`); returns each one's range, by comment id (`[{ id, range }]`), for a click to
1836
+ * find. Not highlighted where the browser can't, but still found.
1837
+ */
1436
1838
  function highlightQuotes(quotes) {
1437
1839
  const found = quotes.flatMap(({ id, start, end, waiting }) => {
1438
1840
  try {
1439
- const range = document.createRange();
1440
- range.setStart(...start);
1441
- range.setEnd(...end);
1442
- return [{ id, range, waiting }];
1841
+ const range = document.createRange()
1842
+ range.setStart(...start)
1843
+ range.setEnd(...end)
1844
+ return [{ id, range, waiting }]
1443
1845
  } catch {
1444
- return [];
1846
+ return []
1445
1847
  }
1446
- });
1848
+ })
1447
1849
  if (globalThis.Highlight && globalThis.CSS?.highlights) {
1448
- for (const { range } of found) addQuoteSheet(range.startContainer.getRootNode());
1449
- const ranges = /* @__PURE__ */ __name((waiting) => found.filter((each) => !!each.waiting === waiting).map(({ range }) => range), "ranges");
1450
- CSS.highlights.set(QUOTE_HIGHLIGHT, new Highlight(...ranges(false)));
1451
- CSS.highlights.set(QUOTE_WAITING_HIGHLIGHT, new Highlight(...ranges(true)));
1850
+ for (const { range } of found) addQuoteSheet(range.startContainer.getRootNode())
1851
+ const ranges = (waiting) => found.filter((each) => !!each.waiting === waiting).map(({ range }) => range)
1852
+ CSS.highlights.set(QUOTE_HIGHLIGHT, new Highlight(...ranges(false)))
1853
+ CSS.highlights.set(QUOTE_WAITING_HIGHLIGHT, new Highlight(...ranges(true)))
1452
1854
  }
1453
- return found;
1855
+ return found
1454
1856
  }
1455
- __name(highlightQuotes, "highlightQuotes");
1857
+
1858
+ /**
1859
+ * Page rules don't reach text in a shadow root: a `<ui-markdown>`'s gets its quotes' look here, once;
1860
+ * their colours are `spell-comments.css`'s.
1861
+ */
1456
1862
  function addQuoteSheet(root) {
1457
- if (root === document || root.querySelector("style[data-spell-quotes]")) return;
1863
+ if (root === document || root.querySelector("style[data-spell-quotes]")) return
1458
1864
  root.append(
1459
1865
  el(
1460
1866
  "style",
@@ -1462,61 +1868,82 @@ function addQuoteSheet(root) {
1462
1868
  `::highlight(${QUOTE_HIGHLIGHT}) { background-color: var(--spell-quote-color); }
1463
1869
  ::highlight(${QUOTE_WAITING_HIGHLIGHT}) { background-color: var(--spell-quote-waiting-color); }`
1464
1870
  )
1465
- );
1871
+ )
1466
1872
  }
1467
- __name(addQuoteSheet, "addQuoteSheet");
1468
- var threadSlots = 0;
1469
- var UNDO_MS = 6e3;
1470
- function iconButton(icon, tip, { size = "mini" } = {}) {
1471
- const button = el("ui-button", { appearance: "circular basic", size, icon, title: tip, "aria-label": tip });
1472
- titleInside(button);
1473
- return button;
1873
+
1874
+ /** The slots made so far, for their unique names (`boxInMarkdown()`). */
1875
+ let threadSlots = 0
1876
+
1877
+ /** How long the toast saying a comment was deleted offers Undo, ms. */
1878
+ const UNDO_MS = 6000
1879
+
1880
+ /**
1881
+ * A control the comments draw (epic `epic-engine` I26; Owen, 2026-10-19: "Why are we not using <ui-xxxx> ...
1882
+ * components for these pages?"): a `<ui-button appearance="circular basic" size="mini">` with `icon`, never a raw `<button>`, so
1883
+ * the component centres its icon; `tip` its tooltip and name, on the inner button too (`titleInside()`).
1884
+ * - `size`: another size (Send's pill: `tiny`, as the New epic pill)
1885
+ */
1886
+ export function iconButton(icon, tip, { size = "mini" } = {}) {
1887
+ const button = el("ui-button", { appearance: "circular basic", size, icon, title: tip, "aria-label": tip })
1888
+ titleInside(button)
1889
+ return button
1474
1890
  }
1475
- __name(iconButton, "iconButton");
1891
+
1892
+ /** A docs section's first child in its body (not its slotted icon, header or actions); `null` for none. */
1476
1893
  function firstContentChild(section) {
1477
- return Array.from(section.children).find((child) => !child.hasAttribute("slot")) ?? null;
1894
+ return Array.from(section.children).find((child) => !child.hasAttribute("slot")) ?? null
1478
1895
  }
1479
- __name(firstContentChild, "firstContentChild");
1480
- var THREADS_TAG = "epic-threads";
1481
- var THREAD_TAG = "epic-thread";
1482
- var PANE_TAG = "epic-comment-pane";
1483
- var SEND_BUTTONS_TAG = "epic-send-buttons";
1484
- var SEND_ASKED = "epic-send-saving";
1485
- var HEAD_ROOM = "--epic-thread-head-room";
1896
+
1897
+ /** The epics pack's tags this draws (`<epic-thread>` ...): each upgrades as the pack registers. */
1898
+ const THREADS_TAG = "epic-threads"
1899
+ const THREAD_TAG = "epic-thread"
1900
+ const PANE_TAG = "epic-comment-pane"
1901
+ const SEND_BUTTONS_TAG = "epic-send-buttons"
1902
+
1903
+ /** `<epic-send-buttons>`' ask to send: a press on its plane, or its countdown running out. */
1904
+ const SEND_ASKED = "epic-send-saving"
1905
+
1906
+ /** The room a thread's header leaves on its right for a corner bullhorn above it (`makeRoom()`; `EpicThread.css`). */
1907
+ const HEAD_ROOM = "--epic-thread-head-room"
1908
+
1909
+ /** Put `child` at index `at` of `box`'s children, moving it only when it isn't there already (the cursor stays). */
1486
1910
  function placeAt(box, child, at) {
1487
- const there = box.children[at];
1488
- if (there !== child) box.insertBefore(child, there ?? null);
1911
+ const there = box.children[at]
1912
+ if (there !== child) box.insertBefore(child, there ?? null)
1489
1913
  }
1490
- __name(placeAt, "placeAt");
1914
+
1915
+ /** Set `element`'s attribute `name` to `value`; `undefined`: take it away. */
1491
1916
  function setOrDrop(element, name, value) {
1492
- if (value === void 0) element.removeAttribute(name);
1493
- else if (element.getAttribute(name) !== value) element.setAttribute(name, value);
1917
+ if (value === undefined) element.removeAttribute(name)
1918
+ else if (element.getAttribute(name) !== value) element.setAttribute(name, value)
1494
1919
  }
1495
- __name(setOrDrop, "setOrDrop");
1920
+
1921
+ /** Resolves once `element` (one of the pack's) is defined and has drawn. NEVER rejects. */
1496
1922
  async function drawn(element) {
1497
- await customElements.whenDefined(element.localName);
1498
- await element.ready?.catch(() => void 0);
1923
+ await customElements.whenDefined(element.localName)
1924
+ await element.ready?.catch(() => undefined)
1499
1925
  }
1500
- __name(drawn, "drawn");
1926
+
1927
+ /** The floppy's tooltip once saved: `Saved 14:02 · waiting for Claude`. */
1501
1928
  function savedTip() {
1502
- return `Saved ${ThreadFacts.localStamp((/* @__PURE__ */ new Date()).toISOString()).slice(11)} · waiting for Claude`;
1929
+ return `Saved ${ThreadFacts.localStamp(new Date().toISOString()).slice(11)} · waiting for Claude`
1503
1930
  }
1504
- __name(savedTip, "savedTip");
1931
+
1932
+ /** The floppy's tooltip when a save failed: why, and that the words are kept. */
1505
1933
  function notSavedTip(why) {
1506
- return `Not saved: ${why} (kept in this browser)`;
1934
+ return `Not saved: ${why} (kept in this browser)`
1507
1935
  }
1508
- __name(notSavedTip, "notSavedTip");
1509
- var bullhornBlocks = /* @__PURE__ */ new WeakMap();
1936
+
1937
+ /** Each bullhorn's block (`addBullhorn()`): what `draw()` checks a kept one against. */
1938
+ const bullhornBlocks = new WeakMap()
1939
+
1940
+ /**
1941
+ * Does bullhorn `mark` still stand by `block`: in its title row (a child of it), the page header's tools, or the
1942
+ * actions row just before it (`addBlockAction()`)?
1943
+ */
1510
1944
  function standsBy(mark, block) {
1511
- if (!mark.isConnected || !block.isConnected) return false;
1512
- if (mark.parentElement === block || mark.classList.contains("at-page")) return true;
1513
- const row = mark.closest(BLOCK_ROW);
1514
- return Boolean(row) && row.nextElementSibling === block;
1945
+ if (!mark.isConnected || !block.isConnected) return false
1946
+ if (mark.parentElement === block || mark.classList.contains("at-page")) return true
1947
+ const row = mark.closest(BLOCK_ROW)
1948
+ return Boolean(row) && row.nextElementSibling === block
1515
1949
  }
1516
- __name(standsBy, "standsBy");
1517
- export {
1518
- commentsOnPage,
1519
- firstWords,
1520
- iconButton,
1521
- wireComments
1522
- };