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,125 +1,232 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
-
4
- // src/tools/_assets/spell-doc-helpers.js
5
- import { copyText } from "spell/util/dom";
6
- import { PrefStore } from "spell/util/persist/PrefStore";
7
- import { PageNotices, ServerLink } from "../../review/index.js";
8
- var FIELDS = "input, textarea, select, ui-input, ui-select, ui-dropdown";
9
- function readJSON(key) {
10
- const value = PrefStore.getAt(key);
11
- return value && typeof value === "object" ? value : {};
12
- }
13
- __name(readJSON, "readJSON");
14
- function writeJSON(key, value) {
15
- PrefStore.setAt(key, value);
16
- }
17
- __name(writeJSON, "writeJSON");
18
- function beforeToolbar(head, pill) {
19
- const toolbar = head.querySelector(":scope > .spell-toolbar");
20
- if (toolbar) toolbar.before(pill);
21
- else head.append(pill);
22
- }
23
- __name(beforeToolbar, "beforeToolbar");
24
- function addHeadTool(head, tool, kind) {
25
- tool.dataset.headTool = kind;
26
- if (!head.matches(".spell-page-head")) return beforeToolbar(head, tool);
27
- let row = head.querySelector(":scope > .spell-head-tools");
1
+ /*
2
+ * Small helpers the docs pages' scripts share:
3
+ * - the data pages (`commands.entry.js`, `core-reference.entry.js`, `spell-syntax.entry.js`), bundled since epic
4
+ * `coherence` C12: their start (`drawThenBoot()`), notice, section numbers and page path
5
+ * - the page runtime (`spell-doc-runtime.js`)
6
+ * - the comments (`spell-doc-comments.js`) and the toolbar (`spell-doc-toolbar.js`),
7
+ * which Epic UI's pages load by themselves too (`spell-comments.js`)
8
+ * - Plain DOM, no Spell UI imports: the comments' own script runs beside the page's Spell UI, never with a second one
9
+ * (a toast goes through the page's `window.SpellUI`)
10
+ * - What they keep in the browser goes through the kit's `PrefStore` (generic: no Spell UI either)
11
+ */
12
+ import { copyText } from "spell/util/dom"
13
+ import { PrefStore } from "spell/util/persist/PrefStore"
14
+ import { PageNotices, ServerLink } from "spell/epic/review"
15
+
16
+ /** What types or picks: a key pressed in one is the field's (paging, the jump key). */
17
+ export const FIELDS = "input, textarea, select, ui-input, ui-select, ui-dropdown"
18
+
19
+ /**
20
+ * The object kept as JSON under `key`, a key named whole (`spell-folds:/x.html`), or `{}`: nothing kept, or not one.
21
+ * - NEVER throws: storage blocked or a value it can't read is `{}`, logged (`PrefStore`).
22
+ */
23
+ export function readJSON(key) {
24
+ const value = PrefStore.getAt(key)
25
+ return value && typeof value === "object" ? value : {}
26
+ }
27
+
28
+ /** Keep `value` as JSON under `key`; a browser that blocks storage keeps it for this page only. */
29
+ export function writeJSON(key, value) {
30
+ PrefStore.setAt(key, value)
31
+ }
32
+
33
+ /** Add `pill` to the page header `head`, before its toolbar (`buildPageToolbar()`): the toolbar stays its last row. */
34
+ export function beforeToolbar(head, pill) {
35
+ const toolbar = head.querySelector(":scope > .spell-toolbar")
36
+ if (toolbar) toolbar.before(pill)
37
+ else head.append(pill)
38
+ }
39
+
40
+ /**
41
+ * The page header's TOOLS ROW (epic `epic-engine` I38): ONE row at the right of the h1's line,
42
+ * holding what our tools put there, in `HEAD_TOOLS`' order, whoever adds first:
43
+ * 1. expand all and collapse all (`folds`)
44
+ * 2. the comments' Send
45
+ * 3. the page's own tools (the Epics page's New epic pill and sort)
46
+ * 4. the page's bullhorn, last at the right
47
+ * - one row, so they never overlap each other: the row overlaps a long title rather than wrapping (`spell-doc.css`)
48
+ * - they used to be placed apart, each at its own distance from the edge, and Send covered the New epic pill
49
+ * - a docs page's `.spell-page-head` only:
50
+ * any other head (Epic UI's masthead) takes the tool as before (`beforeToolbar()`)
51
+ * - made on first use, `data-spell-added` (a live update steps around it); `kind`: one of `HEAD_TOOLS`
52
+ */
53
+ export function addHeadTool(head, tool, kind) {
54
+ tool.dataset.headTool = kind
55
+ if (!head.matches(".spell-page-head")) return beforeToolbar(head, tool)
56
+ let row = head.querySelector(":scope > .spell-head-tools")
28
57
  if (!row) {
29
- row = el("span", { class: "spell-head-tools", "data-spell-added": true });
30
- beforeToolbar(head, row);
58
+ row = el("span", { class: "spell-head-tools", "data-spell-added": true })
59
+ beforeToolbar(head, row)
31
60
  }
32
- const rank = HEAD_TOOLS.indexOf(kind);
33
- const after = [...row.children].find((each) => HEAD_TOOLS.indexOf(each.dataset.headTool) > rank);
34
- row.insertBefore(tool, after ?? null);
35
- }
36
- __name(addHeadTool, "addHeadTool");
37
- var HEAD_TOOLS = ["send", "page", "comment"];
38
- function addBlockAction(block, control, kind) {
39
- let row = block.previousElementSibling;
61
+ const rank = HEAD_TOOLS.indexOf(kind)
62
+ const after = [...row.children].find((each) => HEAD_TOOLS.indexOf(each.dataset.headTool) > rank)
63
+ row.insertBefore(tool, after ?? null)
64
+ }
65
+
66
+ /** The page header's tools, in their order (`addHeadTool()`). */
67
+ const HEAD_TOOLS = ["send", "page", "comment"]
68
+
69
+ /**
70
+ * A block's ACTIONS ROW (epic `epic-engine` I26): the ONE row of a block's own controls,
71
+ * for a block with no title row of its own (a table, a paragraph, a list, a message ...).
72
+ * - an `<epic-actions>` (epic `epic-engine` P45), on every page (epic `coherence` P22):
73
+ * a line of no height just before the block, its buttons over the block's top right corner,
74
+ * placed and styled by the element itself
75
+ * - every page that draws one has the epics pack: the runtime loads it on every docs page (`loadEpicsPack()`),
76
+ * the component sets' layouts on theirs
77
+ * - Owen, 2026-10-19: "The expand button should be to the right of the bullhorn rather than in its own line"
78
+ * - every feature puts its control here, never in a row of its own, so they never overlap or float apart:
79
+ * the comments' bullhorn (`addBullhorn()`), a table's expand button (`wireTableWidths()`)
80
+ * - in `BLOCK_ACTIONS`' order, whoever adds first: the bullhorn, then the expand button
81
+ * - made on first use, `data-spell-added` (a live update steps around it);
82
+ * `dropBlockAction()` takes it away with its last control
83
+ * - `kind`: one of `BLOCK_ACTIONS`; returns the row
84
+ */
85
+ export function addBlockAction(block, control, kind) {
86
+ let row = block.previousElementSibling
40
87
  if (!row?.matches(BLOCK_ROW)) {
41
- row = el(BLOCK_ROW, { "data-spell-added": true });
42
- if (block.slot) row.slot = block.slot;
43
- block.before(row);
88
+ row = el(BLOCK_ROW, { "data-spell-added": true })
89
+ // a block slotted into an element (a docs example's description) takes its row with it:
90
+ // unslotted, the row landed in the element's default slot, somewhere else entirely
91
+ if (block.slot) row.slot = block.slot
92
+ block.before(row)
44
93
  }
45
- control.dataset.action = kind;
46
- const rank = BLOCK_ACTIONS.indexOf(kind);
47
- const after = [...row.children].find((each) => BLOCK_ACTIONS.indexOf(each.dataset.action) > rank);
48
- row.insertBefore(control, after ?? null);
49
- alignBlockActions(row);
50
- return row;
51
- }
52
- __name(addBlockAction, "addBlockAction");
53
- function dropBlockAction(control) {
54
- const row = control.closest(BLOCK_ROW);
55
- control.remove();
56
- if (row && !row.querySelector("[data-action]")) row.remove();
57
- }
58
- __name(dropBlockAction, "dropBlockAction");
59
- var BLOCK_ROW = "epic-actions";
60
- var BLOCK_ACTIONS = ["comment", "expand"];
61
- function alignBlockActions(root) {
62
- const rows = root.matches?.(BLOCK_ROW) ? [root] : [...root.querySelectorAll(BLOCK_ROW)];
94
+ control.dataset.action = kind
95
+ const rank = BLOCK_ACTIONS.indexOf(kind)
96
+ const after = [...row.children].find((each) => BLOCK_ACTIONS.indexOf(each.dataset.action) > rank)
97
+ row.insertBefore(control, after ?? null)
98
+ alignBlockActions(row)
99
+ return row
100
+ }
101
+
102
+ /** Take `control` away, and its block's actions row with it once that's empty (`addBlockAction()`). */
103
+ export function dropBlockAction(control) {
104
+ const row = control.closest(BLOCK_ROW)
105
+ control.remove()
106
+ if (row && !row.querySelector("[data-action]")) row.remove()
107
+ }
108
+
109
+ /** A block's actions row (`addBlockAction()`): its tag, and the selector that finds one. */
110
+ export const BLOCK_ROW = "epic-actions"
111
+
112
+ /** The controls of a block's actions row, in their order: the bullhorn first (`addBlockAction()`). */
113
+ const BLOCK_ACTIONS = ["comment", "expand"]
114
+
115
+ /**
116
+ * Put the buttons of every actions row in `root` (or the one row `root` is) over their block's top edge, 2px in:
117
+ * the row is a line of no height just before the block, but the block's own top margin (a table's 12px, a list's)
118
+ * may lie between them, or collapse into the margin above: CSS can't know which, so this measures it
119
+ * (`--spell-block-gap`, read by `<epic-actions>`' own sheet).
120
+ * - a table's buttons are centred on its header row (its first row):
121
+ * the gap down to that ROW's top (the table's own top border lies above it), its height, `--spell-block-head`,
122
+ * and the row marked `head-row`
123
+ * - to the hundredth of a pixel, not whole pixels: the gap to the TABLE's top, and both rounded,
124
+ * left the expand button 1.65px above the row's middle (epic `epic-engine` r1, the repo-split analysis page's Q5)
125
+ * - all reads, then all writes
126
+ * - a row or block not drawn (a folded section's) is skipped until it shows:
127
+ * its callers run again on a resize (the comments' `makeRoom()`, a table's `place()`)
128
+ */
129
+ export function alignBlockActions(root) {
130
+ const rows = root.matches?.(BLOCK_ROW) ? [root] : [...root.querySelectorAll(BLOCK_ROW)]
63
131
  const sizes = rows.map((row) => {
64
- const block = row.nextElementSibling;
65
- if (!block || !row.getClientRects().length || !block.getClientRects().length) return void 0;
66
- const head = block.querySelector("tr")?.getBoundingClientRect();
67
- const top = head?.height ? head.top : block.getBoundingClientRect().top;
68
- return { gap: pixels(top - row.getBoundingClientRect().top), head: head?.height ? pixels(head.height) : void 0 };
69
- });
132
+ const block = row.nextElementSibling
133
+ if (!block || !row.getClientRects().length || !block.getClientRects().length) return undefined
134
+ const head = block.querySelector("tr")?.getBoundingClientRect()
135
+ const top = head?.height ? head.top : block.getBoundingClientRect().top
136
+ return { gap: pixels(top - row.getBoundingClientRect().top), head: head?.height ? pixels(head.height) : undefined }
137
+ })
70
138
  rows.forEach((row, at) => {
71
- const size = sizes[at];
72
- if (!size) return;
139
+ const size = sizes[at]
140
+ if (!size) return
73
141
  for (const [name, value] of [
74
142
  ["--spell-block-gap", size.gap],
75
143
  ["--spell-block-head", size.head]
76
144
  ]) {
77
- if (value === void 0) row.style.removeProperty(name);
78
- else if (row.style.getPropertyValue(name) !== value) row.style.setProperty(name, value);
145
+ if (value === undefined) row.style.removeProperty(name)
146
+ else if (row.style.getPropertyValue(name) !== value) row.style.setProperty(name, value)
79
147
  }
80
- row.toggleAttribute("head-row", !!size.head);
81
- });
148
+ row.toggleAttribute("head-row", !!size.head)
149
+ })
82
150
  }
83
- __name(alignBlockActions, "alignBlockActions");
151
+
152
+ /** `value` px as CSS, to the hundredth. */
84
153
  function pixels(value) {
85
- return `${Math.round(value * 100) / 100}px`;
86
- }
87
- __name(pixels, "pixels");
88
- function titleInside(host, part = "button") {
89
- const copy = /* @__PURE__ */ __name(() => {
90
- const inner = host.shadowRoot?.querySelector(`[part~="${part}"]`);
91
- if (inner) inner.title = host.title;
92
- return !!inner;
93
- }, "copy");
94
- if (!copy()) void customElements.whenDefined(host.localName).then(() => requestAnimationFrame(copy));
95
- }
96
- __name(titleInside, "titleInside");
97
- function el(tag, attributes = {}, ...children) {
98
- const node = document.createElement(tag);
154
+ return `${Math.round(value * 100) / 100}px`
155
+ }
156
+
157
+ /**
158
+ * Put `host`'s `title` (a `<ui-button>`'s) on the button inside it too, once drawn: the element the pointer lands
159
+ * on carries the tooltip itself (Owen, 2026-10-10: "No tooltip on those same buttons"), as an epic page item's note
160
+ * buttons do, rather than leaving the browser to find it on the shadow host.
161
+ * - `part`: the inner box's part, `button` (a `<ui-button>`), or `item` (a `<ui-item>`: the toolbar's buttons)
162
+ * - again after the title changes: it copies at once when the box is drawn
163
+ */
164
+ export function titleInside(host, part = "button") {
165
+ const copy = () => {
166
+ const inner = host.shadowRoot?.querySelector(`[part~="${part}"]`)
167
+ if (inner) inner.title = host.title
168
+ return !!inner
169
+ }
170
+ if (!copy()) void customElements.whenDefined(host.localName).then(() => requestAnimationFrame(copy))
171
+ }
172
+
173
+ /**
174
+ * A new `tag` with `attributes`, holding `children` (nodes or text): how the runtime draws its elements, never an
175
+ * HTML string (epic `epic-engine` P3).
176
+ * - an attribute `undefined` or `false` is left out; `true` or `""` is set bare (`selected`)
177
+ * - a child `undefined`, `null`, `false` or `""` is skipped
178
+ */
179
+ export function el(tag, attributes = {}, ...children) {
180
+ const node = document.createElement(tag)
99
181
  for (const [name, value] of Object.entries(attributes))
100
- if (value !== void 0 && value !== false) node.setAttribute(name, value === true ? "" : String(value));
101
- node.append(...children.filter((child) => child !== void 0 && child !== null && child !== false && child !== ""));
102
- return node;
182
+ if (value !== undefined && value !== false) node.setAttribute(name, value === true ? "" : String(value))
183
+ node.append(...children.filter((child) => child !== undefined && child !== null && child !== false && child !== ""))
184
+ return node
103
185
  }
104
- __name(el, "el");
105
- function growField(field) {
106
- field.style.height = "auto";
107
- field.style.height = `${field.scrollHeight + 2}px`;
186
+
187
+ /** `field` as tall as its text (between its CSS `min-height` and `max-height`). */
188
+ export function growField(field) {
189
+ field.style.height = "auto"
190
+ field.style.height = `${field.scrollHeight + 2}px`
108
191
  }
109
- __name(growField, "growField");
110
- function noteToast(message, type, { displayTime = 3e3, actions } = {}) {
111
- PageNotices.show(message, { tone: type ?? "plain", ms: displayTime, actions });
192
+
193
+ /**
194
+ * A notice at the bottom of the window, in the page's ONE stack with an epic page's ("Sent 2 marks to Claude"):
195
+ * `PageNotices` (Owen, 2026-10-29: "Make the latter look like the former, but green, and put it in the same toast
196
+ * stack"; Spell UI's `UI.toast()`, at the top, before).
197
+ * - `type`: `success` green, `error` red, `warning` orange; none: the plain one
198
+ * - `displayTime`: ms, 3s unless given; `actions`: its buttons (`{ text, icon, click }`), at its end
199
+ * - NEVER throws
200
+ */
201
+ export function noteToast(message, type, { displayTime = 3000, actions } = {}) {
202
+ PageNotices.show(message, { tone: type ?? "plain", ms: displayTime, actions })
112
203
  }
113
- __name(noteToast, "noteToast");
114
- function addCodeCopies(root) {
204
+
205
+ ////////////////
206
+ // ## Code blocks
207
+ ////////////////
208
+
209
+ /**
210
+ * A copy button at the LEFT of every code block's first line in `root`: a `<pre><code>` written in a page
211
+ * (Owen, 2026-10-29, epic `epic-engine` I182: "this should have a copy icon on the left").
212
+ * - the button is the pre's first child (`.spell-code-copy`, `data-spell-added` so a live patch steps around it);
213
+ * `spell-doc.css` makes the pre a row, the button then the code, and the CODE the part that scrolls,
214
+ * so the button stays put while a long line scrolls
215
+ * - a click puts the code's text on the clipboard (`copyText()`), and says "Copied" in the page's notice stack
216
+ * - never twice: a block that has one keeps it; safe to call again after every live update
217
+ * - NOT `<epic-code>` and `<ui-code>`: Spell UI's `<ui-code copy>` draws their own button
218
+ * - NOT a `<pre>` with no `<code>` in it (a drawing in text): nothing to run or paste
219
+ */
220
+ export function addCodeCopies(root) {
115
221
  for (const code of root.querySelectorAll("pre > code")) {
116
- const pre = code.parentElement;
117
- const hasOne = Array.from(pre.children).some((child) => child.classList.contains(CODE_COPY));
118
- if (hasOne || pre.closest(OWN_COPY) || !code.textContent.trim()) continue;
119
- pre.prepend(codeCopyButton(code));
222
+ const pre = code.parentElement
223
+ const hasOne = Array.from(pre.children).some((child) => child.classList.contains(CODE_COPY))
224
+ if (hasOne || pre.closest(OWN_COPY) || !code.textContent.trim()) continue
225
+ pre.prepend(codeCopyButton(code))
120
226
  }
121
227
  }
122
- __name(addCodeCopies, "addCodeCopies");
228
+
229
+ /** The copy button of `code`'s block (`addCodeCopies()`). */
123
230
  function codeCopyButton(code) {
124
231
  const button = el("ui-button", {
125
232
  class: CODE_COPY,
@@ -129,82 +236,108 @@ function codeCopyButton(code) {
129
236
  title: COPY_LABEL,
130
237
  "aria-label": COPY_LABEL,
131
238
  "data-spell-added": true
132
- });
239
+ })
133
240
  button.addEventListener("click", async () => {
134
- if (await copyText(code.textContent)) noteToast("Copied");
135
- else noteToast("Couldn't copy: the browser said no", "error");
136
- });
137
- return button;
138
- }
139
- __name(codeCopyButton, "codeCopyButton");
140
- var CODE_COPY = "spell-code-copy";
141
- var COPY_LABEL = "Copy";
142
- var OWN_COPY = "epic-code, ui-code";
143
- function drawThenBoot({ load, draw, holder, header, offServer, failure }) {
144
- const bundle = new URL("spell-ui.js", document.currentScript?.src ?? location.href).href;
241
+ if (await copyText(code.textContent)) noteToast("Copied")
242
+ else noteToast("Couldn't copy: the browser said no", "error")
243
+ })
244
+ return button
245
+ }
246
+
247
+ /** Class of a code block's copy button. */
248
+ const CODE_COPY = "spell-code-copy"
249
+
250
+ /** The copy button's name and tooltip. */
251
+ const COPY_LABEL = "Copy"
252
+
253
+ /** Code blocks that draw their own copy button. */
254
+ const OWN_COPY = "epic-code, ui-code"
255
+
256
+ ////////////////
257
+ // ## Data pages
258
+ ////////////////
259
+
260
+ /**
261
+ * A DATA PAGE's start (the commands page, the core reference, the syntax page; epic `coherence` C12):
262
+ * `load()` its data, `draw(data)` it into the page, then boot the docs bundle, `spell-ui.js` beside this script,
263
+ * whatever happened; resolves to the data, or `undefined` (none, or it failed).
264
+ * - why this order: the runtime builds the toolbar and the sticky titles from `main`'s sections once, at start,
265
+ * so the drawn sections must be in the page before it runs
266
+ * - `load()` reads its files through the page's `ServerLink` (`getFile()`), the checkout serving the page
267
+ * - what it can't draw, it says in a warning headed `header`, first where its drawing goes (`holder`, a selector;
268
+ * else `main`'s top):
269
+ * - from `file://`, `offServer`, "This page draws its tables from commands.json5", and how to open it served:
270
+ * it reads nothing there (`ServerLink.canRead()`), and loads nothing
271
+ * - a failure, `failure`, "Couldn't draw the tables", and why
272
+ * - MUST be called as the script runs: it finds the bundle beside `document.currentScript`
273
+ */
274
+ export function drawThenBoot({ load, draw, holder, header, offServer, failure }) {
275
+ const bundle = new URL("spell-ui.js", document.currentScript?.src ?? location.href).href
145
276
  return (async () => {
146
- let data;
277
+ let data
147
278
  try {
148
279
  if (!ServerLink.canRead())
149
- notice(`${offServer}: open it through the page server, e.g. \`epic pages open ${pagePath()}\`.`);
150
- else data = await load();
151
- if (data) draw(data);
280
+ notice(`${offServer}: open it through the page server, e.g. \`epic pages open ${pagePath()}\`.`)
281
+ else data = await load()
282
+ if (data) draw(data)
152
283
  } catch (error) {
153
- notice(`${failure}: ${error.message}`);
154
- data = void 0;
284
+ notice(`${failure}: ${error.message}`)
285
+ data = undefined
155
286
  }
156
- document.body.append(el("script", { src: bundle }));
157
- return data;
158
- })();
287
+ document.body.append(el("script", { src: bundle }))
288
+ return data
289
+ })()
290
+
291
+ /** Show `message` (its `` `code` `` as code) in a warning headed `header`, first in `holder` (else `main`). */
159
292
  function notice(message) {
160
- ;
161
- (document.querySelector(holder) ?? document.querySelector("main"))?.prepend(
293
+ ;(document.querySelector(holder) ?? document.querySelector("main"))?.prepend(
162
294
  el("ui-message", { state: "warning", heading: header }, el("p", {}, ...withCode(message)))
163
- );
295
+ )
164
296
  }
165
- __name(notice, "notice");
166
297
  }
167
- __name(drawThenBoot, "drawThenBoot");
168
- function withCode(value, plain = (part) => [part]) {
169
- return String(value).split("`").flatMap((part, i) => i % 2 ? [el("code", {}, part)] : plain(part)).filter((part) => part !== "");
298
+
299
+ /**
300
+ * `value` as nodes: its `` `code` `` spans as `<code>`, the rest as text, never markup; each text part through
301
+ * `plain()` (default: as it is), which may make nodes of it (a link).
302
+ */
303
+ export function withCode(value, plain = (part) => [part]) {
304
+ return String(value)
305
+ .split("`")
306
+ .flatMap((part, i) => (i % 2 ? [el("code", {}, part)] : plain(part)))
307
+ .filter((part) => part !== "")
170
308
  }
171
- __name(withCode, "withCode");
172
- function sectionNumber(section) {
173
- return /^\s*(\d+(?:\.\d+)*)\.?\s/.exec(section?.getAttribute("label") ?? "")?.[1] ?? "";
309
+
310
+ /** The leading number of `section`'s label (`2` for "2. Operations", `3.1` for "3.1 Files"), or `""`. */
311
+ export function sectionNumber(section) {
312
+ return /^\s*(\d+(?:\.\d+)*)\.?\s/.exec(section?.getAttribute("label") ?? "")?.[1] ?? ""
174
313
  }
175
- __name(sectionNumber, "sectionNumber");
176
- function pagePath() {
177
- return decodeURIComponent(location.pathname).replace(/^.*\/(?=(?:guides|epics|templates|pages)\/)/, "");
314
+
315
+ /** This page's path from the epic folder's root (`guides/...`): what `epic pages open` takes. */
316
+ export function pagePath() {
317
+ return decodeURIComponent(location.pathname).replace(/^.*\/(?=(?:guides|epics|templates|pages)\/)/, "")
178
318
  }
179
- __name(pagePath, "pagePath");
180
- var STAYS_FOLDED = 'epic-section[kind="log"]';
181
- function restoreEpicFolds(blocks, { saved, kept }) {
319
+
320
+ /**
321
+ * An epic page's blocks that start FOLDED on every load, whatever the reader left them as: the Log.
322
+ * - Owen, 2026-10-29 (epic `epic-engine` I155): "epic log: Should start out collapsed always"
323
+ * - a link to it, or to an id inside it, still opens it (the block follows the address itself); so does a click
324
+ * - the page's expand-all leaves it folded too: `<epic-section>`'s `staysFolded`, the same kinds
325
+ * (`STAYS_FOLDED_KINDS`, `EpicSection.types.ts`)
326
+ */
327
+ export const STAYS_FOLDED = 'epic-section[kind="log"]'
328
+
329
+ /**
330
+ * Open again the epic page blocks `blocks` the reader left open, before they first draw (their `open` attribute),
331
+ * so nothing animates; the rest start folded, as the blocks do.
332
+ * - `saved`: the page's saved folds (`{ [id]: folded }`, `spell-folds:<path>`)
333
+ * - `kept`: after a live reload, every block and item open before it (`{ [id]: open }`), whoever opened it;
334
+ * over `saved`
335
+ * - NEVER a block that stays folded (`STAYS_FOLDED`): folded on every load
336
+ */
337
+ export function restoreEpicFolds(blocks, { saved, kept }) {
182
338
  for (const block of blocks) {
183
- if (!block.id || block.matches(STAYS_FOLDED)) continue;
184
- if (kept && block.id in kept) block.toggleAttribute("open", kept[block.id]);
185
- else if (saved[block.id] === false) block.setAttribute("open", "");
339
+ if (!block.id || block.matches(STAYS_FOLDED)) continue
340
+ if (kept && block.id in kept) block.toggleAttribute("open", kept[block.id])
341
+ else if (saved[block.id] === false) block.setAttribute("open", "")
186
342
  }
187
343
  }
188
- __name(restoreEpicFolds, "restoreEpicFolds");
189
- export {
190
- BLOCK_ROW,
191
- FIELDS,
192
- STAYS_FOLDED,
193
- addBlockAction,
194
- addCodeCopies,
195
- addHeadTool,
196
- alignBlockActions,
197
- beforeToolbar,
198
- drawThenBoot,
199
- dropBlockAction,
200
- el,
201
- growField,
202
- noteToast,
203
- pagePath,
204
- readJSON,
205
- restoreEpicFolds,
206
- sectionNumber,
207
- titleInside,
208
- withCode,
209
- writeJSON
210
- };