spell 0.8.7 → 0.8.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (304) hide show
  1. package/README-epics.md +149 -49
  2. package/app/package.json +25 -1
  3. package/app/spaces/@spell/guides/SpellUI/SpellUI.spellml +486 -486
  4. package/app/spaces/@spell/sites/SpellApp/SpellApp.spellml +50 -124
  5. package/dist/app/app/pages/SiteBoardView.css +5 -5
  6. package/dist/app/app/pages/SiteBoardView.js +1 -1
  7. package/dist/app/app/pages/SiteEditorPage.js +6 -3
  8. package/dist/app/app/pages/SiteEdits.js +27 -10
  9. package/dist/app/app/pages/SiteWrites.js +11 -0
  10. package/dist/app/app/runner/spellRuntime.js +1 -0
  11. package/dist/cli/publish/PublishedPackage.d.ts +2 -1
  12. package/dist/cli/publish/PublishedPackage.js +6 -3
  13. package/dist/cli/publish/ScratchInstall.d.ts +14 -3
  14. package/dist/cli/publish/ScratchInstall.js +69 -8
  15. package/dist/epic/cli/EpicProgram.js +20 -5
  16. package/dist/epic/cli/epicGroups.js +7 -1
  17. package/dist/epic/command/BaseBranch.d.ts +35 -0
  18. package/dist/epic/command/BaseBranch.js +58 -0
  19. package/dist/epic/command/EpicCheckout.d.ts +1 -1
  20. package/dist/epic/command/EpicCheckout.js +4 -4
  21. package/dist/epic/command/EpicGuide.js +3 -2
  22. package/dist/epic/command/EpicTools.d.ts +5 -0
  23. package/dist/epic/command/EpicTools.js +14 -3
  24. package/dist/epic/command/MainMerge.d.ts +26 -15
  25. package/dist/epic/command/MainMerge.js +60 -16
  26. package/dist/epic/command/PullRequest.d.ts +45 -0
  27. package/dist/epic/command/PullRequest.js +100 -0
  28. package/dist/epic/command/RepoInit.d.ts +196 -39
  29. package/dist/epic/command/RepoInit.js +481 -60
  30. package/dist/epic/command/Requests.d.ts +1 -0
  31. package/dist/epic/command/Requests.js +7 -1
  32. package/dist/epic/command/SessionMoves.js +2 -1
  33. package/dist/epic/command/SkillsCheck.js +3 -2
  34. package/dist/epic/command/Stock.js +3 -1
  35. package/dist/epic/command/TurnEnd.d.ts +1 -1
  36. package/dist/epic/command/TurnEnd.js +4 -3
  37. package/dist/epic/command/Worktrees.d.ts +20 -3
  38. package/dist/epic/command/Worktrees.js +39 -7
  39. package/dist/epic/command/command.types.d.ts +3 -0
  40. package/dist/epic/components/__pack/epics.entry.js +43 -43
  41. package/dist/epic/components/__pack/epics.pack.js +36 -12794
  42. package/dist/epic/config/CodeHost.d.ts +96 -0
  43. package/dist/epic/config/CodeHost.js +89 -0
  44. package/dist/epic/config/EngineFiles.mjs +60 -0
  45. package/dist/epic/config/EpicConfig.d.ts +20 -3
  46. package/dist/epic/config/EpicConfig.js +25 -1
  47. package/dist/epic/config/EpicRepo.js +1 -1
  48. package/dist/epic/config/GitHub.d.ts +75 -3
  49. package/dist/epic/config/GitHub.js +106 -5
  50. package/dist/epic/config/GitLab.d.ts +138 -0
  51. package/dist/epic/config/GitLab.js +297 -0
  52. package/dist/epic/config/LayeredSettings.js +3 -2
  53. package/dist/epic/server/EpicServer.d.ts +1 -1
  54. package/dist/epic/server/EpicServer.js +26 -12
  55. package/dist/epic/tool/InboxPoller.mjs +2 -1
  56. package/dist/epic/tool/MigrateCommands.js +6 -8
  57. package/dist/epic/tool/PlanCommits.d.ts +7 -4
  58. package/dist/epic/tool/PlanCommits.js +7 -5
  59. package/dist/epic/tool/PlanDocCommands.js +3 -4
  60. package/dist/epic/tool/PlanDocFiles.d.ts +3 -1
  61. package/dist/epic/tool/PlanDocFiles.js +13 -5
  62. package/dist/epic/tool/ServedFolders.d.ts +1 -1
  63. package/dist/epic/tool/ServedFolders.js +4 -4
  64. package/dist/epic/tools/PageInboxes.js +3 -3
  65. package/dist/epic/tools/_assets/commands.entry.js +149 -68
  66. package/dist/epic/tools/_assets/commands.js +20 -2073
  67. package/dist/epic/tools/_assets/core-reference.entry.js +244 -124
  68. package/dist/epic/tools/_assets/core-reference.js +20 -2142
  69. package/dist/epic/tools/_assets/emoji/cldr/0.js +2 -2
  70. package/dist/epic/tools/_assets/emoji/cldr/a.js +2 -2
  71. package/dist/epic/tools/_assets/emoji/cldr/b.js +2 -2
  72. package/dist/epic/tools/_assets/emoji/cldr/c.js +2 -2
  73. package/dist/epic/tools/_assets/emoji/cldr/d.js +2 -2
  74. package/dist/epic/tools/_assets/emoji/cldr/e.js +2 -2
  75. package/dist/epic/tools/_assets/emoji/cldr/f.js +2 -2
  76. package/dist/epic/tools/_assets/emoji/cldr/g.js +2 -2
  77. package/dist/epic/tools/_assets/emoji/cldr/h.js +2 -2
  78. package/dist/epic/tools/_assets/emoji/cldr/i.js +2 -2
  79. package/dist/epic/tools/_assets/emoji/cldr/j.js +2 -2
  80. package/dist/epic/tools/_assets/emoji/cldr/k.js +2 -2
  81. package/dist/epic/tools/_assets/emoji/cldr/l.js +2 -2
  82. package/dist/epic/tools/_assets/emoji/cldr/m.js +2 -2
  83. package/dist/epic/tools/_assets/emoji/cldr/n.js +2 -2
  84. package/dist/epic/tools/_assets/emoji/cldr/o.js +2 -2
  85. package/dist/epic/tools/_assets/emoji/cldr/p.js +2 -2
  86. package/dist/epic/tools/_assets/emoji/cldr/r.js +2 -2
  87. package/dist/epic/tools/_assets/emoji/cldr/s.js +2 -2
  88. package/dist/epic/tools/_assets/emoji/cldr/t.js +2 -2
  89. package/dist/epic/tools/_assets/emoji/cldr/u.js +2 -2
  90. package/dist/epic/tools/_assets/emoji/cldr/v.js +2 -2
  91. package/dist/epic/tools/_assets/emoji/cldr/w.js +2 -2
  92. package/dist/epic/tools/_assets/emoji/cldr/x.js +2 -2
  93. package/dist/epic/tools/_assets/emoji/cldr/y.js +2 -2
  94. package/dist/epic/tools/_assets/emoji/cldr/z.js +2 -2
  95. package/dist/epic/tools/_assets/emoji/fomantic/0.js +2 -2
  96. package/dist/epic/tools/_assets/emoji/fomantic/a.js +2 -2
  97. package/dist/epic/tools/_assets/emoji/fomantic/b.js +2 -2
  98. package/dist/epic/tools/_assets/emoji/fomantic/c.js +2 -2
  99. package/dist/epic/tools/_assets/emoji/fomantic/d.js +2 -2
  100. package/dist/epic/tools/_assets/emoji/fomantic/e.js +2 -2
  101. package/dist/epic/tools/_assets/emoji/fomantic/f.js +2 -2
  102. package/dist/epic/tools/_assets/emoji/fomantic/g.js +2 -2
  103. package/dist/epic/tools/_assets/emoji/fomantic/h.js +2 -2
  104. package/dist/epic/tools/_assets/emoji/fomantic/i.js +2 -2
  105. package/dist/epic/tools/_assets/emoji/fomantic/j.js +2 -2
  106. package/dist/epic/tools/_assets/emoji/fomantic/k.js +2 -2
  107. package/dist/epic/tools/_assets/emoji/fomantic/l.js +2 -2
  108. package/dist/epic/tools/_assets/emoji/fomantic/m.js +2 -2
  109. package/dist/epic/tools/_assets/emoji/fomantic/n.js +2 -2
  110. package/dist/epic/tools/_assets/emoji/fomantic/o.js +2 -2
  111. package/dist/epic/tools/_assets/emoji/fomantic/p.js +2 -2
  112. package/dist/epic/tools/_assets/emoji/fomantic/q.js +2 -2
  113. package/dist/epic/tools/_assets/emoji/fomantic/r.js +2 -2
  114. package/dist/epic/tools/_assets/emoji/fomantic/s.js +2 -2
  115. package/dist/epic/tools/_assets/emoji/fomantic/t.js +2 -2
  116. package/dist/epic/tools/_assets/emoji/fomantic/u.js +2 -2
  117. package/dist/epic/tools/_assets/emoji/fomantic/v.js +2 -2
  118. package/dist/epic/tools/_assets/emoji/fomantic/w.js +2 -2
  119. package/dist/epic/tools/_assets/emoji/fomantic/x.js +2 -2
  120. package/dist/epic/tools/_assets/emoji/fomantic/y.js +2 -2
  121. package/dist/epic/tools/_assets/emoji/fomantic/z.js +2 -2
  122. package/dist/epic/tools/_assets/goals-live.js +318 -210
  123. package/dist/epic/tools/_assets/highlight.min.js +5764 -5269
  124. package/dist/epic/tools/_assets/lazy/code-engine.js +5 -1270
  125. package/dist/epic/tools/_assets/lazy/markdown-engine.js +67 -1513
  126. package/dist/epic/tools/_assets/lazy/markdown-sanitizer.js +3 -753
  127. package/dist/epic/tools/_assets/spell-comments.entry.js +282 -159
  128. package/dist/epic/tools/_assets/spell-comments.js +24 -3716
  129. package/dist/epic/tools/_assets/spell-doc-comments.js +1243 -816
  130. package/dist/epic/tools/_assets/spell-doc-helpers.js +298 -165
  131. package/dist/epic/tools/_assets/spell-doc-runtime.js +2760 -1415
  132. package/dist/epic/tools/_assets/spell-doc-toolbar.js +396 -227
  133. package/dist/epic/tools/_assets/spell-syntax.entry.js +505 -285
  134. package/dist/epic/tools/_assets/spell-syntax.js +22 -2916
  135. package/dist/epic/tools/_assets/spell-ui-sources.js +102 -60
  136. package/dist/epic/tools/_assets/spell-ui.entry.js +108 -40
  137. package/dist/epic/tools/_assets/spell-ui.js +3131 -46465
  138. package/dist/epic/tools/pages.d.ts +5 -6
  139. package/dist/epic/tools/pages.js +7 -6
  140. package/dist/epic/window.mjs +2 -3
  141. package/dist/parser/core/classes/View.d.ts +20 -0
  142. package/dist/parser/core/classes/View.js +91 -17
  143. package/dist/parser/core/core.declarations.json5 +18 -0
  144. package/dist/parser/core/core.scopes.js +5 -0
  145. package/dist/parser/core/sites.d.ts +10 -0
  146. package/dist/parser/core/sites.js +12 -0
  147. package/dist/parser/parser/tokenizer/Tokenizer.d.ts +9 -1
  148. package/dist/parser/parser/tokenizer/Tokenizer.js +43 -5
  149. package/dist/parser/parser/tokenizer/Tokens.d.ts +4 -0
  150. package/dist/parser/parser/tokenizer/Tokens.js +4 -0
  151. package/dist/parser/parser/tokenizer/tokenizer.types.d.ts +5 -0
  152. package/dist/parser/parser/tokenizer/tokenizer.types.js +2 -0
  153. package/dist/parser/py/core/spell_core/apps.py +2 -0
  154. package/dist/parser/spell/PARSING.md +21 -0
  155. package/dist/parser/spell/SpellParser.d.ts +2 -0
  156. package/dist/parser/spell/SpellParser.js +58 -3
  157. package/dist/parser/spell/SpellxTokenizer.js +2 -1
  158. package/dist/parser/spell/SpellxTwin.d.ts +4 -1
  159. package/dist/parser/spell/SpellxTwin.js +10 -3
  160. package/dist/parser/spell/builtinTypes.js +24 -1
  161. package/dist/parser/spell/ingest/PlaceIngest.js +3 -1
  162. package/dist/parser/spell/languages/Language.d.ts +11 -2
  163. package/dist/parser/spell/languages/en/words.js +3 -2
  164. package/dist/parser/spell/languages/es/words.js +7 -4
  165. package/dist/parser/spell/rules/Statement.js +1 -1
  166. package/dist/parser/spell/rules/classes/DrawSlot.js +6 -1
  167. package/dist/parser/spell/rules/sites/SitePage.d.ts +3 -3
  168. package/dist/parser/spell/rules/sites/SitePage.js +2 -2
  169. package/dist/parser/spell/rules/sites/sites.en.js +1 -1
  170. package/dist/parser/spell/rules/sites/sites.es.js +1 -1
  171. package/dist/parser/spell/rules/sites/sites.shared.d.ts +2 -2
  172. package/dist/parser/spell/spell.types.d.ts +7 -0
  173. package/dist/parser/spell/spellSyntax.es.json +6 -6
  174. package/dist/parser/spell/spellSyntax.json +6 -6
  175. package/dist/parser/spellx/SpellxView.js +2 -1
  176. package/dist/ui/components/ui-accordion/UIAccordion.d.ts +1 -0
  177. package/dist/ui/components/ui-ad/UIAd.d.ts +1 -0
  178. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumb.d.ts +1 -0
  179. package/dist/ui/components/ui-breadcrumbs/UIBreadcrumbs.d.ts +1 -0
  180. package/dist/ui/components/ui-button/UIButton.d.ts +8 -3
  181. package/dist/ui/components/ui-button/UIButton.fallback.d.ts +8 -3
  182. package/dist/ui/components/ui-button/UIButtons.d.ts +1 -0
  183. package/dist/ui/components/ui-button/UIOr.d.ts +1 -0
  184. package/dist/ui/components/ui-calendar/UICalendar.d.ts +6 -0
  185. package/dist/ui/components/ui-calendar/UICalendar.fallback.d.ts +6 -0
  186. package/dist/ui/components/ui-card/UICards.d.ts +31 -0
  187. package/dist/ui/components/ui-checkbox/UICheckbox.d.ts +7 -0
  188. package/dist/ui/components/ui-checkbox/UICheckbox.fallback.d.ts +7 -0
  189. package/dist/ui/components/ui-comment/UIComment.d.ts +1 -0
  190. package/dist/ui/components/ui-comment/UIComments.d.ts +1 -0
  191. package/dist/ui/components/ui-components/UIComponents.d.ts +1 -0
  192. package/dist/ui/components/ui-dimmer/UIDimmer.d.ts +1 -0
  193. package/dist/ui/components/ui-divider/UIDivider.d.ts +2 -0
  194. package/dist/ui/components/ui-dropdown/UIDropdown.d.ts +6 -0
  195. package/dist/ui/components/ui-dropdown/UIDropdown.fallback.d.ts +6 -0
  196. package/dist/ui/components/ui-embed/UIEmbed.d.ts +1 -0
  197. package/dist/ui/components/ui-emoji/UIEmoji.d.ts +1 -0
  198. package/dist/ui/components/ui-feed/UIFeed.d.ts +1 -0
  199. package/dist/ui/components/ui-feed/UIFeedEvent.d.ts +1 -0
  200. package/dist/ui/components/ui-flag/UIFlag.d.ts +1 -0
  201. package/dist/ui/components/ui-flyout/UIFlyout.d.ts +1 -0
  202. package/dist/ui/components/ui-form/UIFields.d.ts +1 -0
  203. package/dist/ui/components/ui-form/UIRepeat.d.ts +1 -0
  204. package/dist/ui/components/ui-grid/UIColumn.d.ts +1 -0
  205. package/dist/ui/components/ui-grid/UIGrid.d.ts +1 -0
  206. package/dist/ui/components/ui-grid/UIRow.d.ts +1 -0
  207. package/dist/ui/components/ui-icon/UIIcon.d.ts +3 -2
  208. package/dist/ui/components/ui-icon/UIIcons.d.ts +1 -0
  209. package/dist/ui/components/ui-icon-picker/UIIconPicker.d.ts +6 -0
  210. package/dist/ui/components/ui-icon-picker/UIIconPicker.fallback.d.ts +6 -0
  211. package/dist/ui/components/ui-image/UIImages.d.ts +1 -0
  212. package/dist/ui/components/ui-include/UIInclude.d.ts +1 -0
  213. package/dist/ui/components/ui-input/UIInput.fallback.d.ts +9 -2
  214. package/dist/ui/components/ui-items/UIItems.d.ts +1 -0
  215. package/dist/ui/components/ui-keys/UIKeys.d.ts +1 -0
  216. package/dist/ui/components/ui-label/UILabel.d.ts +2 -0
  217. package/dist/ui/components/ui-label/UILabels.d.ts +1 -0
  218. package/dist/ui/components/ui-list/UIList.d.ts +2 -0
  219. package/dist/ui/components/ui-loader/UILoader.d.ts +1 -0
  220. package/dist/ui/components/ui-message/UIMessage.d.ts +2 -0
  221. package/dist/ui/components/ui-modal/UIModal.d.ts +1 -0
  222. package/dist/ui/components/ui-nag/UINag.d.ts +1 -0
  223. package/dist/ui/components/ui-page/UIPage.d.ts +15 -0
  224. package/dist/ui/components/ui-page/UIPage.es.d.ts +1 -0
  225. package/dist/ui/components/ui-parts/UIActions.d.ts +1 -0
  226. package/dist/ui/components/ui-parts/UIAuthor.d.ts +1 -0
  227. package/dist/ui/components/ui-parts/UIAvatar.d.ts +1 -0
  228. package/dist/ui/components/ui-parts/UIContent.d.ts +1 -0
  229. package/dist/ui/components/ui-parts/UIDate.d.ts +1 -0
  230. package/dist/ui/components/ui-parts/UIDescription.d.ts +1 -0
  231. package/dist/ui/components/ui-parts/UIDetail.d.ts +1 -0
  232. package/dist/ui/components/ui-parts/UIExtra.d.ts +1 -0
  233. package/dist/ui/components/ui-parts/UIHeader.d.ts +15 -3
  234. package/dist/ui/components/ui-parts/UIHeader.en.d.ts +5 -2
  235. package/dist/ui/components/ui-parts/UIHeader.en.js +6 -3
  236. package/dist/ui/components/ui-parts/UIHeader.js +45 -5
  237. package/dist/ui/components/ui-parts/UIMeta.d.ts +1 -0
  238. package/dist/ui/components/ui-parts/UIParts.css +18 -0
  239. package/dist/ui/components/ui-parts/UIParts.css.inline.js +1 -1
  240. package/dist/ui/components/ui-parts/UIParts.types.d.ts +15 -1
  241. package/dist/ui/components/ui-parts/UISummary.d.ts +1 -0
  242. package/dist/ui/components/ui-parts/UITitle.d.ts +1 -0
  243. package/dist/ui/components/ui-parts/UIValue.d.ts +1 -0
  244. package/dist/ui/components/ui-placeholder/UIPlaceholder.d.ts +1 -0
  245. package/dist/ui/components/ui-placeholder/UIPlaceholderHeader.d.ts +1 -0
  246. package/dist/ui/components/ui-placeholder/UIPlaceholderImage.d.ts +1 -0
  247. package/dist/ui/components/ui-placeholder/UIPlaceholderLine.d.ts +1 -0
  248. package/dist/ui/components/ui-placeholder/UIPlaceholderParagraph.d.ts +1 -0
  249. package/dist/ui/components/ui-progress/UIProgress.d.ts +2 -0
  250. package/dist/ui/components/ui-quote/UIQuote.d.ts +1 -0
  251. package/dist/ui/components/ui-rail/UIRail.d.ts +1 -0
  252. package/dist/ui/components/ui-rating/UIRating.d.ts +6 -0
  253. package/dist/ui/components/ui-rating/UIRating.fallback.d.ts +6 -0
  254. package/dist/ui/components/ui-reveal/UIReveal.d.ts +1 -0
  255. package/dist/ui/components/ui-search/UISearch.fallback.d.ts +13 -1
  256. package/dist/ui/components/ui-section/UISections.d.ts +1 -0
  257. package/dist/ui/components/ui-segment/UISegment.d.ts +2 -0
  258. package/dist/ui/components/ui-segment/UISegments.d.ts +1 -0
  259. package/dist/ui/components/ui-select/UISelect.d.ts +6 -0
  260. package/dist/ui/components/ui-select/UISelect.fallback.d.ts +6 -0
  261. package/dist/ui/components/ui-shape/UISide.d.ts +4 -0
  262. package/dist/ui/components/ui-sidebar/UIPushable.d.ts +1 -0
  263. package/dist/ui/components/ui-sidebar/UIPusher.d.ts +1 -0
  264. package/dist/ui/components/ui-sidebar/UISidebar.d.ts +1 -0
  265. package/dist/ui/components/ui-sides/UISides.d.ts +6 -0
  266. package/dist/ui/components/ui-sides/UISides.fallback.d.ts +6 -0
  267. package/dist/ui/components/ui-slider/UISlider.d.ts +7 -0
  268. package/dist/ui/components/ui-slider/UISlider.fallback.d.ts +7 -0
  269. package/dist/ui/components/ui-space/UISpace.d.ts +1 -0
  270. package/dist/ui/components/ui-statistic/UIStatistic.d.ts +1 -0
  271. package/dist/ui/components/ui-statistic/UIStatistics.d.ts +1 -0
  272. package/dist/ui/components/ui-step/UIStep.d.ts +1 -0
  273. package/dist/ui/components/ui-step/UISteps.d.ts +1 -0
  274. package/dist/ui/components/ui-table/UICell.d.ts +1 -0
  275. package/dist/ui/components/ui-terms/UITerm.d.ts +1 -0
  276. package/dist/ui/components/ui-terms/UITerms.d.ts +1 -0
  277. package/dist/ui/components/ui-theme-editor/UIColorChip.d.ts +1 -0
  278. package/dist/ui/components/ui-theme-editor/UIThemeToken.d.ts +1 -0
  279. package/dist/ui/components/ui-toast/UIToast.d.ts +1 -0
  280. package/dist/ui/components/ui-toc/UIToc.d.ts +1 -0
  281. package/dist/ui/components/ui-transition/UITransition.d.ts +1 -0
  282. package/dist/ui/components/ui-video/UIAudio.d.ts +1 -0
  283. package/dist/ui/components/ui-video/UIVideo.d.ts +1 -0
  284. package/dist/ui/components/ui-visibility/UIVisibility.d.ts +1 -0
  285. package/dist/ui/components/ui-zoom/UIZoom.d.ts +1 -0
  286. package/dist/ui/jsx.d.ts +4 -4
  287. package/dist/ui/vocabulary/defaults.generated.js +1 -1
  288. package/dist/util/spell/constants.js +1 -1
  289. package/epic/.claude-plugin/plugin.json +1 -1
  290. package/epic/.codex-plugin/plugin.json +1 -1
  291. package/epic/hooks/handoff.mjs +4 -3
  292. package/epic/hooks/worktree.mjs +22 -3
  293. package/epic/package.json +41 -2
  294. package/epic/skills/details/SKILL.md +2 -1
  295. package/epic/skills/epic/SKILL.md +7 -1
  296. package/epic/skills/epic/guide.md +3 -0
  297. package/epic/skills/isolate/SKILL.md +53 -20
  298. package/epic/src/AGENTS.md +11 -2
  299. package/epic/templates/durable.html +1 -1
  300. package/epic/vscode/package.json +1 -1
  301. package/epic/vscode/spell-epic.vsix +0 -0
  302. package/package.json +1 -1
  303. package/parser/package.json +1 -1
  304. package/ui/package.json +15 -2
@@ -1,30 +1,104 @@
1
- var __defProp = Object.defineProperty;
2
- var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
3
-
4
- // src/tools/_assets/spell-syntax.entry.js
5
- import { slug } from "spell/util/string";
6
- import { ServerLink, clockOf } from "../../review/index.js";
7
- import { CHOICES_API, ChoicesForm, DraftSaver, keepOneLine, stopNewLine } from "../../answers/index.js";
8
- import { drawThenBoot, el, sectionNumber, titleInside, withCode } from "./spell-doc-helpers.js";
9
- var COMMENTS_API = "/api/docs/comments";
10
- var AGENTS_TURNS = ["agent", "claude"];
11
- var SAVE_DELAY = 5e3;
12
- var DRAFT_KEY_PREFIX = "spell-syntax-draft:";
13
- var WRITERS = ["js", "ts", "py"];
14
- var WAND_WORDS = "Provide more details here";
15
- var NO_PURPOSE = "(no docstring yet)";
16
- var EXCERPT_LENGTH = 80;
17
- var boxes = /* @__PURE__ */ new Map();
18
- var wands = /* @__PURE__ */ new Map();
19
- var orphans = {};
20
- var bar;
21
- var sent;
22
- var drafts = new DraftSaver({
23
- save: /* @__PURE__ */ __name(async ({ keepalive }) => (await post(CHOICES_API, "draft", { keepalive })).draft.saved, "save"),
1
+ /*
2
+ * Entry of `spell-syntax.js`: the spell syntax guide (`guides/spell-syntax/spell-syntax.html`):
3
+ * draws every rule of the base spell language, one table per module, from the syntax table generated from the code;
4
+ * keeps what Owen types over its boxes;
5
+ * and turns each wand into a comment asking Claude for more details. Then boots the docs bundle.
6
+ * - Loaded INSTEAD of `spell-ui.js`, as `core-reference.js` is: it fetches, draws, then adds `spell-ui.js` (same
7
+ * folder), whatever happened (`drawThenBoot()`).
8
+ * - The data: the JSON `<body data-choices-rows>` names, from the page:
9
+ * `parser/src/spell/spellSyntax.json`, written by `yarn spell:gen:syntax` in spell-parser
10
+ * (spell-parser's `src/spell/node/spellSyntax.ts` has its shape, `SpellSyntaxData`).
11
+ * - Read from the checkout SERVING the page (the page's `ServerLink`, `getFile()`), so each branch shows its own
12
+ * rules.
13
+ * - From `file://` it says so where the tables go (`drawThenBoot()`): the page needs the page server.
14
+ * - Built from elements (`el()`), never from markup in strings.
15
+ * - its buttons Spell UI's `<ui-button>`s (epic `epic-engine` P3): the pencils, the resets, the wands, Expand all
16
+ * and Collapse all; their icons centred by the component, each one's `title` on the button the pointer lands on too
17
+ * (`titleInside()`)
18
+ * - the boxes stay native `<textarea>`s: 750 of them, read and written as plain values; a reset button is made
19
+ * only once its box first differs (`resetButton()`)
20
+ * - a class name's box is ONE line, as every one-line answer box (`keepOneLine()`, `stopNewLine()`)
21
+ * - the feedback a `<ui-textarea grow>`: it grows with its text, to a third of the window
22
+ * - Each module: a nested `<ui-section>` where `[data-syntax-modules]` is,
23
+ * holding a table Rule name | Syntax | Purpose, a row per rule class (its internal classes first).
24
+ * - OPEN, as every section of this page, unlike other docs pages
25
+ * (Owen, 2026-10-12: "Start out with all everything expanded")
26
+ * - EXPAND ALL and COLLAPSE ALL: the page header's, every docs page's (the runtime's `addFoldAll()`; its own pair
27
+ * at the toolbar's right went 2026-10-24).
28
+ * - Rule name:
29
+ * - the class's name, a link to its source (its rule names its tooltip), with a pencil to suggest another name
30
+ * - then each syntax it's registered with, a bullet each
31
+ * - then its aliases, "aka: `expression`"
32
+ * - Syntax: each syntax's example, from its tests, and what each writer makes of it.
33
+ * - BOXES, pre-filled with what the code has:
34
+ * the class's name (behind its pencil), and each example's output from each writer.
35
+ * - Owen types over one to suggest another; a changed box is marked, its round button puts the code's back.
36
+ * - Keyed `<Class>.<field>`: `IsGtLt.name`, `IsGtLt.js`, `IsGtLt.ts`, `IsGtLt.py`;
37
+ * the second example's `AssignmentStatement.js.2`, and so on.
38
+ * - Saved through the syntax-choices routes (`choicesRoutes.ts`), never into the code:
39
+ * - 5s after typing stops, and as the page goes away:
40
+ * `POST /api/docs/choices/draft`, `spell-syntax.draft.json5` beside the page
41
+ * - by a `DraftSaver`, as every form's (epic `coherence` C10): a failed save tried again every 3s, one wording
42
+ * of where it stands; a copy in this browser at once (`DRAFT_KEY_PREFIX`), put back when newer than the
43
+ * server's
44
+ * - Send:
45
+ * `POST /api/docs/choices/answer`, `spell-syntax.answer.json5`, which `epic choices wait <page>` exits with
46
+ * - Kept apart from the generated data, so regenerating it keeps them:
47
+ * - a box whose code now says what Owen typed is no longer a change
48
+ * - one for a rule that's gone is kept as is
49
+ * - The WAND beside each purpose asks Claude for more details there:
50
+ * - it adds a COMMENT (`POST /api/docs/comments`, `commentsRoutes.ts`) on the module's table, quoting the purpose,
51
+ * "Provide more details here: `IsGtLt`."
52
+ * - the runtime draws its thread in that cell; Claude answers on it (`epic comments answer`)
53
+ * - `epic comments wait <page>`, run in the background, wakes a session with it
54
+ * - while its comment waits for Claude, the wand is blue, and a click does nothing more
55
+ * - BUNDLED (epic `coherence` C12): `node src/tools/bundle-spell-ui.js --data-pages` builds it into `spell-syntax.js`,
56
+ * a classic script with NO Spell UI in it; edit THIS, never the bundle. It imports what exists: the docs helpers'
57
+ * `el()`, `titleInside()` and start, `ChoicesForm`'s file links, `ServerLink`, `DraftSaver`, the kit's `slug()`, and
58
+ * `clockOf()`, the review's one time of day.
59
+ */
60
+ import { slug } from "spell/util/string"
61
+ import { ServerLink, clockOf } from "spell/epic/review"
62
+ import { CHOICES_API, ChoicesForm, DraftSaver, keepOneLine, stopNewLine } from "spell/epic/answers"
63
+
64
+ import { drawThenBoot, el, sectionNumber, titleInside, withCode } from "./spell-doc-helpers.js"
65
+
66
+ /** Where comments go (`commentsRoutes.ts`). */
67
+ const COMMENTS_API = "/api/docs/comments"
68
+ /** A comment's `turn` while it waits for an agent: `agent`, or `claude` from a server before epic `epic-friend` P10. */
69
+ const AGENTS_TURNS = ["agent", "claude"]
70
+ /** How long after the last change the draft is saved, in ms. */
71
+ const SAVE_DELAY = 5000
72
+ /** The browser's copy of the page's draft: this, then the page's path. */
73
+ const DRAFT_KEY_PREFIX = "spell-syntax-draft:"
74
+ /** The writers, in the Syntax column's order. */
75
+ const WRITERS = ["js", "ts", "py"]
76
+ /** A wand's words, as its comment starts and as its tooltip. */
77
+ const WAND_WORDS = "Provide more details here"
78
+ /** A purpose the class's docstring doesn't give. */
79
+ const NO_PURPOSE = "(no docstring yet)"
80
+ /** How much of a table's text a comment's excerpt keeps: `BlockAnchors.js` `EXCERPT_LENGTH`. */
81
+ const EXCERPT_LENGTH = 80
82
+
83
+ /** Every box, by key (`IsGtLt.py`): `{ key, input, reset, holder, generated }`. */
84
+ const boxes = new Map()
85
+ /** Every wand, by class name. */
86
+ const wands = new Map()
87
+ /** What Owen typed for rules no longer on the page (renamed, removed): kept, and saved again as is. */
88
+ let orphans = {}
89
+ /** The toolbar's parts, once drawn. */
90
+ let bar
91
+ /** The answer last sent, if any. */
92
+ let sent
93
+ /** The draft's saves (`POST /api/docs/choices/draft`), its browser copy, and where it stands. */
94
+ const drafts = new DraftSaver({
95
+ save: async ({ keepalive }) => (await post(CHOICES_API, "draft", { keepalive })).draft.saved,
24
96
  wait: SAVE_DELAY,
25
97
  key: `${DRAFT_KEY_PREFIX}${location.pathname}`,
26
- onChange: /* @__PURE__ */ __name(() => setSaved(drafts.text, { isError: drafts.isError }), "onChange")
27
- });
98
+ onChange: () => setSaved(drafts.text, { isError: drafts.isError })
99
+ })
100
+
101
+ // drawn, the bundle booted: then what was typed and asked comes back
28
102
  void drawThenBoot({
29
103
  load,
30
104
  draw,
@@ -32,45 +106,57 @@ void drawThenBoot({
32
106
  header: "Rules not drawn",
33
107
  offServer: "This page draws its rules from the checkout serving it, and saves what you type",
34
108
  failure: "Couldn't draw the rules"
35
- }).then((data) => data && restore());
109
+ }).then((data) => data && restore())
110
+
111
+ ////////////////
112
+ // ## Start
113
+ ////////////////
114
+
115
+ /** The syntax table; throws when there's none. */
36
116
  async function load() {
37
- const path = document.body.dataset.choicesRows;
38
- if (!path) throw new Error("the page's `<body>` has no `data-choices-rows`");
39
- const data = await ServerLink.forPage().getFile(path);
40
- if (data === void 0) throw new Error(`${path.split("/").pop()}: not found`);
41
- return data;
117
+ const path = document.body.dataset.choicesRows
118
+ if (!path) throw new Error("the page's `<body>` has no `data-choices-rows`")
119
+ const data = await ServerLink.forPage().getFile(path)
120
+ if (data === undefined) throw new Error(`${path.split("/").pop()}: not found`)
121
+ return data
42
122
  }
43
- __name(load, "load");
123
+
124
+ ////////////////
125
+ // ## Drawing
126
+ ////////////////
127
+
128
+ /** The stats, a section per module where `[data-syntax-modules]` is, then the toolbar at `main`'s end. */
44
129
  function draw(data) {
45
- const modules = data.modules ?? [];
46
- const rows = modules.flatMap((module) => module.rules);
47
- const stats = document.querySelector("[data-syntax-stats]");
130
+ const modules = data.modules ?? []
131
+ const rows = modules.flatMap((module) => module.rules)
132
+ const stats = document.querySelector("[data-syntax-stats]")
48
133
  stats?.replaceChildren(
49
134
  el("ui-statistic", { value: String(modules.length), label: "modules" }),
50
135
  el("ui-statistic", { value: String(rows.filter((rule) => !rule.internal).length), label: "rule classes" }),
51
136
  el("ui-statistic", { value: String(rows.filter((rule) => rule.internal).length), label: "internal" })
52
- );
53
- const holder = document.querySelector("[data-syntax-modules]");
54
- const number = sectionNumber(holder.closest("ui-section"));
55
- holder.replaceWith(...modules.map((module, i) => moduleSection(module, number ? `${number}.${i + 1} ` : "")));
56
- bar = drawBar();
57
- wire();
58
- count();
59
- }
60
- __name(draw, "draw");
137
+ )
138
+ const holder = document.querySelector("[data-syntax-modules]")
139
+ const number = sectionNumber(holder.closest("ui-section"))
140
+ holder.replaceWith(...modules.map((module, i) => moduleSection(module, number ? `${number}.${i + 1} ` : "")))
141
+ bar = drawBar()
142
+ wire()
143
+ count()
144
+ }
145
+
146
+ /** One module: an open `<ui-section>`, its count, its table. */
61
147
  function moduleSection({ module, rules }, prefix) {
62
- const internal = rules.filter((rule) => rule.internal).length;
63
- const registered = rules.length - internal;
148
+ const internal = rules.filter((rule) => rule.internal).length
149
+ const registered = rules.length - internal
64
150
  const badge = [
65
151
  registered ? `${registered} ${registered === 1 ? "rule" : "rules"}` : "",
66
152
  internal ? `${internal} internal` : ""
67
- ].filter(Boolean);
153
+ ].filter(Boolean)
68
154
  const table = el(
69
155
  "table",
70
156
  {},
71
157
  el("thead", {}, el("tr", {}, el("th", {}, "Rule name"), el("th", {}, "Syntax"), el("th", {}, "Purpose"))),
72
158
  el("tbody", {}, ...rules.map(ruleRow))
73
- );
159
+ )
74
160
  return el(
75
161
  "ui-section",
76
162
  {
@@ -86,9 +172,10 @@ function moduleSection({ module, rules }, prefix) {
86
172
  { id: `rules-${slug(module)}`, class: "spell-syntax-table", celled: "", padding: "compact", unstackable: "" },
87
173
  table
88
174
  )
89
- );
175
+ )
90
176
  }
91
- __name(moduleSection, "moduleSection");
177
+
178
+ /** One rule class's row: its name, syntaxes and aliases; each example in each writer; its purpose and wand. */
92
179
  function ruleRow(rule) {
93
180
  return el(
94
181
  "tr",
@@ -96,30 +183,42 @@ function ruleRow(rule) {
96
183
  nameCell(rule),
97
184
  syntaxCell(rule),
98
185
  purposeCell(rule)
99
- );
186
+ )
100
187
  }
101
- __name(ruleRow, "ruleRow");
188
+
189
+ /**
190
+ * Rule name:
191
+ * - the class's name, opening its source, its rule names as its tooltip
192
+ * - its pencil, showing the box to suggest another name
193
+ * - each syntax, a bullet; then its aliases, "aka: `expression`"
194
+ */
102
195
  function nameCell(rule) {
103
- const tip = rule.ruleNames.length ? rule.ruleNames.join(", ") : "no rule name of its own";
104
- const name = el(rule.file ? "a" : "span", { class: "spell-syntax-source", title: tip }, rule.className);
105
- if (rule.file) name.href = ChoicesForm.fileUrlHere(rule.file, rule.line);
196
+ const tip = rule.ruleNames.length ? rule.ruleNames.join(", ") : "no rule name of its own"
197
+ const name = el(rule.file ? "a" : "span", { class: "spell-syntax-source", title: tip }, rule.className)
198
+ if (rule.file) name.href = ChoicesForm.fileUrlHere(rule.file, rule.line)
106
199
  const rename = iconButton(
107
200
  "spell-syntax-rename",
108
201
  "pen to square",
109
202
  `Suggest another name for ${rule.className}`,
110
203
  `Suggest another name for ${rule.className}`
111
- );
112
- const nameBox = box(rule, "name", rule.className, `Class name of ${rule.className}`);
113
- nameBox.hidden = true;
114
- const syntaxes = rule.syntaxes.filter((form) => form.syntax);
115
- const syntaxList = syntaxes.length ? el("ul", { class: "spell-syntax-syntaxes" }, ...syntaxes.map((form) => el("li", {}, el("code", {}, form.syntax)))) : rule.internal ? "" : el("p", { class: "spell-syntax-none" }, "matched by its code: no syntax of its own");
116
- const aka = rule.aliases.length ? el(
117
- "p",
118
- { class: "spell-syntax-aka" },
119
- el("em", {}, "aka"),
120
- ": ",
121
- ...rule.aliases.flatMap((alias, i) => [i ? ", " : "", el("code", {}, alias)])
122
- ) : "";
204
+ )
205
+ const nameBox = box(rule, "name", rule.className, `Class name of ${rule.className}`)
206
+ nameBox.hidden = true
207
+ const syntaxes = rule.syntaxes.filter((form) => form.syntax)
208
+ const syntaxList = syntaxes.length
209
+ ? el("ul", { class: "spell-syntax-syntaxes" }, ...syntaxes.map((form) => el("li", {}, el("code", {}, form.syntax))))
210
+ : rule.internal
211
+ ? ""
212
+ : el("p", { class: "spell-syntax-none" }, "matched by its code: no syntax of its own")
213
+ const aka = rule.aliases.length
214
+ ? el(
215
+ "p",
216
+ { class: "spell-syntax-aka" },
217
+ el("em", {}, "aka"),
218
+ ": ",
219
+ ...rule.aliases.flatMap((alias, i) => [i ? ", " : "", el("code", {}, alias)])
220
+ )
221
+ : ""
123
222
  return el(
124
223
  "td",
125
224
  { class: "spell-syntax-name" },
@@ -127,44 +226,53 @@ function nameCell(rule) {
127
226
  nameBox,
128
227
  syntaxList,
129
228
  aka
130
- );
229
+ )
131
230
  }
132
- __name(nameCell, "nameCell");
231
+
232
+ /** Syntax: each syntax's example, and each writer's output for it; why there's none, where there's none. */
133
233
  function syntaxCell(rule) {
134
- const examples = rule.syntaxes.filter((form) => form.example);
234
+ const examples = rule.syntaxes.filter((form) => form.example)
135
235
  if (!examples.length)
136
236
  return el(
137
237
  "td",
138
238
  { class: "spell-syntax-outputs" },
139
239
  el("em", { class: "spell-syntax-none" }, rule.internal ? "no syntax of its own" : "no test to show it with yet")
140
- );
141
- return el("td", { class: "spell-syntax-outputs" }, ...examples.map((form, i) => example(rule, form, i)));
240
+ )
241
+ return el("td", { class: "spell-syntax-outputs" }, ...examples.map((form, i) => example(rule, form, i)))
142
242
  }
143
- __name(syntaxCell, "syntaxCell");
243
+
244
+ /**
245
+ * One example: the spell, the syntax it matches its tooltip; then each writer's output, in a box.
246
+ * - its boxes keyed `<Class>.js` for the first example, `<Class>.js.2` for the second ...
247
+ */
144
248
  function example(rule, form, i) {
145
- const suffix = i ? `.${i + 1}` : "";
249
+ const suffix = i ? `.${i + 1}` : ""
146
250
  const lines = WRITERS.map((writer) => {
147
- const output = form.outputs[writer];
148
- const value = "code" in output ? box(rule, `${writer}${suffix}`, output.code, `${writer} for ${form.example}`) : el("em", { class: "spell-syntax-none" }, `(${output.error})`);
149
- return el("li", {}, el("b", {}, writer), value);
150
- });
151
- const tip = form.syntax ? `Matches: ${form.syntax}` : "Matched by the rule's own code";
251
+ const output = form.outputs[writer]
252
+ const value =
253
+ "code" in output
254
+ ? box(rule, `${writer}${suffix}`, output.code, `${writer} for ${form.example}`)
255
+ : el("em", { class: "spell-syntax-none" }, `(${output.error})`)
256
+ return el("li", {}, el("b", {}, writer), value)
257
+ })
258
+ const tip = form.syntax ? `Matches: ${form.syntax}` : "Matched by the rule's own code"
152
259
  return el(
153
260
  "ul",
154
261
  { class: "spell-syntax-writers" },
155
262
  el("li", { class: "spell-syntax-input" }, el("b", {}, "e.g."), el("code", { title: tip }, form.example)),
156
263
  ...lines
157
- );
264
+ )
158
265
  }
159
- __name(example, "example");
266
+
267
+ /** Purpose: **internal** first for a class nobody registers, its one sentence, the wand. */
160
268
  function purposeCell(rule) {
161
269
  const text = el(
162
270
  "span",
163
271
  { class: "spell-syntax-purpose-text" },
164
- ...rule.internal ? [el("b", {}, "internal"), " "] : [],
272
+ ...(rule.internal ? [el("b", {}, "internal"), " "] : []),
165
273
  ...withCode(rule.purpose || NO_PURPOSE)
166
- );
167
- const tip = `${WAND_WORDS}: ask Claude, in a comment here`;
274
+ )
275
+ const tip = `${WAND_WORDS}: ask Claude, in a comment here`
168
276
  const wand = el("ui-button", {
169
277
  class: "spell-syntax-wand",
170
278
  appearance: "circular basic",
@@ -172,41 +280,56 @@ function purposeCell(rule) {
172
280
  icon: "wand magic sparkles",
173
281
  title: tip,
174
282
  "aria-label": `${WAND_WORDS}: ${rule.className}`
175
- });
176
- titleInside(wand);
177
- wand.addEventListener("click", () => void askForDetails(rule, wand, text));
178
- wands.set(rule.className, wand);
179
- return el("td", { class: "spell-syntax-purpose" }, el("p", {}, text, " ", wand));
283
+ })
284
+ titleInside(wand)
285
+ wand.addEventListener("click", () => void askForDetails(rule, wand, text))
286
+ wands.set(rule.className, wand)
287
+ return el("td", { class: "spell-syntax-purpose" }, el("p", {}, text, " ", wand))
180
288
  }
181
- __name(purposeCell, "purposeCell");
289
+
290
+ /**
291
+ * A box holding `value`, keyed `<Class>.<field>`; its round reset button comes once it differs (`mark()`).
292
+ * - one line for the class's name (`data-one-line`: `keepOneLine()`); as many as the code has for a writer's output
293
+ */
182
294
  function box(rule, field, value, label) {
183
- const key = `${rule.className}.${field}`;
295
+ const key = `${rule.className}.${field}`
184
296
  const input = el("textarea", {
185
297
  class: "spell-choice-input",
186
298
  rows: "1",
187
299
  spellcheck: "false",
188
300
  autocomplete: "off",
189
301
  "aria-label": label,
190
- ...field === "name" && { "data-one-line": "" }
191
- });
192
- input.value = value;
193
- const holder = el("div", { class: "spell-choice-field spell-syntax-box", "data-box": key }, input);
194
- boxes.set(key, { key, input, reset: void 0, holder, generated: value });
195
- return holder;
196
- }
197
- __name(box, "box");
302
+ ...(field === "name" && { "data-one-line": "" })
303
+ })
304
+ input.value = value
305
+ const holder = el("div", { class: "spell-choice-field spell-syntax-box", "data-box": key }, input)
306
+ boxes.set(key, { key, input, reset: undefined, holder, generated: value })
307
+ return holder
308
+ }
309
+
310
+ /**
311
+ * `one` box's round reset button, after its text: "back to what the code has".
312
+ * - made the first time the box differs, not for every box up front: most are never changed, and each
313
+ * `<ui-button>` draws a shadow root
314
+ */
198
315
  function resetButton(one) {
199
- const { generated } = one;
316
+ const { generated } = one
200
317
  const reset = iconButton(
201
318
  "spell-choice-reset",
202
319
  "clock rotate left",
203
320
  `Back to ${generated.split("\n")[0]}${generated.includes("\n") ? " ..." : ""}`,
204
321
  "Back to what the code has"
205
- );
206
- one.holder.append(reset);
207
- return reset;
322
+ )
323
+ one.holder.append(reset)
324
+ return reset
208
325
  }
209
- __name(resetButton, "resetButton");
326
+
327
+ /**
328
+ * A round, icon-only `<ui-button>` of the page's own, plain (no ring: `syntax-choices.css`, `spell-syntax.css`):
329
+ * `tip` its tooltip, on the inner button too (`titleInside()`); `label` what a screen reader hears.
330
+ * - `tiny`: its icon 11px, near the 13px glyph the raw buttons drew before (`mini`'s is 9px), the button a one-line
331
+ * box's height
332
+ */
210
333
  function iconButton(className, icon, tip, label) {
211
334
  const button = el("ui-button", {
212
335
  class: className,
@@ -215,11 +338,18 @@ function iconButton(className, icon, tip, label) {
215
338
  icon,
216
339
  title: tip,
217
340
  "aria-label": label
218
- });
219
- titleInside(button);
220
- return button;
341
+ })
342
+ titleInside(button)
343
+ return button
221
344
  }
222
- __name(iconButton, "iconButton");
345
+
346
+ /**
347
+ * The toolbar after the last section, pinned to the window's bottom
348
+ * (`syntax-choices.css`, as a syntax-choices page's):
349
+ * - feedback with Send to its right
350
+ * - under them the count and the save status
351
+ * - then an error or "Sent"
352
+ */
223
353
  function drawBar() {
224
354
  const feedback = el("ui-textarea", {
225
355
  class: "spell-choices-feedback",
@@ -227,8 +357,8 @@ function drawBar() {
227
357
  grow: "",
228
358
  placeholder: "Feedback for Claude: anything the boxes don't say",
229
359
  fluid: ""
230
- });
231
- const send2 = el(
360
+ })
361
+ const send = el(
232
362
  "ui-button",
233
363
  {
234
364
  class: "spell-choices-send",
@@ -238,197 +368,265 @@ function drawBar() {
238
368
  title: "Send every changed box, and the feedback, to Claude"
239
369
  },
240
370
  "Send"
241
- );
242
- const saved = el("span", { class: "spell-choices-saved" });
243
- const error = el("ui-message", { class: "spell-choices-error", state: "negative", size: "small", hidden: "" });
244
- const done = el("ui-message", { class: "spell-choices-sent", state: "positive", size: "small", hidden: "" });
245
- document.querySelector("main").append(
246
- el(
247
- "div",
248
- { id: "choices-bar", class: "spell-choices-bar" },
249
- el("div", { class: "spell-choices-row" }, feedback, send2),
250
- el("div", { class: "spell-choices-meta" }, saved),
251
- error,
252
- done
371
+ )
372
+ const saved = el("span", { class: "spell-choices-saved" })
373
+ const error = el("ui-message", { class: "spell-choices-error", state: "negative", size: "small", hidden: "" })
374
+ const done = el("ui-message", { class: "spell-choices-sent", state: "positive", size: "small", hidden: "" })
375
+ document
376
+ .querySelector("main")
377
+ .append(
378
+ el(
379
+ "div",
380
+ { id: "choices-bar", class: "spell-choices-bar" },
381
+ el("div", { class: "spell-choices-row" }, feedback, send),
382
+ el("div", { class: "spell-choices-meta" }, saved),
383
+ error,
384
+ done
385
+ )
253
386
  )
254
- );
255
- return { feedback, send: send2, saved, error, done };
387
+ return { feedback, send, saved, error, done }
256
388
  }
257
- __name(drawBar, "drawBar");
389
+
390
+ ////////////////
391
+ // ## Editing
392
+ ////////////////
393
+
394
+ /** Typing, resets, pencils, source links, feedback, Send, and saving as the page goes away. */
258
395
  function wire() {
259
- const main = document.querySelector("main");
396
+ const main = document.querySelector("main")
260
397
  main.addEventListener("input", (event) => {
261
- const holder = event.target.closest?.(".spell-syntax-box");
262
- if (!holder) return;
263
- if (event.target.hasAttribute("data-one-line")) keepOneLine(event.target);
264
- mark(boxes.get(holder.dataset.box));
265
- changed();
266
- });
398
+ const holder = event.target.closest?.(".spell-syntax-box")
399
+ if (!holder) return
400
+ // the class's name is one line: a pasted line break goes
401
+ if (event.target.hasAttribute("data-one-line")) keepOneLine(event.target)
402
+ mark(boxes.get(holder.dataset.box))
403
+ changed()
404
+ })
267
405
  main.addEventListener("keydown", (event) => {
268
- if (event.target.hasAttribute?.("data-one-line")) stopNewLine(event);
269
- });
406
+ if (event.target.hasAttribute?.("data-one-line")) stopNewLine(event)
407
+ })
270
408
  main.addEventListener("click", (event) => {
271
- const rename = event.target.closest?.(".spell-syntax-rename");
409
+ const rename = event.target.closest?.(".spell-syntax-rename")
272
410
  if (rename) {
273
- showNameBox(boxes.get(`${rename.closest("tr").dataset.rule}.name`), "toggle");
274
- return;
411
+ showNameBox(boxes.get(`${rename.closest("tr").dataset.rule}.name`), "toggle")
412
+ return
275
413
  }
276
- const reset = event.target.closest?.(".spell-choice-reset");
277
- const holder = reset?.closest(".spell-syntax-box");
414
+ const reset = event.target.closest?.(".spell-choice-reset")
415
+ const holder = reset?.closest(".spell-syntax-box")
278
416
  if (holder) {
279
- const one = boxes.get(holder.dataset.box);
280
- one.input.value = one.generated;
281
- mark(one);
282
- changed();
283
- one.input.focus();
284
- return;
417
+ const one = boxes.get(holder.dataset.box)
418
+ one.input.value = one.generated
419
+ mark(one)
420
+ changed()
421
+ one.input.focus()
422
+ return
285
423
  }
286
- const link = event.target.closest?.("a.spell-syntax-source");
287
- if (link) ChoicesForm.openFile(event, link.href);
288
- });
289
- bar.feedback.addEventListener("ui-typed", changed);
290
- bar.send.addEventListener("click", () => void send());
291
- drafts.watch(window);
292
- }
293
- __name(wire, "wire");
424
+ const link = event.target.closest?.("a.spell-syntax-source")
425
+ if (link) ChoicesForm.openFile(event, link.href)
426
+ })
427
+ bar.feedback.addEventListener("ui-typed", changed)
428
+ bar.send.addEventListener("click", () => void send())
429
+ // as the page goes away (or hides): saved at once
430
+ drafts.watch(window)
431
+ }
432
+
433
+ /**
434
+ * Mark `one` box changed (it differs from what the code has) or not: the box, its reset button, its row.
435
+ * - a changed name's box stays in view
436
+ */
294
437
  function mark(one) {
295
- const isChanged = isBoxChanged(one);
296
- one.holder.toggleAttribute("data-changed", isChanged);
297
- if (isChanged) one.reset ??= resetButton(one);
298
- if (one.reset) one.reset.hidden = !isChanged;
299
- if (isChanged && one.key.endsWith(".name")) showNameBox(one, "show");
300
- const row = one.holder.closest("tr");
301
- row.toggleAttribute("data-edited", !!row.querySelector(".spell-syntax-box[data-changed]"));
302
- }
303
- __name(mark, "mark");
438
+ const isChanged = isBoxChanged(one)
439
+ one.holder.toggleAttribute("data-changed", isChanged)
440
+ if (isChanged) one.reset ??= resetButton(one)
441
+ if (one.reset) one.reset.hidden = !isChanged
442
+ if (isChanged && one.key.endsWith(".name")) showNameBox(one, "show")
443
+ const row = one.holder.closest("tr")
444
+ row.toggleAttribute("data-edited", !!row.querySelector(".spell-syntax-box[data-changed]"))
445
+ }
446
+
447
+ /**
448
+ * Show the class name's box, `one`, under the name (and focus it), or hide it:
449
+ * its pencil's click (`toggle`), or a changed name (`show`).
450
+ * - a changed name's box never hides: the pencil focuses it instead
451
+ */
304
452
  function showNameBox(one, how) {
305
- const isShown = how === "show" || one.holder.hidden || isBoxChanged(one);
306
- one.holder.hidden = !isShown;
307
- one.holder.closest("td").querySelector(".spell-syntax-rename").toggleAttribute("data-open", isShown);
308
- if (isShown && how === "toggle") one.input.focus();
453
+ const isShown = how === "show" || one.holder.hidden || isBoxChanged(one)
454
+ one.holder.hidden = !isShown
455
+ one.holder.closest("td").querySelector(".spell-syntax-rename").toggleAttribute("data-open", isShown)
456
+ if (isShown && how === "toggle") one.input.focus()
309
457
  }
310
- __name(showNameBox, "showNameBox");
458
+
459
+ /** Does `one` box differ from what the code has? */
311
460
  function isBoxChanged(one) {
312
- return one.input.value.trim() !== one.generated.trim();
461
+ return one.input.value.trim() !== one.generated.trim()
313
462
  }
314
- __name(isBoxChanged, "isBoxChanged");
463
+
464
+ /** Something changed: recount, kept in this browser at once, and saved once typing stops. */
315
465
  function changed() {
316
- count();
317
- drafts.keep({ values: collect(), feedback: feedbackNow(), saved: (/* @__PURE__ */ new Date()).toISOString() });
318
- drafts.changed();
319
- if (sent) showSent(sent, { isStale: true });
466
+ count()
467
+ drafts.keep({ values: collect(), feedback: feedbackNow(), saved: new Date().toISOString() })
468
+ drafts.changed()
469
+ if (sent) showSent(sent, { isStale: true })
320
470
  }
321
- __name(changed, "changed");
471
+
472
+ /**
473
+ * The count, on Send's tooltip: no line of its own under the bar
474
+ * (Owen, 2026-10-13: "Lose the `0 boxes saved` bit").
475
+ */
322
476
  function count() {
323
- const changes = [...boxes.values()].filter(isBoxChanged).length;
324
- const kept = Object.keys(orphans).length;
325
- const rules = new Set([...boxes.values()].filter(isBoxChanged).map((one) => one.key.split(".")[0])).size;
326
- bar.send.title = `Send ${changes} changed ${changes === 1 ? "box" : "boxes"}, in ${rules} ${rules === 1 ? "rule" : "rules"}` + (kept ? ` (and ${kept} kept for rules no longer here)` : "") + `, and the feedback, to Claude`;
477
+ const changes = [...boxes.values()].filter(isBoxChanged).length
478
+ const kept = Object.keys(orphans).length
479
+ const rules = new Set([...boxes.values()].filter(isBoxChanged).map((one) => one.key.split(".")[0])).size
480
+ bar.send.title =
481
+ `Send ${changes} changed ${changes === 1 ? "box" : "boxes"}, in ${rules} ${rules === 1 ? "rule" : "rules"}` +
482
+ (kept ? ` (and ${kept} kept for rules no longer here)` : "") +
483
+ `, and the feedback, to Claude`
327
484
  }
328
- __name(count, "count");
485
+
486
+ /** The boxes that differ from the code, as typed, by key; and what was typed for rules no longer here. */
329
487
  function collect() {
330
- const values = { ...orphans };
331
- for (const one of boxes.values()) if (isBoxChanged(one)) values[one.key] = one.input.value;
332
- return values;
488
+ const values = { ...orphans }
489
+ for (const one of boxes.values()) if (isBoxChanged(one)) values[one.key] = one.input.value
490
+ return values
333
491
  }
334
- __name(collect, "collect");
492
+
493
+ ////////////////
494
+ // ## Saving and sending
495
+ ////////////////
496
+
497
+ /** Send: every changed box and the feedback; show what was sent, or why not. */
335
498
  async function send() {
336
- bar.error.hidden = true;
337
- bar.send.setAttribute("loading", "");
499
+ bar.error.hidden = true
500
+ bar.send.setAttribute("loading", "")
338
501
  try {
339
- const { answer } = await post(CHOICES_API, "answer");
340
- drafts.done();
341
- drafts.tell(`saved ${clockOf(answer.answered)}`);
342
- showSent(answer);
502
+ const { answer } = await post(CHOICES_API, "answer")
503
+ // sent: the draft is done with, its browser copy too
504
+ drafts.done()
505
+ drafts.tell(`saved ${clockOf(answer.answered)}`)
506
+ showSent(answer)
343
507
  } catch (error) {
344
- showError(`Not sent: ${error.message}`);
508
+ showError(`Not sent: ${error.message}`)
345
509
  } finally {
346
- bar.send.removeAttribute("loading");
510
+ bar.send.removeAttribute("loading")
347
511
  }
348
512
  }
349
- __name(send, "send");
513
+
514
+ /**
515
+ * POST the page's boxes to `/api/docs/choices/<what>`; the route's answer.
516
+ * - throws an `Error` saying, in Owen's words, what to do: reload, restart the server, open it from the server
517
+ */
350
518
  async function post(api, what, { keepalive = false } = {}) {
351
519
  return postJSON(
352
520
  `${api}/${what}`,
353
521
  { page: location.pathname, values: collect(), feedback: feedbackNow() },
354
522
  { keepalive }
355
- );
523
+ )
356
524
  }
357
- __name(post, "post");
525
+
526
+ /** The feedback box's text, trimmed. */
358
527
  function feedbackNow() {
359
- return String(bar.feedback.value ?? "").trim();
528
+ return String(bar.feedback.value ?? "").trim()
360
529
  }
361
- __name(feedbackNow, "feedbackNow");
530
+
531
+ /**
532
+ * POST `body` to `url` through the page's `ServerLink`: its token, refreshed once after a restart; the answer, or
533
+ * throws saying why.
534
+ */
362
535
  async function postJSON(url, body, { keepalive = false } = {}) {
363
536
  if (!ServerLink.isServed())
364
- throw new Error("this page isn't on the page server: open it with `epic pages open <page>`");
365
- return ServerLink.forPage().post(url, body, { keepalive });
537
+ throw new Error("this page isn't on the page server: open it with `epic pages open <page>`")
538
+ return ServerLink.forPage().post(url, body, { keepalive })
366
539
  }
367
- __name(postJSON, "postJSON");
540
+
541
+ /** What was typed and sent before, into the boxes; then which wands are waiting for Claude. */
368
542
  async function restore() {
369
- if (!ServerLink.isServed()) return;
543
+ if (!ServerLink.isServed()) return
370
544
  try {
371
- const [draft, answer] = await Promise.all([fetchJSON(`${CHOICES_API}/draft`), fetchJSON(`${CHOICES_API}/answer`)]);
372
- const local = drafts.kept();
373
- const isLocalNewer = local?.saved && local.saved > (draft?.draft?.saved ?? answer?.answer?.answered ?? "");
374
- const last = isLocalNewer ? local : draft?.draft ?? answer?.answer;
545
+ const [draft, answer] = await Promise.all([fetchJSON(`${CHOICES_API}/draft`), fetchJSON(`${CHOICES_API}/answer`)])
546
+ // this browser's copy, newer than the server's draft: typed while the server couldn't take it
547
+ const local = drafts.kept()
548
+ const isLocalNewer = local?.saved && local.saved > (draft?.draft?.saved ?? answer?.answer?.answered ?? "")
549
+ const last = isLocalNewer ? local : (draft?.draft ?? answer?.answer)
375
550
  if (last) {
376
- orphans = {};
551
+ orphans = {}
377
552
  for (const [key, value] of Object.entries(last.values ?? {})) {
378
- const one = boxes.get(key);
553
+ const one = boxes.get(key)
379
554
  if (!one) {
380
- orphans[key] = value;
381
- continue;
555
+ orphans[key] = value
556
+ continue
382
557
  }
383
- one.input.value = value;
384
- mark(one);
558
+ one.input.value = value
559
+ mark(one)
385
560
  }
386
- await customElements.whenDefined("ui-textarea");
387
- bar.feedback.value = last.feedback ?? "";
388
- count();
561
+ // a property set before the element upgrades would shadow its own
562
+ await customElements.whenDefined("ui-textarea")
563
+ bar.feedback.value = last.feedback ?? ""
564
+ count()
389
565
  }
390
- if (draft?.draft) drafts.tell(`saved ${clockOf(draft.draft.saved)}`);
391
- if (answer?.answer) showSent(answer.answer);
392
- if (isLocalNewer) drafts.changed();
566
+ if (draft?.draft) drafts.tell(`saved ${clockOf(draft.draft.saved)}`)
567
+ if (answer?.answer) showSent(answer.answer)
568
+ // not on the server yet: saved now
569
+ if (isLocalNewer) drafts.changed()
393
570
  } catch (error) {
394
- drafts.tell(`can't load what you typed: ${error.message}`, { isError: true });
571
+ drafts.tell(`can't load what you typed: ${error.message}`, { isError: true })
395
572
  }
396
- await markWands();
573
+ await markWands()
397
574
  }
398
- __name(restore, "restore");
575
+
576
+ /** `GET url?page=<this page>`, as JSON; `undefined` when the route says no. */
399
577
  async function fetchJSON(url) {
400
- const reply = await ServerLink.forPage().get(url, { query: { page: location.pathname }, missing: null }).catch(() => void 0);
401
- if (reply === null) throw new Error("page server too old, restart it");
402
- return reply;
578
+ const reply = await ServerLink.forPage()
579
+ .get(url, { query: { page: location.pathname }, missing: null })
580
+ .catch(() => undefined)
581
+ if (reply === null) throw new Error("page server too old, restart it")
582
+ return reply
403
583
  }
404
- __name(fetchJSON, "fetchJSON");
584
+
585
+ /** The toolbar's quiet save status; `isError`: in red. */
405
586
  function setSaved(message, { isError = false } = {}) {
406
- bar.saved.textContent = message;
407
- bar.saved.classList.toggle("spell-choices-failed", isError);
587
+ bar.saved.textContent = message
588
+ bar.saved.classList.toggle("spell-choices-failed", isError)
408
589
  }
409
- __name(setSaved, "setSaved");
590
+
591
+ /** `message` in the toolbar's error box. */
410
592
  function showError(message) {
411
- bar.error.replaceChildren(el("p", {}, message));
412
- bar.error.hidden = false;
593
+ bar.error.replaceChildren(el("p", {}, message))
594
+ bar.error.hidden = false
413
595
  }
414
- __name(showError, "showError");
596
+
597
+ /**
598
+ * The "Sent" message for `answer`; `isStale`: changed since, so it says to press Send again.
599
+ * - SIDE EFFECT: remembers `answer` as the one sent
600
+ */
415
601
  function showSent(answer, { isStale = false } = {}) {
416
- sent = answer;
417
- const changes = Object.keys(answer.values ?? {}).length;
418
- const again = answer.changes ? ` (sent ${answer.changes + 1} times)` : "";
419
- const words = isStale ? `Sent at ${clockOf(answer.answered)}${again}; changed since: press Send again to send the new ones.` : `Sent to Claude at ${clockOf(answer.answered)}${again}: ${changes} ${changes === 1 ? "box" : "boxes"}. Change anything and press Send again to resend.`;
420
- bar.done.setAttribute("state", isStale ? "warning" : "positive");
421
- bar.done.replaceChildren(el("p", {}, words));
422
- bar.done.hidden = false;
423
- }
424
- __name(showSent, "showSent");
602
+ sent = answer
603
+ const changes = Object.keys(answer.values ?? {}).length
604
+ const again = answer.changes ? ` (sent ${answer.changes + 1} times)` : ""
605
+ const words = isStale
606
+ ? `Sent at ${clockOf(answer.answered)}${again}; changed since: press Send again to send the new ones.`
607
+ : `Sent to Claude at ${clockOf(answer.answered)}${again}: ${changes} ${changes === 1 ? "box" : "boxes"}. Change anything and press Send again to resend.`
608
+ bar.done.setAttribute("state", isStale ? "warning" : "positive")
609
+ bar.done.replaceChildren(el("p", {}, words))
610
+ bar.done.hidden = false
611
+ }
612
+
613
+ ////////////////
614
+ // ## The wand: a comment asking for more details
615
+ ////////////////
616
+
617
+ /**
618
+ * Ask Claude for more details on `rule`'s purpose:
619
+ * a comment on its module's table, quoting `text` (the purpose), so its thread shows in that cell.
620
+ * - once per wait: while its comment waits for Claude, a click does nothing more
621
+ * - NEVER throws: a failure shows in the toolbar
622
+ */
425
623
  async function askForDetails(rule, wand, text) {
426
- if (wand.hasAttribute("data-asked")) return;
427
- bar.error.hidden = true;
428
- wand.setAttribute("loading", "");
624
+ if (wand.hasAttribute("data-asked")) return
625
+ bar.error.hidden = true
626
+ wand.setAttribute("loading", "")
429
627
  try {
430
- const table = wand.closest("ui-table");
431
- const section = table.closest("ui-section");
628
+ const table = wand.closest("ui-table")
629
+ const section = table.closest("ui-section")
432
630
  await postJSON(COMMENTS_API, {
433
631
  page: location.pathname,
434
632
  action: "add",
@@ -439,66 +637,88 @@ async function askForDetails(rule, wand, text) {
439
637
  quote: squash(textOf(text)),
440
638
  offset: offsetOf(table, text),
441
639
  text: `${WAND_WORDS}: \`${rule.className}\`.`
442
- });
443
- showAsked(rule.className, true);
640
+ })
641
+ showAsked(rule.className, true)
444
642
  } catch (error) {
445
- showError(`Not asked: ${error.message}`);
643
+ showError(`Not asked: ${error.message}`)
446
644
  } finally {
447
- wand.removeAttribute("loading");
645
+ wand.removeAttribute("loading")
448
646
  }
449
647
  }
450
- __name(askForDetails, "askForDetails");
648
+
649
+ /**
650
+ * Mark the wands whose comment is waiting for an agent: this page's comments, as the server has them.
651
+ * - an agent's turn is `agent`; `claude` from a page server started before epic `epic-friend` P10
652
+ */
451
653
  async function markWands() {
452
654
  try {
453
- const answer = await fetchJSON(COMMENTS_API);
454
- const asked = /* @__PURE__ */ new Set();
655
+ const answer = await fetchJSON(COMMENTS_API)
656
+ const asked = new Set()
455
657
  for (const comment of answer?.comments ?? []) {
456
- const className = new RegExp(`^${WAND_WORDS}: \`([^\`]+)\``).exec(comment.text ?? "")?.[1];
457
- if (className && AGENTS_TURNS.includes(comment.turn)) asked.add(className);
658
+ const className = new RegExp(`^${WAND_WORDS}: \`([^\`]+)\``).exec(comment.text ?? "")?.[1]
659
+ if (className && AGENTS_TURNS.includes(comment.turn)) asked.add(className)
458
660
  }
459
- for (const className of wands.keys()) showAsked(className, asked.has(className));
661
+ for (const className of wands.keys()) showAsked(className, asked.has(className))
460
662
  } catch {
663
+ // the comments routes aren't there: the wands just stay as they are
461
664
  }
462
665
  }
463
- __name(markWands, "markWands");
666
+
667
+ /** Show `className`'s wand as asked (blue: Claude has it to do) or not. */
464
668
  function showAsked(className, isAsked) {
465
- const wand = wands.get(className);
466
- if (!wand) return;
467
- wand.toggleAttribute("data-asked", isAsked);
468
- if (isAsked) wand.setAttribute("color", "primary");
469
- else wand.removeAttribute("color");
470
- wand.setAttribute("appearance", isAsked ? "circular" : "circular basic");
471
- wand.title = isAsked ? "Asked Claude for more details: the thread is below" : `${WAND_WORDS}: ask Claude, in a comment here`;
472
- titleInside(wand);
473
- }
474
- __name(showAsked, "showAsked");
669
+ const wand = wands.get(className)
670
+ if (!wand) return
671
+ wand.toggleAttribute("data-asked", isAsked)
672
+ if (isAsked) wand.setAttribute("color", "primary")
673
+ else wand.removeAttribute("color")
674
+ wand.setAttribute("appearance", isAsked ? "circular" : "circular basic")
675
+ wand.title = isAsked
676
+ ? "Asked Claude for more details: the thread is below"
677
+ : `${WAND_WORDS}: ask Claude, in a comment here`
678
+ titleInside(wand)
679
+ }
680
+
681
+ /**
682
+ * `block`'s text as a comment reads it (`BlockAnchors.js` `textOf()`):
683
+ * its text nodes, a space after each element's, the runtime's own additions left out.
684
+ */
475
685
  function textOf(block) {
476
- return runsOf(block).map((run) => run.text).join("");
686
+ return runsOf(block)
687
+ .map((run) => run.text)
688
+ .join("")
477
689
  }
478
- __name(textOf, "textOf");
690
+
691
+ /** Where `node` starts in `block`'s squashed text, in characters (`BlockAnchors.js` `offsetIn()`). */
479
692
  function offsetOf(block, node) {
480
- let before = "";
693
+ let before = ""
481
694
  for (const run of runsOf(block)) {
482
- if (run.node === node) return squash(`${before}x`).length - 1;
483
- before += run.text;
695
+ if (run.node === node) return squash(`${before}x`).length - 1
696
+ before += run.text
484
697
  }
485
- return 0;
698
+ return 0
486
699
  }
487
- __name(offsetOf, "offsetOf");
700
+
701
+ /** `block`'s text runs, in order: `{ node, text }`; `node` is set on each element's first run. */
488
702
  function runsOf(block) {
489
- const runs = [];
490
- const walk = /* @__PURE__ */ __name((node) => {
491
- if (node.nodeType === 3) return runs.push({ node: null, text: node.textContent });
492
- if (node.nodeType !== 1 || node !== block && node.matches("[data-spell-added]")) return;
493
- runs.push({ node, text: "" });
494
- for (const child of node.childNodes) walk(child);
495
- runs.push({ node: null, text: " " });
496
- }, "walk");
497
- walk(block);
498
- return runs;
499
- }
500
- __name(runsOf, "runsOf");
703
+ const runs = []
704
+ const walk = (node) => {
705
+ if (node.nodeType === 3) return runs.push({ node: null, text: node.textContent })
706
+ if (node.nodeType !== 1 || (node !== block && node.matches("[data-spell-added]"))) return
707
+ runs.push({ node, text: "" })
708
+ for (const child of node.childNodes) walk(child)
709
+ runs.push({ node: null, text: " " })
710
+ }
711
+ walk(block)
712
+ return runs
713
+ }
714
+
715
+ ////////////////
716
+ // ## Helpers
717
+ ////////////////
718
+
719
+ /** `text` with runs of white space as one space, trimmed. */
501
720
  function squash(text) {
502
- return String(text ?? "").replace(/\s+/g, " ").trim();
721
+ return String(text ?? "")
722
+ .replace(/\s+/g, " ")
723
+ .trim()
503
724
  }
504
- __name(squash, "squash");