nodality 1.4.2 → 1.5.0

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 (306) hide show
  1. package/README.md +34 -5
  2. package/bin/dev-server.mjs +200 -0
  3. package/bin/install-skill.mjs +77 -20
  4. package/bin/mcp-server.mjs +98 -0
  5. package/bin/nodality.mjs +29 -4
  6. package/dist/animator.cjs.js +1 -1
  7. package/dist/animator.cjs.js.LICENSE.txt +1 -1
  8. package/dist/animator.esm.js +1 -1
  9. package/dist/animator.esm.js.LICENSE.txt +1 -1
  10. package/dist/audionew.cjs.js +1 -1
  11. package/dist/audionew.cjs.js.LICENSE.txt +1 -1
  12. package/dist/audionew.esm.js +1 -1
  13. package/dist/audionew.esm.js.LICENSE.txt +1 -1
  14. package/dist/base.cjs.js +1 -1
  15. package/dist/base.cjs.js.LICENSE.txt +1 -1
  16. package/dist/base.esm.js +1 -1
  17. package/dist/base.esm.js.LICENSE.txt +1 -1
  18. package/dist/beta-desktop-bar.cjs.js +1 -1
  19. package/dist/beta-desktop-bar.cjs.js.LICENSE.txt +1 -1
  20. package/dist/beta-desktop-bar.esm.js +1 -1
  21. package/dist/beta-desktop-bar.esm.js.LICENSE.txt +1 -1
  22. package/dist/beta-mobile-bar.cjs.js +1 -1
  23. package/dist/beta-mobile-bar.cjs.js.LICENSE.txt +1 -1
  24. package/dist/beta-mobile-bar.esm.js +1 -1
  25. package/dist/beta-mobile-bar.esm.js.LICENSE.txt +1 -1
  26. package/dist/bundle.umd.js +1 -1
  27. package/dist/bundle.umd.js.LICENSE.txt +28 -62
  28. package/dist/button.cjs.js +1 -1
  29. package/dist/button.cjs.js.LICENSE.txt +1 -1
  30. package/dist/button.esm.js +1 -1
  31. package/dist/button.esm.js.LICENSE.txt +1 -1
  32. package/dist/card-getter.cjs.js.LICENSE.txt +1 -1
  33. package/dist/card-getter.esm.js.LICENSE.txt +1 -1
  34. package/dist/center.cjs.js +1 -1
  35. package/dist/center.cjs.js.LICENSE.txt +1 -1
  36. package/dist/center.esm.js +1 -1
  37. package/dist/center.esm.js.LICENSE.txt +1 -1
  38. package/dist/checkbox.cjs.js +1 -1
  39. package/dist/checkbox.cjs.js.LICENSE.txt +1 -1
  40. package/dist/checkbox.esm.js +1 -1
  41. package/dist/checkbox.esm.js.LICENSE.txt +1 -1
  42. package/dist/code.cjs.js +1 -1
  43. package/dist/code.cjs.js.LICENSE.txt +1 -1
  44. package/dist/code.esm.js +1 -1
  45. package/dist/code.esm.js.LICENSE.txt +1 -1
  46. package/dist/container.cjs.js +1 -1
  47. package/dist/container.cjs.js.LICENSE.txt +1 -1
  48. package/dist/container.esm.js +1 -1
  49. package/dist/container.esm.js.LICENSE.txt +1 -1
  50. package/dist/data-list.cjs.js.LICENSE.txt +1 -1
  51. package/dist/data-list.esm.js.LICENSE.txt +1 -1
  52. package/dist/designer.cjs.js +1 -1
  53. package/dist/designer.cjs.js.LICENSE.txt +28 -26
  54. package/dist/designer.esm.js +1 -1
  55. package/dist/designer.esm.js.LICENSE.txt +28 -26
  56. package/dist/element-mapper.cjs.js +1 -1
  57. package/dist/element-mapper.cjs.js.LICENSE.txt +1 -1
  58. package/dist/element-mapper.esm.js +1 -1
  59. package/dist/element-mapper.esm.js.LICENSE.txt +1 -1
  60. package/dist/finalresult.esm.js +1 -2
  61. package/dist/finalresult.esm.js.LICENSE.txt +28 -26
  62. package/dist/flex-card.cjs.js +1 -1
  63. package/dist/flex-card.cjs.js.LICENSE.txt +1 -1
  64. package/dist/flex-card.esm.js +1 -1
  65. package/dist/flex-card.esm.js.LICENSE.txt +1 -1
  66. package/dist/flex-grid.cjs.js +1 -1
  67. package/dist/flex-grid.cjs.js.LICENSE.txt +1 -1
  68. package/dist/flex-grid.esm.js +1 -1
  69. package/dist/flex-grid.esm.js.LICENSE.txt +1 -1
  70. package/dist/flex-row.cjs.js +1 -1
  71. package/dist/flex-row.cjs.js.LICENSE.txt +1 -1
  72. package/dist/flex-row.esm.js +1 -1
  73. package/dist/flex-row.esm.js.LICENSE.txt +1 -1
  74. package/dist/floating-input.cjs.js +1 -1
  75. package/dist/floating-input.cjs.js.LICENSE.txt +1 -1
  76. package/dist/floating-input.esm.js +1 -1
  77. package/dist/floating-input.esm.js.LICENSE.txt +1 -1
  78. package/dist/free.cjs.js +1 -1
  79. package/dist/free.cjs.js.LICENSE.txt +1 -1
  80. package/dist/free.esm.js +1 -1
  81. package/dist/free.esm.js.LICENSE.txt +1 -1
  82. package/dist/horizontal-scroller.cjs.js.LICENSE.txt +1 -1
  83. package/dist/horizontal-scroller.esm.js.LICENSE.txt +1 -1
  84. package/dist/image-picker.cjs.js +1 -1
  85. package/dist/image-picker.cjs.js.LICENSE.txt +1 -1
  86. package/dist/image-picker.esm.js +1 -1
  87. package/dist/image-picker.esm.js.LICENSE.txt +1 -1
  88. package/dist/image.cjs.js +1 -1
  89. package/dist/image.cjs.js.LICENSE.txt +1 -1
  90. package/dist/image.esm.js +1 -1
  91. package/dist/image.esm.js.LICENSE.txt +1 -1
  92. package/dist/index.cjs.js +1 -1
  93. package/dist/index.cjs.js.LICENSE.txt +28 -26
  94. package/dist/index.d.ts +3 -2
  95. package/dist/index.esm.js +1 -2
  96. package/dist/index.esm.js.LICENSE.txt +28 -26
  97. package/dist/keyframe-animation.cjs.js.LICENSE.txt +1 -1
  98. package/dist/keyframe-animation.esm.js.LICENSE.txt +1 -1
  99. package/dist/link-getter.cjs.js +1 -1
  100. package/dist/link-getter.cjs.js.LICENSE.txt +1 -1
  101. package/dist/link-getter.esm.js +1 -1
  102. package/dist/link-getter.esm.js.LICENSE.txt +1 -1
  103. package/dist/link.cjs.js +1 -1
  104. package/dist/link.cjs.js.LICENSE.txt +1 -1
  105. package/dist/link.esm.js +1 -1
  106. package/dist/link.esm.js.LICENSE.txt +1 -1
  107. package/dist/meta-adder.cjs.js +1 -1
  108. package/dist/meta-adder.cjs.js.LICENSE.txt +1 -1
  109. package/dist/meta-adder.esm.js +1 -1
  110. package/dist/meta-adder.esm.js.LICENSE.txt +1 -1
  111. package/dist/modal-2025.cjs.js +1 -1
  112. package/dist/modal-2025.cjs.js.LICENSE.txt +1 -1
  113. package/dist/modal-2025.esm.js +1 -1
  114. package/dist/modal-2025.esm.js.LICENSE.txt +1 -1
  115. package/dist/multiswitcher.cjs.js +1 -1
  116. package/dist/multiswitcher.cjs.js.LICENSE.txt +1 -1
  117. package/dist/multiswitcher.esm.js +1 -1
  118. package/dist/multiswitcher.esm.js.LICENSE.txt +1 -1
  119. package/dist/new-nav-bar.cjs.js +1 -1
  120. package/dist/new-nav-bar.cjs.js.LICENSE.txt +1 -1
  121. package/dist/new-nav-bar.esm.js +1 -1
  122. package/dist/new-nav-bar.esm.js.LICENSE.txt +1 -1
  123. package/dist/picker.cjs.js +1 -1
  124. package/dist/picker.cjs.js.LICENSE.txt +1 -1
  125. package/dist/picker.esm.js +1 -1
  126. package/dist/picker.esm.js.LICENSE.txt +1 -1
  127. package/dist/progress.cjs.js +1 -1
  128. package/dist/progress.cjs.js.LICENSE.txt +1 -1
  129. package/dist/progress.esm.js +1 -1
  130. package/dist/progress.esm.js.LICENSE.txt +1 -1
  131. package/dist/radio.cjs.js.LICENSE.txt +1 -1
  132. package/dist/radio.esm.js.LICENSE.txt +1 -1
  133. package/dist/range.cjs.js.LICENSE.txt +1 -1
  134. package/dist/range.esm.js.LICENSE.txt +1 -1
  135. package/dist/scroll-video.cjs.js.LICENSE.txt +1 -1
  136. package/dist/scroll-video.esm.js.LICENSE.txt +1 -1
  137. package/dist/side-bar.cjs.js +1 -1
  138. package/dist/side-bar.cjs.js.LICENSE.txt +1 -1
  139. package/dist/side-bar.esm.js +1 -1
  140. package/dist/side-bar.esm.js.LICENSE.txt +1 -1
  141. package/dist/side-nav-bar.cjs.js +1 -1
  142. package/dist/side-nav-bar.cjs.js.LICENSE.txt +1 -1
  143. package/dist/side-nav-bar.esm.js +1 -1
  144. package/dist/side-nav-bar.esm.js.LICENSE.txt +1 -1
  145. package/dist/simple-bar.cjs.js +1 -1
  146. package/dist/simple-bar.cjs.js.LICENSE.txt +1 -1
  147. package/dist/simple-bar.esm.js +1 -1
  148. package/dist/simple-bar.esm.js.LICENSE.txt +1 -1
  149. package/dist/slider-2025.cjs.js +1 -1
  150. package/dist/slider-2025.cjs.js.LICENSE.txt +1 -1
  151. package/dist/slider-2025.esm.js +1 -1
  152. package/dist/slider-2025.esm.js.LICENSE.txt +1 -1
  153. package/dist/spacer.cjs.js +1 -1
  154. package/dist/spacer.cjs.js.LICENSE.txt +1 -1
  155. package/dist/spacer.esm.js +1 -1
  156. package/dist/spacer.esm.js.LICENSE.txt +1 -1
  157. package/dist/stack.cjs.js +1 -1
  158. package/dist/stack.cjs.js.LICENSE.txt +1 -1
  159. package/dist/stack.esm.js +1 -1
  160. package/dist/stack.esm.js.LICENSE.txt +1 -1
  161. package/dist/stacker.cjs.js.LICENSE.txt +1 -1
  162. package/dist/stacker.esm.js.LICENSE.txt +1 -1
  163. package/dist/table.cjs.js +1 -1
  164. package/dist/table.cjs.js.LICENSE.txt +1 -1
  165. package/dist/table.esm.js +1 -1
  166. package/dist/table.esm.js.LICENSE.txt +1 -1
  167. package/dist/text-field.cjs.js +1 -1
  168. package/dist/text-field.cjs.js.LICENSE.txt +1 -1
  169. package/dist/text-field.esm.js +1 -1
  170. package/dist/text-field.esm.js.LICENSE.txt +1 -1
  171. package/dist/text.cjs.js +1 -1
  172. package/dist/text.cjs.js.LICENSE.txt +1 -1
  173. package/dist/text.esm.js +1 -1
  174. package/dist/text.esm.js.LICENSE.txt +1 -1
  175. package/dist/theme.cjs.js.LICENSE.txt +1 -1
  176. package/dist/theme.esm.js.LICENSE.txt +1 -1
  177. package/dist/transform-anim.cjs.js.LICENSE.txt +1 -1
  178. package/dist/transform-anim.esm.js.LICENSE.txt +1 -1
  179. package/dist/ulist.cjs.js +1 -1
  180. package/dist/ulist.cjs.js.LICENSE.txt +1 -1
  181. package/dist/ulist.esm.js +1 -1
  182. package/dist/ulist.esm.js.LICENSE.txt +1 -1
  183. package/dist/video.cjs.js +1 -1
  184. package/dist/video.cjs.js.LICENSE.txt +1 -1
  185. package/dist/video.esm.js +1 -1
  186. package/dist/video.esm.js.LICENSE.txt +1 -1
  187. package/dist/wrap.cjs.js +1 -1
  188. package/dist/wrap.cjs.js.LICENSE.txt +1 -1
  189. package/dist/wrap.esm.js +1 -1
  190. package/dist/wrap.esm.js.LICENSE.txt +1 -1
  191. package/dist/zoom-card.cjs.js +1 -1
  192. package/dist/zoom-card.cjs.js.LICENSE.txt +1 -1
  193. package/dist/zoom-card.esm.js +1 -1
  194. package/dist/zoom-card.esm.js.LICENSE.txt +1 -1
  195. package/layout/animator.js +49 -6
  196. package/layout/audio.js +1 -1
  197. package/layout/audionew.js +1 -1
  198. package/layout/base.js +1 -1
  199. package/layout/beta-desktop-bar.js +1 -1
  200. package/layout/beta-mobile-bar.js +1 -1
  201. package/layout/button.js +3 -3
  202. package/layout/center.js +1 -1
  203. package/layout/checkbox.js +1 -1
  204. package/layout/circle.js +1 -1
  205. package/layout/code.js +1 -1
  206. package/layout/container.js +4 -4
  207. package/layout/dropdown-2025.js +6 -5
  208. package/layout/flex-card.js +1 -1
  209. package/layout/flex-grid.js +3 -3
  210. package/layout/flex-row.js +3 -3
  211. package/layout/form-components/custom.js +1 -1
  212. package/layout/form-components/data-list.js +1 -1
  213. package/layout/form-components/floating-input.js +11 -2
  214. package/layout/form-components/form-all.js +1 -1
  215. package/layout/form-components/form.js +1 -1
  216. package/layout/form-components/image-picker.js +2 -2
  217. package/layout/form-components/picker.js +2 -2
  218. package/layout/form-components/radio.js +1 -1
  219. package/layout/form-components/radiogroup.js +1 -1
  220. package/layout/form-components/range.js +1 -1
  221. package/layout/free.js +1 -1
  222. package/layout/grid-overlay.js +1 -1
  223. package/layout/grid-switcher.js +3 -3
  224. package/layout/grid.js +2 -2
  225. package/layout/horizontal-scroller.js +1 -1
  226. package/layout/image.js +6 -3
  227. package/layout/index.js +1 -1
  228. package/layout/link.js +3 -3
  229. package/layout/list.js +1 -1
  230. package/layout/meta-adder.js +1 -1
  231. package/layout/modal-2025.js +1 -1
  232. package/layout/morph.js +1 -1
  233. package/layout/multiswitcher.js +12 -7
  234. package/layout/nav-bar.js +2 -2
  235. package/layout/nav-factor/custom-div.js +1 -1
  236. package/layout/new-nav-bar.js +2 -2
  237. package/layout/polygon.js +1 -1
  238. package/layout/prerender-site.js +1 -1
  239. package/layout/prerender.js +1 -1
  240. package/layout/progress.js +2 -2
  241. package/layout/row.js +3 -3
  242. package/layout/scroll-video.js +1 -1
  243. package/layout/shop.js +1 -1
  244. package/layout/side-bar.js +1 -1
  245. package/layout/side-nav-bar.js +1 -1
  246. package/layout/simple-bar.js +1 -1
  247. package/layout/slider-2025.js +1 -1
  248. package/layout/spacer.js +1 -1
  249. package/layout/stack.js +1 -1
  250. package/layout/svg.js +1 -1
  251. package/layout/switcher.js +2 -2
  252. package/layout/table.js +1 -1
  253. package/layout/text-field.js +2 -2
  254. package/layout/text.js +8 -8
  255. package/layout/ulist.js +1 -1
  256. package/layout/video.js +1 -1
  257. package/layout/wrap.js +1 -1
  258. package/layout/zoom-card.js +1 -1
  259. package/lib/agent-surface.js +1 -1
  260. package/lib/card-getter.js +1 -1
  261. package/lib/check-page.js +6 -2
  262. package/lib/codegen.js +1 -1
  263. package/lib/data.js +1 -1
  264. package/lib/designer.js +114 -8
  265. package/lib/dev-inspector.js +295 -0
  266. package/lib/dev-state.js +257 -0
  267. package/lib/element-mapper.js +186 -13
  268. package/lib/element-params.generated.js +4 -4
  269. package/lib/grid-geometry.js +1 -1
  270. package/lib/keyframe-animation.js +1 -1
  271. package/lib/known-inert.js +1 -1
  272. package/lib/link-getter.js +1 -1
  273. package/lib/morph-node.js +1 -1
  274. package/lib/normalize-spec.js +1 -1
  275. package/lib/parse-html.js +1 -1
  276. package/lib/raster-inspect.js +1 -1
  277. package/lib/raster-ops.js +9 -1
  278. package/lib/raster-presets.js +1 -1
  279. package/lib/react.js +1 -1
  280. package/lib/resolve-refs.js +1 -1
  281. package/lib/responsive.js +1 -1
  282. package/lib/scroll-video.js +1 -1
  283. package/lib/seo.js +1 -1
  284. package/lib/stacker.js +1 -1
  285. package/lib/suggest.js +1 -1
  286. package/lib/theme.js +1 -1
  287. package/lib/transform-anim.js +1 -1
  288. package/lib/transition.js +1 -1
  289. package/lib/validate-nodes.js +1 -1
  290. package/lib/view-transition.js +1 -1
  291. package/lib/webmcp-adapter.js +1 -1
  292. package/package.json +1 -1
  293. package/schema.json +1735 -4207
  294. package/scripts/generate-schema.mjs +9 -2
  295. package/skills/nodality/SKILL.md +22 -238
  296. package/skills/nodality/references/content-and-composites.md +66 -0
  297. package/skills/nodality/references/editing.md +38 -0
  298. package/skills/nodality/references/imperative.md +27 -0
  299. package/skills/nodality/references/multi-page.md +40 -0
  300. package/skills/nodality/references/node-families.md +58 -0
  301. package/skills/nodality/references/prerender.md +13 -0
  302. package/skills/nodality/references/verifying.md +27 -0
  303. package/skills/nodality-apply-comments/SKILL.md +52 -0
  304. package/skills/nodality-current/SKILL.md +69 -0
  305. package/skills/nodality-edit-page/SKILL.md +42 -0
  306. package/skills/nodality-new-page/SKILL.md +55 -0
@@ -0,0 +1,257 @@
1
+ /*!
2
+ * nodality v1.5.0
3
+ * (c) 2026 Filip Vabrousek
4
+ * License: MIT
5
+ */
6
+
7
+ /*!
8
+ * dev-state.js — what the person is looking at, and what they asked for.
9
+ *
10
+ * `nodality dev` writes two files in the project's `.nodality/` folder (the
11
+ * project root, never the upload folder, so neither is ever deployed):
12
+ *
13
+ * current.json the page, viewport and element the person last picked
14
+ * in the inspector — a live cursor, overwritten on every
15
+ * pick, read by an agent at the start of every turn that
16
+ * says "this".
17
+ * comments.json notes left on rendered elements, addressed by element
18
+ * id. A comment is resolved, never deleted, so what was
19
+ * asked and what was done stay side by side.
20
+ *
21
+ * An element id is the address because it is the one handle that survives
22
+ * edits: `target` already names elements by it, and a note pinned to
23
+ * `#hero` still means `#hero` after anything else on the page changes.
24
+ *
25
+ * Node only (fs). Imported by the dev server, `check` and the MCP tools —
26
+ * never by the browser bundle.
27
+ */
28
+
29
+ import fs from "node:fs";
30
+ import path from "node:path";
31
+ import crypto from "node:crypto";
32
+ import { suggest } from "./suggest.js";
33
+
34
+ export const STATE_DIR = ".nodality";
35
+ export const MAX_NOTE = 2000;
36
+ export const MAX_TEXT = 120;
37
+
38
+ export const stateDir = (root = process.cwd()) => path.join(root, STATE_DIR);
39
+ const file = (root, name) => path.join(stateDir(root), name);
40
+
41
+ function readJson(p, fallback) {
42
+ try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return fallback; }
43
+ }
44
+
45
+ // Write to a temp file and rename: a reader never sees half a file, and two
46
+ // quick picks cannot interleave into invalid JSON.
47
+ function writeJson(p, value) {
48
+ fs.mkdirSync(path.dirname(p), { recursive: true });
49
+ const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
50
+ fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n");
51
+ fs.renameSync(tmp, p);
52
+ }
53
+
54
+ // A source pointer as the dev snippet writes it: pages/index.js:60:5.
55
+ const SRC_RE = /^[\w./-]{1,300}:\d{1,7}:\d{1,5}$/;
56
+ const src = (v) => (typeof v === "string" && SRC_RE.test(v) && !v.includes("..") ? v : null);
57
+
58
+ /**
59
+ * The line a source pointer names, read from the upload folder (never taken
60
+ * from the browser): { file, line, col, code }, or null when the file or line
61
+ * is not there. `code` is what a comment is anchored to: when lines move, the
62
+ * code is how `check` finds the note's place again.
63
+ */
64
+ export function codeAt(uploadDir, pointer) {
65
+ const s = src(pointer);
66
+ if (!s || !uploadDir) return null;
67
+ const [, file, line, col] = /^(.*):(\d+):(\d+)$/.exec(s);
68
+ const base = path.resolve(uploadDir);
69
+ const abs = path.resolve(base, file);
70
+ if (!abs.startsWith(base + path.sep)) return null;
71
+ let text;
72
+ try { text = fs.readFileSync(abs, "utf8"); } catch { return null; }
73
+ const lines = text.split("\n");
74
+ const n = Number(line);
75
+ if (n < 1 || n > lines.length) return null;
76
+ return { file, line: n, col: Number(col), code: lines[n - 1].trim().slice(0, 200) };
77
+ }
78
+
79
+ const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : undefined);
80
+ const ids = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.length <= 200).slice(0, 50) : []);
81
+ const int = (v) => (Number.isFinite(v) ? Math.round(v) : undefined);
82
+
83
+ /** A page path as the dev server serves it: relative, forward slashes, no leading slash. */
84
+ export function normalizePage(p) {
85
+ if (typeof p !== "string") return "index.html";
86
+ let s = p.split("?")[0].split("#")[0].replace(/\\/g, "/").replace(/^\/+/, "");
87
+ if (s === "" || s.endsWith("/")) s += "index.html";
88
+ return s;
89
+ }
90
+
91
+ // ── current.json ──────────────────────────────────────────────────
92
+
93
+ /**
94
+ * Keep only the fields an agent reads, each bounded. The body comes from the
95
+ * browser, so nothing in it is trusted to be the shape it claims.
96
+ */
97
+ export function sanitizeCurrent(body = {}, { uploadDir } = {}) {
98
+ const vp = body.viewport || {};
99
+ const sel = body.selection;
100
+ return {
101
+ page: normalizePage(body.page),
102
+ viewport: { width: int(vp.width) ?? null, height: int(vp.height) ?? null },
103
+ selection: sel && typeof sel === "object" ? {
104
+ ids: ids(sel.ids),
105
+ source: codeAt(uploadDir, sel.src),
106
+ type: str(sel.type, 40) ?? null,
107
+ tag: str(sel.tag, 20) ?? null,
108
+ text: str(sel.text, MAX_TEXT) ?? "",
109
+ nodesTargeting: Array.isArray(sel.nodesTargeting) ? sel.nodesTargeting.filter(Number.isInteger).slice(0, 100) : [],
110
+ activeRanges: Array.isArray(sel.activeRanges)
111
+ ? sel.activeRanges.filter((r) => r && Number.isInteger(r.node) && Array.isArray(r.range))
112
+ .slice(0, 50).map((r) => ({ node: r.node, range: r.range.slice(0, 2).map(int) }))
113
+ : [],
114
+ } : null,
115
+ updatedAt: new Date().toISOString(),
116
+ };
117
+ }
118
+
119
+ export const readCurrent = (root) => readJson(file(root, "current.json"), null);
120
+
121
+ export function writeCurrent(root, body, opts = {}) {
122
+ const value = sanitizeCurrent(body, opts);
123
+ writeJson(file(root, "current.json"), value);
124
+ return value;
125
+ }
126
+
127
+ // ── comments.json ─────────────────────────────────────────────────
128
+
129
+ export const readComments = (root) => {
130
+ const list = readJson(file(root, "comments.json"), []);
131
+ return Array.isArray(list) ? list : [];
132
+ };
133
+
134
+ /** Add one note. Returns the stored comment, or an error report. */
135
+ export function addComment(root, body = {}, { uploadDir } = {}) {
136
+ const note = str(body.note, MAX_NOTE)?.trim();
137
+ const target = ids(body.target);
138
+ const source = codeAt(uploadDir, body.src);
139
+ if (!note) return { ok: false, error: { code: "MISSING_FIELD", path: "note" } };
140
+ // An element is addressed by its id, or — on a page written with the
141
+ // imperative layer, where it has none — by the line that created it.
142
+ if (!target.length && !source) return { ok: false, error: { code: "MISSING_FIELD", path: "target" } };
143
+ const r = body.rect;
144
+ const comment = {
145
+ id: `c-${crypto.randomBytes(4).toString("hex")}`,
146
+ page: normalizePage(body.page),
147
+ target,
148
+ source,
149
+ rect: r && [r.x, r.y, r.w, r.h].every(Number.isFinite)
150
+ ? { x: int(r.x), y: int(r.y), w: int(r.w), h: int(r.h) } : null,
151
+ viewport: body.viewport && Number.isFinite(body.viewport.width)
152
+ ? { width: int(body.viewport.width), height: int(body.viewport.height) ?? null } : null,
153
+ note,
154
+ ts: new Date().toISOString(),
155
+ status: "open",
156
+ };
157
+ const list = readComments(root);
158
+ list.push(comment);
159
+ writeJson(file(root, "comments.json"), list);
160
+ return { ok: true, comment };
161
+ }
162
+
163
+ /** Mark one comment resolved, with what was done. Never deletes. */
164
+ export function resolveComment(root, id, summary) {
165
+ const list = readComments(root);
166
+ const c = list.find((x) => x.id === id);
167
+ if (!c) {
168
+ return { ok: false, error: { code: "UNKNOWN_COMMENT", path: "id", got: id,
169
+ suggestions: suggest(String(id), list.map((x) => x.id)) } };
170
+ }
171
+ const s = str(summary, MAX_NOTE)?.trim();
172
+ if (!s) return { ok: false, error: { code: "MISSING_FIELD", path: "summary" } };
173
+ c.status = "resolved";
174
+ c.resolution = s;
175
+ c.resolvedAt = new Date().toISOString();
176
+ writeJson(file(root, "comments.json"), list);
177
+ return { ok: true, comment: c };
178
+ }
179
+
180
+ /**
181
+ * The page path a file is served at: relative to the upload folder, the same
182
+ * key the dev server writes. Comparing by suffix instead would let a note on
183
+ * `index.html` match `en/index.html` too.
184
+ */
185
+ export function pageOfFile(filePath, uploadDir) {
186
+ const rel = path.relative(path.resolve(uploadDir), path.resolve(filePath));
187
+ return normalizePage(rel.startsWith("..") ? path.basename(filePath) : rel);
188
+ }
189
+
190
+ /**
191
+ * What `check` reports about the comments on one page, given the element ids
192
+ * that page actually rendered:
193
+ * STALE_COMMENT_TARGET (error) a target id is gone — the note now
194
+ * points at nothing, and applying it would
195
+ * mean guessing. The likeliest new id rides
196
+ * along as the suggestion.
197
+ * UNRESOLVED_COMMENT (warning) the note is still open.
198
+ */
199
+ export function commentFindings(comments, { page, ids: present = [], uploadDir } = {}) {
200
+ const key = normalizePage(page);
201
+ const have = new Set(present);
202
+ const errors = [];
203
+ const warnings = [];
204
+ for (const c of comments) {
205
+ if (c.status !== "open" || normalizePage(c.page) !== key) continue;
206
+ if (!c.target.length && c.source) {
207
+ const r = sourceFinding(c, uploadDir);
208
+ (r.level === "error" ? errors : warnings).push(r.finding);
209
+ continue;
210
+ }
211
+ const gone = c.target.filter((t) => !have.has(t));
212
+ if (gone.length) {
213
+ errors.push({ code: "STALE_COMMENT_TARGET", path: c.id, got: gone.join(", "),
214
+ detail: `comment ${untrusted("note", c.note)} targets ${gone.map((g) => "#" + g).join(", ")}, which this page no longer renders`,
215
+ suggestions: gone.flatMap((g) => suggest(g, [...have])).slice(0, 3) });
216
+ } else {
217
+ warnings.push({ code: "UNRESOLVED_COMMENT", path: c.id, got: c.target.join(", "),
218
+ detail: `open comment on ${c.target.map((g) => "#" + g).join(", ")}: ${untrusted("note", c.note)}`, suggestions: [] });
219
+ }
220
+ }
221
+ return { errors, warnings };
222
+ }
223
+
224
+ /**
225
+ * A note anchored to code, not an id. Its line is checked against the code
226
+ * it was written at: unchanged → still open; found on another line → moved
227
+ * (a warning naming the new line, so the agent edits the right place);
228
+ * found nowhere → stale, because applying it would mean guessing.
229
+ */
230
+ function sourceFinding(c, uploadDir) {
231
+ const { file, line, code } = c.source;
232
+ const now = codeAt(uploadDir, `${file}:${line}:1`);
233
+ if (now && now.code === code) {
234
+ return { level: "warning", finding: { code: "UNRESOLVED_COMMENT", path: c.id, got: `${file}:${line}`,
235
+ detail: `open comment on ${file}:${line} (${code}): ${untrusted("note", c.note)}`, suggestions: [] } };
236
+ }
237
+ let lines = [];
238
+ try { lines = fs.readFileSync(path.resolve(uploadDir || ".", file), "utf8").split("\n"); } catch {}
239
+ const at = lines.findIndex((l) => l.trim().slice(0, 200) === code);
240
+ if (at >= 0) {
241
+ return { level: "warning", finding: { code: "COMMENT_SOURCE_MOVED", path: c.id, got: `${file}:${line}`,
242
+ detail: `the code this comment was written on moved: ${untrusted("note", c.note)}`, suggestions: [`${file}:${at + 1}`] } };
243
+ }
244
+ return { level: "error", finding: { code: "STALE_COMMENT_SOURCE", path: c.id, got: `${file}:${line}`,
245
+ detail: `comment ${untrusted("note", c.note)} was written on code that is no longer in ${file}: ${code}`, suggestions: [] } };
246
+ }
247
+
248
+ // ── handing it to an agent ────────────────────────────────────────
249
+
250
+ /**
251
+ * Text a person typed or a page contains, wrapped so it reads as data. `<`
252
+ * is escaped so the text cannot close its own tag and continue as if it
253
+ * were part of the surrounding instructions.
254
+ */
255
+ export function untrusted(tag, text) {
256
+ return `<${tag}>${String(text ?? "").replace(/</g, "&lt;")}</${tag}>`;
257
+ }
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * nodality v1.4.2
2
+ * nodality v1.5.0
3
3
  * (c) 2026 Filip Vabrousek
4
4
  * License: MIT
5
5
  */
@@ -214,7 +214,13 @@ class ElementMapper { // 22:09:58 04/11/2024
214
214
  if (built.obj && typeof built.obj === "object") built.obj.id = declared;
215
215
  }
216
216
  const node = built && (built.res || built.formElement || built.el || built.container);
217
- if (node && typeof node.setAttribute === "function") {
217
+ // A component may already carry the declared id, on its own node or
218
+ // an inner one (FilePickera puts it on its <input>); writing it onto
219
+ // the wrapper too gave the page two elements with one id.
220
+ const carries = (n) => n && typeof n.getAttribute === "function" && (n.getAttribute("id") === declared
221
+ || (typeof n.querySelectorAll === "function" && [...n.querySelectorAll("[id]")].some((k) => k.getAttribute("id") === declared)));
222
+ const carried = built && [built.res, built.formElement, built.el, built.container].some(carries);
223
+ if (node && !carried && typeof node.setAttribute === "function") {
218
224
  const current = node.getAttribute("id");
219
225
  // Written exactly as declared, hash and all. Ids are compared in
220
226
  // normalised form everywhere (see sameId), and the DOM keeps the
@@ -347,6 +353,8 @@ class ElementMapper { // 22:09:58 04/11/2024
347
353
  return new Table()
348
354
  .add(rows)
349
355
  .set({
356
+ // Declared id at set() time, for chainReact (see mapCircle).
357
+ ...(obj.el.id != null && obj.el.id !== "" ? { id: String(obj.el.id) } : {}),
350
358
  cellPadding: "0.3em",
351
359
  cellAlign: "center",
352
360
  style: {
@@ -450,6 +458,8 @@ new Text("row.").set({
450
458
 
451
459
  return new Code()
452
460
  .set({
461
+ // Declared id at set() time, for chainReact (see mapCircle).
462
+ ...(el.id != null && el.id !== "" ? { id: String(el.id) } : {}),
453
463
  stroke: this.filtero("blast", el.id, obj.customOptions),
454
464
  gradient: this.filtero("gradient", el.id, obj.customOptions),
455
465
  animation: this.filtero("animation", el.id, obj.customOptions),
@@ -539,7 +549,7 @@ animation: {
539
549
 
540
550
  // The id below was hardcoded to "#first", so every copy element on a page
541
551
  // emitted the same id and none could be targeted individually.
542
- return `new Wrapper()
552
+ const src = `new Wrapper()
543
553
  .set({
544
554
  width: "${minSize}px",
545
555
  height: "${minSize}px",
@@ -606,6 +616,41 @@ animation: {
606
616
 
607
617
  })
608
618
  )`;
619
+
620
+ // The instance Des mounts: the same wrapper and texts the source builds,
621
+ // computed here. (The source above has a double comma when a raster chain
622
+ // is present, so that case never rendered; this one does.)
623
+ const wrap = new Wrapper().set({
624
+ width: minSize + "px", height: minSize + "px", display: "flex", justifyContent: "center",
625
+ alignItems: "center", position: "absolute", id: obj.el.id ? String(obj.el.id) : "#first", scale: 0.3,
626
+ ...(ft?.animation ? { animation: {
627
+ op: {
628
+ name: "animation", color: "green", width: "1px", fireAt: "inview",
629
+ keyframesOpen: [{ transform: "rotate(360deg)", opacity: 0 }, { transform: "rotate(0deg)", opacity: 1 }],
630
+ keyframesClose: [{ transform: "rotate(0deg)", opacity: 1 }, { transform: "rotate(0deg)", opacity: 0 }],
631
+ openOptions: { duration: 300, fill: "forwards", delay: 1000 },
632
+ closeOptions: { duration: 1, fill: "forwards", delay: 1000 },
633
+ },
634
+ target: ["#first"],
635
+ } } : {}),
636
+ ...(copyRaster.length ? { raster: JSON.parse(JSON.stringify(copyRaster)) } : {}),
637
+ });
638
+ const texts = Array.from({ length: count }).map((_, i) => {
639
+ const cx = minSize / 2, cy = minSize / 2, R = minSize / 2;
640
+ const angle = (i / count) * Math.PI * 2 - Math.PI / 2;
641
+ const dist = R + minSize / 2;
642
+ const x = cx + dist * Math.cos(angle);
643
+ const y = cy + dist * Math.sin(angle);
644
+ let rot = angle * 180 / Math.PI + 90;
645
+ rot = (rot % 360 + 360) % 360;
646
+ rot = (rot % 360 + 360) % 360;
647
+ return new Text("Hello").set({
648
+ size: "S1", color: "green", font: "Arial", left: x + "px", top: y + "px",
649
+ transform: { op: { name: "transform", transform: { static: true, keep: true, values: ["tx:-50%", "ty:-50%", "rotate(" + rot + "deg)"] } } },
650
+ });
651
+ });
652
+ wrap.add(texts);
653
+ return this.withSource(wrap, src);
609
654
  }
610
655
 
611
656
 
@@ -1747,9 +1792,9 @@ if (obj.el.dropdown){
1747
1792
  // unchanged, and the dropdown slot after it still indexes the
1748
1793
  // entry the pushes above appended.
1749
1794
  ...(obj.el.animation ? animatedLinks : links).slice(0, items.length).filter(Boolean),
1750
- (obj.el.animation && obj.el.dropdown)
1751
- ? animatedLinks[items.length]
1752
- : new Text("").set({}).excludeFromCode(),
1795
+ // Only when there is a dropdown slot. This was an empty Text kept out
1796
+ // of the generated code, so a mounted instance rendered an empty <p>.
1797
+ ...((obj.el.animation && obj.el.dropdown) ? [animatedLinks[items.length]] : []),
1753
1798
 
1754
1799
  new Text("Company, 2025")
1755
1800
  .set({ // no ID, no animation
@@ -1859,7 +1904,7 @@ if (obj.el.dropdown){
1859
1904
 
1860
1905
  // probably dont use obj.el.els here, bit can access
1861
1906
  let ela = new Free()
1862
- .set({id: "#3", templateCols: templateCols, height: "600px", })
1907
+ .set({id: obj.el.id != null && obj.el.id !== "" ? String(obj.el.id) : "#3", templateCols: templateCols, height: "600px", })
1863
1908
  .add([
1864
1909
  new Text("I am free")
1865
1910
  .set({
@@ -1899,6 +1944,9 @@ if (obj.el.dropdown){
1899
1944
 
1900
1945
  return new Circle()
1901
1946
  .set({
1947
+ // The declared id, at set() time: chainReact matches nodes against it, so
1948
+ // without it a gradient or shadow targeting this circle applied nothing.
1949
+ ...(el.id != null && el.id !== "" ? { id: String(el.id) } : {}),
1902
1950
  diameter: 108,
1903
1951
  background: "#1abc9c",
1904
1952
  stroke: this.filtero("blast", el.id, obj.customOptions),
@@ -1930,6 +1978,8 @@ return new Circle()
1930
1978
  // same id and none could be targeted individually.
1931
1979
  let elo = new Polygon({ id: el.id ? String(el.id) : "hex" })
1932
1980
  .set({
1981
+ // Declared id at set() time, for chainReact (see mapCircle).
1982
+ ...(el.id != null && el.id !== "" ? { id: String(el.id) } : {}),
1933
1983
  sides: count,
1934
1984
  size: 300,
1935
1985
  background: "#1abc9c",
@@ -2255,7 +2305,8 @@ const blast = this.filtero("blast", el.id, obj.customOptions);
2255
2305
  "gradient", "animation", "shadow", "marginOp", "filtera", "blast", "raster",
2256
2306
  ])).map(([k, v]) => `,\n ${JSON.stringify(k)}: ${JSON.stringify(v)}`).join("");
2257
2307
 
2258
- return ` new FlexGrid()
2308
+ const grid = this.gridItemsBuild(obj, cardTemplate);
2309
+ const src = ` new FlexGrid()
2259
2310
  .set({
2260
2311
  colat: "700px",
2261
2312
  wrap: true,
@@ -2284,9 +2335,122 @@ const blast = this.filtero("blast", el.id, obj.customOptions);
2284
2335
  }
2285
2336
  })
2286
2337
  .items(
2287
- ${this.gridItemsSource(obj, cardTemplate)}
2338
+ ${grid.src}
2288
2339
  )
2289
2340
  `;
2341
+
2342
+ // The instance Des mounts, built from the same data as the source above
2343
+ // and in the same order the source would run: grid, its set(), then the
2344
+ // cards. Values are JSON round-tripped exactly as the source carried them,
2345
+ // so no instance shares an object with the caller's nodes.
2346
+ const J = (v) => JSON.parse(JSON.stringify(v));
2347
+ const authoredObj = J(this.elOpts(obj.el, [
2348
+ "backgroundCard", "gradient", "animation", "shadow", "marginOp", "filtera", "blast", "raster",
2349
+ ]));
2350
+ const inst = new FlexGrid().set({
2351
+ colat: "700px", wrap: true, align: "center", gap: "1rem",
2352
+ ...authoredObj,
2353
+ ...this.gridOps({ gradient, animation, shadow, marginOp, filtera, blast }),
2354
+ ...(gridRaster !== undefined ? { raster: J(gridRaster) } : {}),
2355
+ });
2356
+ inst.items(grid.cards());
2357
+ return this.withSource(inst, src);
2358
+ }
2359
+
2360
+ /** The node ops a cards grid passes on, as the generated source writes them. */
2361
+ static gridOps(ops) {
2362
+ const out = {};
2363
+ for (const k of ["gradient", "animation", "shadow", "marginOp", "filtera", "blast"]) {
2364
+ if (ops[k] !== undefined) out[k] = JSON.parse(JSON.stringify(ops[k]));
2365
+ }
2366
+ return out;
2367
+ }
2368
+
2369
+ /**
2370
+ * An instance whose code is the source this mapper always emitted, so the
2371
+ * code panel and `nodality compile` print exactly what they printed when
2372
+ * Des ran that source to build the page.
2373
+ */
2374
+ static withSource(inst, src) {
2375
+ inst.toCode = () => [src];
2376
+ return inst;
2377
+ }
2378
+
2379
+ /**
2380
+ * The `.items(...)` of a cards grid, as source and as instances.
2381
+ * `cards()` builds the instances when called, so the caller decides the
2382
+ * order (after the grid's own set(), as the source runs). Nested element
2383
+ * specs are mapped ONCE: their instance goes into the card, their toCode()
2384
+ * into the source.
2385
+ */
2386
+ static gridItemsBuild(obj, cardTemplate) {
2387
+ const items = obj.el.items;
2388
+ const isZoom = !!obj.el.backgroundCard;
2389
+ const el = obj.el;
2390
+ const ops = {
2391
+ gradient: this.filtero("gradient", el.id, obj.customOptions),
2392
+ animation: this.filtero("animation", el.id, obj.customOptions),
2393
+ shadow: this.filtero("shadow", el.id, obj.customOptions),
2394
+ marginOp: this.filtero("margin", el.id, obj.customOptions),
2395
+ filtera: this.filtero("filter", el.id, obj.customOptions),
2396
+ blast: this.filtero("blast", el.id, obj.customOptions),
2397
+ };
2398
+ const cardBox = { width: "300px", height: "700px", radius: "0.7rem", mar: { sides: ["all"], value: "0.8rem" } };
2399
+ const linkStyle = { background: "#1d6fe0", pad: [{ lr: "0.5rem", tb: "1rem" }], radius: "0.4rem", color: "white" };
2400
+ // The template card, as cardTemplate writes it.
2401
+ const templateCard = (item, withAlt) => isZoom
2402
+ ? new ZoomCard().set({ url: item.img, font: "Arial", mar: { sides: ["all"], value: "0.8rem" }, inpad: "1rem", useBrightness: true })
2403
+ .items([
2404
+ new Text(item.title).set({ fluidc: "S6", tag: "h2", color: "#c2410c" }),
2405
+ new Link("Link").set({ text: item.title, url: item.link, ...linkStyle }),
2406
+ ])
2407
+ : new Card().set({ ...cardBox, ...this.gridOps(ops) })
2408
+ .items([
2409
+ new Image(item.img).set(withAlt ? { isFull: true, url: item.img, alt: item.alt } : { isFull: true, url: item.img }),
2410
+ new Text(item.title).set({ size: "S5", tag: "h2", color: "#c2410c" }),
2411
+ new Link("Link").set({ text: item.title, url: item.link, ...linkStyle, mar: [{ "a": 21 }] }),
2412
+ ]);
2413
+
2414
+ if (!Array.isArray(items) || items.length === 0) {
2415
+ const placeholders = [
2416
+ { img: "https://upload.wikimedia.org/wikipedia/commons/3/3a/Starship_S20.jpg", title: "Starship", link: "#ship" },
2417
+ { img: "https://upload.wikimedia.org/wikipedia/commons/1/16/Apollo_11_Launch_-_GPN-2000-000630.jpg", title: "Saturn V", link: "#saturn" },
2418
+ { img: "https://upload.wikimedia.org/wikipedia/commons/d/d6/STS120LaunchHiRes-edit1.jpg", title: "Shuttle", link: "#shuttle" },
2419
+ ];
2420
+ return { src: this.gridItemsSource(obj, cardTemplate), cards: () => placeholders.map((it) => templateCard(it, false)) };
2421
+ }
2422
+
2423
+ const isSpecList = (it) => Array.isArray(it);
2424
+ const shorthand = items.filter((it) => !isSpecList(it));
2425
+ if (!items.some(isSpecList)) {
2426
+ const withAlt = shorthand.some((it) => it && it.alt !== undefined);
2427
+ const data = JSON.parse(JSON.stringify(shorthand));
2428
+ return { src: this.gridItemsSource(obj, cardTemplate), cards: () => data.map((it) => templateCard(it, withAlt)) };
2429
+ }
2430
+
2431
+ // Mixed: each card explicit. Spec lists are mapped here, once.
2432
+ const mapped = items.map((it) => isSpecList(it) ? it.map((child) => this.mapType({ ...obj, el: child })) : null);
2433
+ const codeOf = (m) => (typeof m === "string" ? m : [].concat(m && m.toCode ? m.toCode() : []).join("")).trim();
2434
+ const srcCards = items.map((it, i) => isSpecList(it)
2435
+ ? `new Card()
2436
+ .set({ width: "300px", height: "700px", radius: "0.7rem", mar: { sides: ["all"], value: "0.8rem" } })
2437
+ .items([
2438
+ ${mapped[i].map(codeOf).filter(Boolean).join(",\n ")}
2439
+ ])`
2440
+ : this.cardFromShorthand(it));
2441
+ const v = (x) => JSON.parse(JSON.stringify(x ?? ""));
2442
+ return {
2443
+ src: `[
2444
+ ${srcCards.join(",\n ")}
2445
+ ]`,
2446
+ cards: () => items.map((it, i) => isSpecList(it)
2447
+ ? new Card().set({ ...cardBox }).items(mapped[i].filter((m) => m && typeof m === "object"))
2448
+ : new Card().set({ ...cardBox }).items([
2449
+ new Image(v(it.img)).set(it.alt === undefined ? { isFull: true, url: v(it.img) } : { isFull: true, url: v(it.img), alt: v(it.alt) }),
2450
+ new Text(v(it.title)).set({ size: "S5", tag: "h2", color: "#c2410c" }),
2451
+ new Link("Link").set({ text: v(it.title), url: v(it.link), ...linkStyle }),
2452
+ ])),
2453
+ };
2290
2454
  }
2291
2455
 
2292
2456
  /**
@@ -2479,14 +2643,16 @@ static form(obj){
2479
2643
  "array of { at, template }.");
2480
2644
  }
2481
2645
  const kids = Array.isArray(el.children) ? el.children : [];
2482
- const kidSrc = kids
2483
- .map((child) => {
2484
- const code = this.mapType({ ...obj, el: child }).toCode();
2646
+ // Mapped once: the instances go into the switcher, their code into the source.
2647
+ const kidInst = kids.map((child) => this.mapType({ ...obj, el: child }));
2648
+ const kidSrc = kidInst
2649
+ .map((m) => {
2650
+ const code = m.toCode();
2485
2651
  return Array.isArray(code) ? code.join("") : String(code);
2486
2652
  })
2487
2653
  .join(",\n ");
2488
2654
 
2489
- return `new AreaSwitcher()
2655
+ const src = `new AreaSwitcher()
2490
2656
  .set(${JSON.stringify({
2491
2657
  gap: el.gap ?? "10px",
2492
2658
  height: el.height ?? "700px",
@@ -2496,6 +2662,13 @@ static form(obj){
2496
2662
  .add([
2497
2663
  ${kidSrc}
2498
2664
  ])`;
2665
+ const sw = new AreaSwitcher().set({
2666
+ gap: el.gap ?? "10px",
2667
+ height: el.height ?? "700px",
2668
+ ...(el.id !== undefined ? { id: el.id } : {}),
2669
+ }).react(JSON.parse(JSON.stringify(react)));
2670
+ sw.add(kidInst);
2671
+ return this.withSource(sw, src);
2499
2672
  }
2500
2673
 
2501
2674
  static mapWrap(obj) {