@jam-overture/loom 0.1.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 (401) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +743 -0
  3. package/dist/catalogue.d.ts +70 -0
  4. package/dist/catalogue.js +88 -0
  5. package/dist/cli/args.d.ts +17 -0
  6. package/dist/cli/args.js +83 -0
  7. package/dist/cli/filesystem.d.ts +15 -0
  8. package/dist/cli/filesystem.js +31 -0
  9. package/dist/cli/index.d.ts +12 -0
  10. package/dist/cli/index.js +12 -0
  11. package/dist/cli/main.d.ts +3 -0
  12. package/dist/cli/main.js +30 -0
  13. package/dist/cli/namespace.d.ts +40 -0
  14. package/dist/cli/namespace.js +40 -0
  15. package/dist/cli/plan.d.ts +84 -0
  16. package/dist/cli/plan.js +113 -0
  17. package/dist/cli/run.d.ts +17 -0
  18. package/dist/cli/run.js +75 -0
  19. package/dist/cli/templates.d.ts +43 -0
  20. package/dist/cli/templates.js +134 -0
  21. package/dist/closed-set.d.ts +34 -0
  22. package/dist/closed-set.js +34 -0
  23. package/dist/data/adapter.d.ts +123 -0
  24. package/dist/data/adapter.js +91 -0
  25. package/dist/data/binding.d.ts +48 -0
  26. package/dist/data/binding.js +39 -0
  27. package/dist/data/catalogue.d.ts +26 -0
  28. package/dist/data/catalogue.js +6 -0
  29. package/dist/data/index.d.ts +14 -0
  30. package/dist/data/index.js +14 -0
  31. package/dist/data/plan.d.ts +58 -0
  32. package/dist/data/plan.js +0 -0
  33. package/dist/data/resolution.d.ts +91 -0
  34. package/dist/data/resolution.js +96 -0
  35. package/dist/data/resolve.d.ts +46 -0
  36. package/dist/data/resolve.js +37 -0
  37. package/dist/data/source.d.ts +40 -0
  38. package/dist/data/source.js +45 -0
  39. package/dist/deadline.d.ts +57 -0
  40. package/dist/deadline.js +78 -0
  41. package/dist/frame/catalogue.d.ts +24 -0
  42. package/dist/frame/catalogue.js +5 -0
  43. package/dist/frame/index.d.ts +12 -0
  44. package/dist/frame/index.js +12 -0
  45. package/dist/frame/origin.d.ts +87 -0
  46. package/dist/frame/origin.js +114 -0
  47. package/dist/frame/resolution.d.ts +85 -0
  48. package/dist/frame/resolution.js +79 -0
  49. package/dist/grammar.d.ts +26 -0
  50. package/dist/grammar.js +28 -0
  51. package/dist/ids.d.ts +57 -0
  52. package/dist/ids.js +104 -0
  53. package/dist/index.d.ts +26 -0
  54. package/dist/index.js +26 -0
  55. package/dist/interactivity.d.ts +50 -0
  56. package/dist/interactivity.js +22 -0
  57. package/dist/interpretation/anthropic.d.ts +22 -0
  58. package/dist/interpretation/anthropic.js +76 -0
  59. package/dist/interpretation/client.d.ts +83 -0
  60. package/dist/interpretation/client.js +2 -0
  61. package/dist/interpretation/draft.d.ts +234 -0
  62. package/dist/interpretation/draft.js +84 -0
  63. package/dist/interpretation/index.d.ts +15 -0
  64. package/dist/interpretation/index.js +15 -0
  65. package/dist/interpretation/interpreter.d.ts +62 -0
  66. package/dist/interpretation/interpreter.js +151 -0
  67. package/dist/interpretation/materialize.d.ts +42 -0
  68. package/dist/interpretation/materialize.js +107 -0
  69. package/dist/interpretation/prompt.d.ts +229 -0
  70. package/dist/interpretation/prompt.js +285 -0
  71. package/dist/interpretation/render.d.ts +76 -0
  72. package/dist/interpretation/render.js +272 -0
  73. package/dist/interpretation/schema.d.ts +49 -0
  74. package/dist/interpretation/schema.js +131 -0
  75. package/dist/json.d.ts +35 -0
  76. package/dist/json.js +11 -0
  77. package/dist/paging.d.ts +60 -0
  78. package/dist/paging.js +49 -0
  79. package/dist/primitive-type.d.ts +32 -0
  80. package/dist/primitive-type.js +39 -0
  81. package/dist/render/addressing.d.ts +59 -0
  82. package/dist/render/addressing.js +60 -0
  83. package/dist/render/anchor.d.ts +105 -0
  84. package/dist/render/anchor.js +84 -0
  85. package/dist/render/behaviour-adjust.d.ts +62 -0
  86. package/dist/render/behaviour-adjust.js +78 -0
  87. package/dist/render/behaviour-copy.d.ts +53 -0
  88. package/dist/render/behaviour-copy.js +75 -0
  89. package/dist/render/behaviour-disclose.d.ts +74 -0
  90. package/dist/render/behaviour-disclose.js +77 -0
  91. package/dist/render/behaviour-present.d.ts +123 -0
  92. package/dist/render/behaviour-present.js +173 -0
  93. package/dist/render/behaviour.d.ts +243 -0
  94. package/dist/render/behaviour.js +284 -0
  95. package/dist/render/control.d.ts +81 -0
  96. package/dist/render/control.js +80 -0
  97. package/dist/render/decorative.d.ts +62 -0
  98. package/dist/render/decorative.js +2 -0
  99. package/dist/render/diagnostics.d.ts +260 -0
  100. package/dist/render/diagnostics.js +61 -0
  101. package/dist/render/disclosed.d.ts +37 -0
  102. package/dist/render/disclosed.js +37 -0
  103. package/dist/render/editable.d.ts +34 -0
  104. package/dist/render/editable.js +35 -0
  105. package/dist/render/frame.d.ts +42 -0
  106. package/dist/render/frame.js +31 -0
  107. package/dist/render/index.d.ts +35 -0
  108. package/dist/render/index.js +35 -0
  109. package/dist/render/inline-variables.d.ts +77 -0
  110. package/dist/render/inline-variables.js +220 -0
  111. package/dist/render/presented.d.ts +82 -0
  112. package/dist/render/presented.js +82 -0
  113. package/dist/render/primitive.d.ts +228 -0
  114. package/dist/render/primitive.js +36 -0
  115. package/dist/render/props.d.ts +48 -0
  116. package/dist/render/props.js +2 -0
  117. package/dist/render/reads.d.ts +73 -0
  118. package/dist/render/reads.js +45 -0
  119. package/dist/render/render.d.ts +164 -0
  120. package/dist/render/render.js +571 -0
  121. package/dist/render/request.d.ts +111 -0
  122. package/dist/render/request.js +60 -0
  123. package/dist/render/text.d.ts +91 -0
  124. package/dist/render/text.js +44 -0
  125. package/dist/render/theme.d.ts +61 -0
  126. package/dist/render/theme.js +52 -0
  127. package/dist/reserved-props.d.ts +35 -0
  128. package/dist/reserved-props.js +45 -0
  129. package/dist/result.d.ts +27 -0
  130. package/dist/result.js +30 -0
  131. package/dist/role.d.ts +71 -0
  132. package/dist/role.js +22 -0
  133. package/dist/runtime/analysis.d.ts +149 -0
  134. package/dist/runtime/analysis.js +187 -0
  135. package/dist/runtime/assessment.d.ts +35 -0
  136. package/dist/runtime/assessment.js +13 -0
  137. package/dist/runtime/disposition.d.ts +102 -0
  138. package/dist/runtime/disposition.js +59 -0
  139. package/dist/runtime/events.d.ts +187 -0
  140. package/dist/runtime/events.js +7 -0
  141. package/dist/runtime/gate.d.ts +43 -0
  142. package/dist/runtime/gate.js +169 -0
  143. package/dist/runtime/index.d.ts +27 -0
  144. package/dist/runtime/index.js +27 -0
  145. package/dist/runtime/intent.d.ts +60 -0
  146. package/dist/runtime/intent.js +36 -0
  147. package/dist/runtime/interpreter.d.ts +117 -0
  148. package/dist/runtime/interpreter.js +46 -0
  149. package/dist/runtime/inverse-interpreter.d.ts +90 -0
  150. package/dist/runtime/inverse-interpreter.js +56 -0
  151. package/dist/runtime/inverse.d.ts +87 -0
  152. package/dist/runtime/inverse.js +48 -0
  153. package/dist/runtime/narration.d.ts +24 -0
  154. package/dist/runtime/narration.js +36 -0
  155. package/dist/runtime/nesting.d.ts +31 -0
  156. package/dist/runtime/nesting.js +46 -0
  157. package/dist/runtime/pipeline.d.ts +124 -0
  158. package/dist/runtime/pipeline.js +178 -0
  159. package/dist/runtime/policy-fingerprint.d.ts +29 -0
  160. package/dist/runtime/policy-fingerprint.js +119 -0
  161. package/dist/runtime/policy-source.d.ts +42 -0
  162. package/dist/runtime/policy-source.js +8 -0
  163. package/dist/runtime/policy.d.ts +156 -0
  164. package/dist/runtime/policy.js +107 -0
  165. package/dist/runtime/proposal.d.ts +423 -0
  166. package/dist/runtime/proposal.js +109 -0
  167. package/dist/runtime/redirection.d.ts +53 -0
  168. package/dist/runtime/redirection.js +38 -0
  169. package/dist/runtime/repointing.d.ts +71 -0
  170. package/dist/runtime/repointing.js +0 -0
  171. package/dist/runtime/reversibility.d.ts +36 -0
  172. package/dist/runtime/reversibility.js +39 -0
  173. package/dist/runtime/stake-level.d.ts +33 -0
  174. package/dist/runtime/stake-level.js +58 -0
  175. package/dist/runtime/stakes.d.ts +47 -0
  176. package/dist/runtime/stakes.js +305 -0
  177. package/dist/runtime/vocabulary.d.ts +122 -0
  178. package/dist/runtime/vocabulary.js +87 -0
  179. package/dist/sdk/audit.d.ts +195 -0
  180. package/dist/sdk/audit.js +128 -0
  181. package/dist/sdk/catalogue.d.ts +37 -0
  182. package/dist/sdk/catalogue.js +16 -0
  183. package/dist/sdk/conformance.d.ts +342 -0
  184. package/dist/sdk/conformance.js +494 -0
  185. package/dist/sdk/copy.d.ts +105 -0
  186. package/dist/sdk/copy.js +90 -0
  187. package/dist/sdk/definition.d.ts +242 -0
  188. package/dist/sdk/definition.js +64 -0
  189. package/dist/sdk/index.d.ts +19 -0
  190. package/dist/sdk/index.js +19 -0
  191. package/dist/sdk/interactivity.d.ts +29 -0
  192. package/dist/sdk/interactivity.js +34 -0
  193. package/dist/sdk/pairings.d.ts +124 -0
  194. package/dist/sdk/pairings.js +81 -0
  195. package/dist/sdk/registry.d.ts +162 -0
  196. package/dist/sdk/registry.js +329 -0
  197. package/dist/sdk/selection.d.ts +46 -0
  198. package/dist/sdk/selection.js +24 -0
  199. package/dist/sdk/text.d.ts +100 -0
  200. package/dist/sdk/text.js +105 -0
  201. package/dist/sdk/vocabulary.d.ts +39 -0
  202. package/dist/sdk/vocabulary.js +36 -0
  203. package/dist/signals/broadcast.d.ts +134 -0
  204. package/dist/signals/broadcast.js +451 -0
  205. package/dist/signals/collect.d.ts +184 -0
  206. package/dist/signals/collect.js +196 -0
  207. package/dist/signals/deliver.d.ts +64 -0
  208. package/dist/signals/deliver.js +85 -0
  209. package/dist/signals/fold.d.ts +112 -0
  210. package/dist/signals/fold.js +76 -0
  211. package/dist/signals/index.d.ts +31 -0
  212. package/dist/signals/index.js +31 -0
  213. package/dist/signals/ingest.d.ts +51 -0
  214. package/dist/signals/ingest.js +70 -0
  215. package/dist/signals/intake.d.ts +149 -0
  216. package/dist/signals/intake.js +154 -0
  217. package/dist/signals/journal.d.ts +94 -0
  218. package/dist/signals/journal.js +11 -0
  219. package/dist/signals/kinds.d.ts +22 -0
  220. package/dist/signals/kinds.js +22 -0
  221. package/dist/signals/ledger.d.ts +46 -0
  222. package/dist/signals/ledger.js +81 -0
  223. package/dist/signals/memory.d.ts +17 -0
  224. package/dist/signals/memory.js +99 -0
  225. package/dist/signals/migrate.d.ts +27 -0
  226. package/dist/signals/migrate.js +78 -0
  227. package/dist/signals/postgres.d.ts +7 -0
  228. package/dist/signals/postgres.js +295 -0
  229. package/dist/signals/rollup.d.ts +142 -0
  230. package/dist/signals/rollup.js +0 -0
  231. package/dist/signals/schema.d.ts +534 -0
  232. package/dist/signals/schema.js +92 -0
  233. package/dist/signals/signal.d.ts +381 -0
  234. package/dist/signals/signal.js +150 -0
  235. package/dist/signals/tally.d.ts +70 -0
  236. package/dist/signals/tally.js +2 -0
  237. package/dist/signals/view.d.ts +51 -0
  238. package/dist/signals/view.js +54 -0
  239. package/dist/store/attribution.d.ts +125 -0
  240. package/dist/store/attribution.js +116 -0
  241. package/dist/store/database.d.ts +14 -0
  242. package/dist/store/database.js +2 -0
  243. package/dist/store/driver.d.ts +29 -0
  244. package/dist/store/driver.js +39 -0
  245. package/dist/store/errors.d.ts +56 -0
  246. package/dist/store/errors.js +37 -0
  247. package/dist/store/index.d.ts +16 -0
  248. package/dist/store/index.js +16 -0
  249. package/dist/store/memory.d.ts +3 -0
  250. package/dist/store/memory.js +115 -0
  251. package/dist/store/migrate.d.ts +54 -0
  252. package/dist/store/migrate.js +122 -0
  253. package/dist/store/postgres-holds.d.ts +4 -0
  254. package/dist/store/postgres-holds.js +192 -0
  255. package/dist/store/postgres.d.ts +8 -0
  256. package/dist/store/postgres.js +262 -0
  257. package/dist/store/replay.d.ts +94 -0
  258. package/dist/store/replay.js +82 -0
  259. package/dist/store/revert.d.ts +116 -0
  260. package/dist/store/revert.js +243 -0
  261. package/dist/store/schema.d.ts +371 -0
  262. package/dist/store/schema.js +78 -0
  263. package/dist/store/source.d.ts +23 -0
  264. package/dist/store/source.js +37 -0
  265. package/dist/store/store.d.ts +231 -0
  266. package/dist/store/store.js +52 -0
  267. package/dist/store/undone.d.ts +18 -0
  268. package/dist/store/undone.js +89 -0
  269. package/dist/submit/catalogue.d.ts +20 -0
  270. package/dist/submit/catalogue.js +5 -0
  271. package/dist/submit/declaration.d.ts +39 -0
  272. package/dist/submit/declaration.js +30 -0
  273. package/dist/submit/endpoint.d.ts +131 -0
  274. package/dist/submit/endpoint.js +160 -0
  275. package/dist/submit/index.d.ts +13 -0
  276. package/dist/submit/index.js +13 -0
  277. package/dist/submit/plan.d.ts +49 -0
  278. package/dist/submit/plan.js +47 -0
  279. package/dist/submit/resolution.d.ts +61 -0
  280. package/dist/submit/resolution.js +64 -0
  281. package/dist/submit/resolve.d.ts +45 -0
  282. package/dist/submit/resolve.js +36 -0
  283. package/dist/telemetry/calibration.d.ts +132 -0
  284. package/dist/telemetry/calibration.js +151 -0
  285. package/dist/telemetry/episode.d.ts +140 -0
  286. package/dist/telemetry/episode.js +272 -0
  287. package/dist/telemetry/event.d.ts +2310 -0
  288. package/dist/telemetry/event.js +405 -0
  289. package/dist/telemetry/index.d.ts +15 -0
  290. package/dist/telemetry/index.js +15 -0
  291. package/dist/telemetry/journal.d.ts +116 -0
  292. package/dist/telemetry/journal.js +11 -0
  293. package/dist/telemetry/memory.d.ts +24 -0
  294. package/dist/telemetry/memory.js +75 -0
  295. package/dist/telemetry/migrate.d.ts +26 -0
  296. package/dist/telemetry/migrate.js +40 -0
  297. package/dist/telemetry/postgres.d.ts +6 -0
  298. package/dist/telemetry/postgres.js +139 -0
  299. package/dist/telemetry/retention.d.ts +131 -0
  300. package/dist/telemetry/retention.js +217 -0
  301. package/dist/telemetry/schema.d.ts +113 -0
  302. package/dist/telemetry/schema.js +33 -0
  303. package/dist/telemetry/sink.d.ts +42 -0
  304. package/dist/telemetry/sink.js +61 -0
  305. package/dist/testing/contracts.d.ts +34 -0
  306. package/dist/testing/contracts.js +34 -0
  307. package/dist/testing/definitions.d.ts +15 -0
  308. package/dist/testing/definitions.js +48 -0
  309. package/dist/testing/doubles.d.ts +94 -0
  310. package/dist/testing/doubles.js +141 -0
  311. package/dist/testing/episode-harness.d.ts +49 -0
  312. package/dist/testing/episode-harness.js +65 -0
  313. package/dist/testing/filesystem.d.ts +17 -0
  314. package/dist/testing/filesystem.js +17 -0
  315. package/dist/testing/fixtures.d.ts +57 -0
  316. package/dist/testing/fixtures.js +84 -0
  317. package/dist/testing/hold-contract.d.ts +19 -0
  318. package/dist/testing/hold-contract.js +374 -0
  319. package/dist/testing/index.d.ts +41 -0
  320. package/dist/testing/index.js +41 -0
  321. package/dist/testing/journal-contract.d.ts +17 -0
  322. package/dist/testing/journal-contract.js +353 -0
  323. package/dist/testing/model-replies.d.ts +34 -0
  324. package/dist/testing/model-replies.js +101 -0
  325. package/dist/testing/primitives.d.ts +7 -0
  326. package/dist/testing/primitives.js +29 -0
  327. package/dist/testing/reader-signal-contract.d.ts +38 -0
  328. package/dist/testing/reader-signal-contract.js +318 -0
  329. package/dist/testing/row-security.d.ts +17 -0
  330. package/dist/testing/row-security.js +21 -0
  331. package/dist/testing/store-contract.d.ts +25 -0
  332. package/dist/testing/store-contract.js +500 -0
  333. package/dist/theme/apply.d.ts +17 -0
  334. package/dist/theme/apply.js +60 -0
  335. package/dist/theme/contrast.d.ts +197 -0
  336. package/dist/theme/contrast.js +259 -0
  337. package/dist/theme/derive.d.ts +77 -0
  338. package/dist/theme/derive.js +167 -0
  339. package/dist/theme/faces.d.ts +73 -0
  340. package/dist/theme/faces.js +119 -0
  341. package/dist/theme/font-packs.d.ts +25 -0
  342. package/dist/theme/font-packs.js +257 -0
  343. package/dist/theme/index.d.ts +20 -0
  344. package/dist/theme/index.js +20 -0
  345. package/dist/theme/lab.d.ts +30 -0
  346. package/dist/theme/lab.js +46 -0
  347. package/dist/theme/library.d.ts +114 -0
  348. package/dist/theme/library.js +300 -0
  349. package/dist/theme/measure.d.ts +144 -0
  350. package/dist/theme/measure.js +145 -0
  351. package/dist/theme/palettes.d.ts +64 -0
  352. package/dist/theme/palettes.js +497 -0
  353. package/dist/theme/registry.d.ts +59 -0
  354. package/dist/theme/registry.js +60 -0
  355. package/dist/theme/separation.d.ts +177 -0
  356. package/dist/theme/separation.js +203 -0
  357. package/dist/theme/style-presets.d.ts +60 -0
  358. package/dist/theme/style-presets.js +124 -0
  359. package/dist/theme/theme.d.ts +253 -0
  360. package/dist/theme/theme.js +171 -0
  361. package/dist/tree/apply.d.ts +16 -0
  362. package/dist/tree/apply.js +104 -0
  363. package/dist/tree/builders.d.ts +19 -0
  364. package/dist/tree/builders.js +20 -0
  365. package/dist/tree/compare.d.ts +68 -0
  366. package/dist/tree/compare.js +75 -0
  367. package/dist/tree/configuration.d.ts +25 -0
  368. package/dist/tree/configuration.js +108 -0
  369. package/dist/tree/delta.d.ts +288 -0
  370. package/dist/tree/delta.js +88 -0
  371. package/dist/tree/errors.d.ts +69 -0
  372. package/dist/tree/errors.js +34 -0
  373. package/dist/tree/identity.d.ts +117 -0
  374. package/dist/tree/identity.js +145 -0
  375. package/dist/tree/index.d.ts +21 -0
  376. package/dist/tree/index.js +21 -0
  377. package/dist/tree/inverse.d.ts +24 -0
  378. package/dist/tree/inverse.js +112 -0
  379. package/dist/tree/mutation.d.ts +18 -0
  380. package/dist/tree/mutation.js +49 -0
  381. package/dist/tree/naming.d.ts +4 -0
  382. package/dist/tree/naming.js +35 -0
  383. package/dist/tree/navigation.d.ts +38 -0
  384. package/dist/tree/navigation.js +83 -0
  385. package/dist/tree/node.d.ts +103 -0
  386. package/dist/tree/node.js +46 -0
  387. package/dist/tree/outline.d.ts +28 -0
  388. package/dist/tree/outline.js +10 -0
  389. package/dist/tree/tree.d.ts +83 -0
  390. package/dist/tree/tree.js +62 -0
  391. package/dist/write/commit.d.ts +124 -0
  392. package/dist/write/commit.js +234 -0
  393. package/dist/write/held.d.ts +674 -0
  394. package/dist/write/held.js +185 -0
  395. package/dist/write/index.d.ts +11 -0
  396. package/dist/write/index.js +11 -0
  397. package/dist/write/liveness.d.ts +132 -0
  398. package/dist/write/liveness.js +91 -0
  399. package/dist/write/revert.d.ts +79 -0
  400. package/dist/write/revert.js +134 -0
  401. package/package.json +160 -0
package/README.md ADDED
@@ -0,0 +1,743 @@
1
+ # Loom
2
+
3
+ An AI-powered adaptive UI runtime. A UI is a validated tree; AI proposes discrete
4
+ changes to that tree; a pure Gate function decides what is allowed; the runtime
5
+ applies what survives and renders the result.
6
+
7
+ Pre-production alpha. Nothing here is stable yet.
8
+
9
+ ```bash
10
+ npm install @jam-overture/loom
11
+ ```
12
+
13
+ ## What is in the package, and what is not
14
+
15
+ `@jam-overture/loom` is the **framework**: the tree and its deltas, the Gate, the
16
+ interpretation seam, the render seam, the store, the write path, signals,
17
+ telemetry, the SDK, the testing contracts and the `loom` CLI. Fifteen entry
18
+ points, listed under [Entry points](#entry-points).
19
+
20
+ Four things that live in this repository are deliberately **not** in it, and
21
+ each is somebody's product rather than the framework's plumbing
22
+ (`decisions/0194-the-framework-is-the-package-and-everything-that-uses-it-ships-separately.md`):
23
+
24
+ | not published here | what it is |
25
+ | --- | --- |
26
+ | the starter primitive library | ten primitives a deployment may adopt — a library to choose from, with its own release rhythm |
27
+ | the marketing site, the documentation, the lessons | `apps/loom`, one Next.js application, deployed rather than packaged |
28
+ | the demonstration | a surface, not an import |
29
+ | the portal | a tool over a deployment's own tree |
30
+
31
+ So `@jam-overture/loom/primitives` resolves inside this workspace and **is not a
32
+ subpath of the published package.** Everything the README says about the
33
+ starter primitives below is about this repository; a separate package for them
34
+ is the next step and does not exist yet.
35
+
36
+ ## Entry points
37
+
38
+ Fifteen, each a subpath of the one package. Everything after `.` is there so a
39
+ host can take a part of Loom without the rest; the optional peers are optional
40
+ because the core is usable without any of them.
41
+
42
+ | import | what it is |
43
+ | --- | --- |
44
+ | `@jam-overture/loom` | the tree, the deltas, the Gate, the runtime pipeline, the vocabularies |
45
+ | `@jam-overture/loom/anthropic` | the interpretation seam against Anthropic's API — needs `@anthropic-ai/sdk` |
46
+ | `@jam-overture/loom/react` | tree to React, per request — needs `react` |
47
+ | `@jam-overture/loom/sdk` | the primitive registration contract, registries and audits — needs `react` |
48
+ | `@jam-overture/loom/cli` | the `loom` scaffolding command, as a library |
49
+ | `@jam-overture/loom/store` | tree storage, in memory |
50
+ | `@jam-overture/loom/write` | the write path: intent in, disposition out |
51
+ | `@jam-overture/loom/postgres` | the same store over Postgres — needs `drizzle-orm` |
52
+ | `@jam-overture/loom/signals` | reader signals, parsed and reduced |
53
+ | `@jam-overture/loom/signals/broadcast` | the browser half: a published page reporting what readers did |
54
+ | `@jam-overture/loom/signals/postgres` | signal storage — needs `drizzle-orm` |
55
+ | `@jam-overture/loom/telemetry` | proposal, provenance, disposition and outcome |
56
+ | `@jam-overture/loom/telemetry/postgres` | telemetry storage — needs `drizzle-orm` |
57
+ | `@jam-overture/loom/testing` | fixtures and sample trees |
58
+ | `@jam-overture/loom/testing/contracts` | the conformance suites a primitive must pass — needs `vitest`, and only loads inside a test run |
59
+
60
+ `@jam-overture/loom` itself depends only on `zod`. `react`, `@anthropic-ai/sdk`,
61
+ `drizzle-orm` and `vitest` are optional peer dependencies: install the ones the
62
+ subpaths you use name, and nothing else.
63
+
64
+ ## Why a tree and a delta, not generated code
65
+
66
+ AI that emits UI code cannot be reviewed, gated, or reverted at a useful
67
+ granularity. Loom narrows what AI may produce to a `TreeDelta` — an ordered list
68
+ of four discrete operations against an existing tree. That makes every proposed
69
+ change addressable ("insert a checkout button into the sidebar"), reviewable by a
70
+ pure function, attributable in telemetry, and reversible.
71
+
72
+ ## Build order
73
+
74
+ 1. **Tree schema** — the AST, the NodeId scheme, `TreeDelta`
75
+ 2. **Composition Runtime** — `EditIntent → ProposedChange → Gate → Disposition → Apply`
76
+ 3. **Adaptive Renderer** — edge/RSC resolver, tree → React, per request
77
+ 4. **Framework SDK** — primitive registration contract, CLI scaffolding
78
+ 5. **Portal** — a thin UI over the persisted tree
79
+ 6. **Telemetry** — proposal, provenance, disposition, and outcome, captured from day one
80
+ 7. **Marketplace** — last, and not started
81
+
82
+ Sections 1–6 are built and run end to end. What is still open in each is tracked
83
+ in the latest report in [`reports/`](reports/) rather than here, because a marker
84
+ in a README is a thing that goes stale quietly.
85
+
86
+ ### Reader signals
87
+
88
+ The part of adaptation that happens on a live page. A render with
89
+ `addressed: true` puts node ids on published markup, and
90
+ `@jam-overture/loom/signals/broadcast` reports four closed kinds of signal from it —
91
+ `viewed`, `dwelled`, `activated`, `disclosed` — naming nodes and never content,
92
+ filed under the tree and revision the page was rendered from
93
+ ([0136](decisions/0136-a-published-page-broadcasts-reader-signals-when-its-host-asks.md)).
94
+ Off unless a host starts it, and configured by the host rather than the tree.
95
+
96
+ Broadcasting is built. **Capturing, storing and showing signals are approved as
97
+ of 13 September** and planned in [`docs/signals.md`](docs/signals.md), which
98
+ supersedes the deferral in `reports/2026-09-12-reader-signals.md`: five steps in
99
+ order, each with the lane that owns it, and the rules the seam keeps — a signal
100
+ stays anonymous and node-shaped, and a funnel is correlated inside one page view
101
+ ([0146](decisions/0146-a-reader-signal-stays-anonymous-and-a-funnel-is-correlated-inside-one-page-view.md)).
102
+ Read it before starting anything that consumes signals.
103
+
104
+ ### 4b — The primitive library
105
+
106
+ §4 built the contract a primitive registers under. It never built anything to
107
+ register, and an empty registry is the reason nothing downstream can be shown:
108
+ the portal has no interesting tree to review, a marketplace would have nothing
109
+ to list, and no demo exists. The vocabulary is the gap between an architecture
110
+ and a product.
111
+
112
+ The source is the Hermes predecessor — 70 block definitions with 72 React
113
+ renderers, 54 shapes, 18 layouts, and a theme system of 29 palettes, 22 font
114
+ packs and 10 style presets. It is a **port, not a copy**; four things differ:
115
+
116
+ | | Hermes | Loom |
117
+ | --- | --- | --- |
118
+ | Prop model | `FieldDef[]` over a custom union | Zod schema per primitive |
119
+ | Composition | leaves in a flat `warp.blocks` list | nesting, via slots and children |
120
+ | Data | `binding` fields resolved from profile + integrations | plain JSON props, no resolution layer |
121
+ | Renderer contract | `{instance, resolvedFields, isOwner, onEdit}` | `{loom, props, children}`, spreading `loom.editable` |
122
+
123
+ Order, and the reason for it:
124
+
125
+ 1. **Theme** — done ([0049](decisions/0049-a-theme-is-three-ids-in-the-tree.md),
126
+ [0050](decisions/0050-the-runtimes-props-are-namespaced-and-the-root-mounts-the-theme.md)).
127
+ Three registered ids on the root node, resolved per render and mounted by the
128
+ root primitive as CSS custom properties, so a ported renderer reading
129
+ `var(--loom-accent)` is styled and a re-theme is an ordinary `configure`.
130
+ 2. **Ten primitives, not seventy** — done
131
+ ([0051](decisions/0051-a-slot-is-a-region-the-primitive-places.md),
132
+ [0052](decisions/0052-a-repeated-item-is-a-node-and-a-fixed-field-is-a-prop.md),
133
+ [0053](decisions/0053-a-url-in-the-tree-is-checked-against-a-scheme-allowlist.md)).
134
+ Chosen to cover the *contract* rather than the catalogue: four that compose,
135
+ two of them through named slots; five leaves; one with a rich prop schema and
136
+ a cross-field rule; one driven by an enum that changes what is rendered; and
137
+ one container/child pair that shows how every remaining Hermes list block
138
+ decomposes. See [the starter library](#the-starter-primitives).
139
+ 3. **The demo vocabulary, and then the demo** — done. The vocabulary came first
140
+ (eight composed primitives, taking the library to eighteen) because a page
141
+ built from `section` + `prose` + `stat-grid` is a layout demo, and what this
142
+ step has to produce is something that looks like a product. The demo list and
143
+ the marketing list are one list, so §4d builds the real site from these rather
144
+ than beside them.
145
+
146
+ The demo itself is `/demo`, public, in the portal deployment
147
+ ([0056](decisions/0056-the-demo-is-public-and-shares-nothing-but-the-deployment.md)):
148
+ a real page on the left, and on the right the record of every change to it —
149
+ the proposal with its rationale and provenance, the stakes factors and the
150
+ reversibility verdict, which rule fired under which policy, the revision it
151
+ produced and what it replaced, and an undo that is a proposal like any other.
152
+ Five scripted changes cover all four delta operations and need no key
153
+ ([0057](decisions/0057-a-preset-is-a-deterministic-interpreter.md)); free text
154
+ goes to the model when one is configured. It is the first end-to-end run of
155
+ §1–§6 against something not written to pass its own tests.
156
+
157
+ Three things approved on #68 rode along with the vocabulary and are done:
158
+ `auditRegistry` probes for slot placement and reports which primitives are
159
+ leaves; the theme registry joins the catalogue the model is shown; and
160
+ decomposed pairs have a naming rule
161
+ ([0054](decisions/0054-a-container-is-its-childs-name-plus-the-arrangement.md)).
162
+ 4. **Data** — the seam the port hits at the first primitive that needs any
163
+ ([§4e](#4e--data-what-a-primitive-cannot-be-told-in-props), done), **text** —
164
+ the strings a primitive owns rather than reads from the tree
165
+ ([§4f](#4f--text-the-strings-a-primitive-owns), done), and **submissions** —
166
+ where a form's contents go
167
+ ([§4g](#4g--submissions-where-a-forms-contents-go), done). All three are the
168
+ same shape of gap: something a page needs that props cannot carry.
169
+ 5. **The remaining primitives**, which by then are mechanical — and they come
170
+ after §4c and §4d, because a site that shows the runtime is worth more than
171
+ the fifty-second block. Only then §7, since a marketplace of primitives needs
172
+ primitives.
173
+
174
+ Refinement inside §1–§6 is **reactive from here**: driven by what the port
175
+ breaks, not run as its own stream.
176
+
177
+ ### 4e — Data: what a primitive cannot be told in props
178
+
179
+ Five of the seventy Hermes blocks resolve a `binding` rather than reading a
180
+ prop: `about` binds three fields to one profile, and `services`, `products`,
181
+ `feed` and `marquee` bind a list to a connected integration. Ported without an
182
+ answer they become an author typing their own services in by hand, which is not
183
+ the block anyone used.
184
+
185
+ **A binding is a question the tree asks, and never an answer**
186
+ ([0058](decisions/0058-a-binding-is-a-question-the-tree-asks-answered-before-the-walk.md)).
187
+ `loom:data` is the second key in the reserved namespace 0050 opened, and it
188
+ names a registered source and the params to ask it with:
189
+
190
+ ```json
191
+ "loom:data": { "services": { "source": "catalogue.services", "params": { "limit": 6 } } }
192
+ ```
193
+
194
+ Resolution happens in three steps, and the middle one is the only IO in serving
195
+ a page: `planTreeData` reads every binding out of the tree as a pure pass and
196
+ deduplicates it, `resolveDataPlan` asks every question at once, and
197
+ `renderLoomTree` takes the finished answers and stays as synchronous as it was.
198
+ `renderRequest` is where the three meet.
199
+
200
+ A source is registered like a primitive is. `defineSource` declares what it
201
+ accepts and what it answers, both as Zod; the registry is the allowlist a
202
+ binding can reach, params are checked before the adapter is called and the
203
+ answer after. A primitive reads `loom.data`, beside `props` rather than merged
204
+ into it, and every answer is either `ready` or `unavailable` **with a reason** —
205
+ "you have no services yet" and "we could not reach your services" are different
206
+ sentences and a shape that cannot tell them apart eventually shows the wrong one.
207
+
208
+ What is not built yet is the authoring half: a primitive declaring which binding
209
+ names it reads, so the catalogue can tell a model that `loom.services` wants a
210
+ `services` binding. Until then a bound tree is hand-authored, and no starter
211
+ primitive binds anything.
212
+
213
+ ### 4f — Text: the strings a primitive owns
214
+
215
+ Almost every user-facing string on a page comes from the tree. A few cannot: a
216
+ marker glyph carries an accessible name the visible label does not say, and
217
+ making that a prop would put an accessible name in the space a model writes.
218
+ Left inline in the component it is untranslatable, and a German deployment
219
+ renders an English "Not included" in the middle of a German pricing table — the
220
+ gap the primitives routine hit at `loom.perk` and filed.
221
+
222
+ **A primitive declares the strings it owns; a deployment may replace them**
223
+ ([0060](decisions/0060-a-primitive-owns-a-string-and-a-deployment-may-replace-it.md)).
224
+ `definePrimitive` takes a `text` map in the author's own language, the keys are
225
+ typed so a component can only read what it declared, and what reaches
226
+ `loom.text` is the translation where there is one and the declared string where
227
+ there is not — never a missing key.
228
+
229
+ ```ts
230
+ text: { excluded: "Not included", coming: "Coming soon" }
231
+ ```
232
+
233
+ A registry is a `TextResolver` over its own declarations, so an untranslated
234
+ deployment is the base case rather than a fallback path. `textResolverFor` lays a
235
+ dictionary over it, merging once per dictionary rather than once per node;
236
+ `textCatalogue` is the extraction a translation file is written from, and
237
+ `textCoverage` says what a dictionary answers, what it does not, and which of its
238
+ keys name nothing. Which language a visitor gets stays the host's decision — the
239
+ framework never reads a request header.
240
+
241
+ ### 4g — Submissions: where a form's contents go
242
+
243
+ Three of the seventy Hermes blocks are blocked on a seam rather than on a
244
+ primitive, and two of them are the same one: `contactform` and `newsletter` are a
245
+ field list and a submit. The field list is an ordinary
246
+ [0052](decisions/0052-a-repeated-item-is-a-node-and-a-fixed-field-is-a-prop.md)
247
+ decomposition. The submit is a decision about where a deployment's data goes,
248
+ and a URL in a prop is AI-authored by definition — a scheme allowlist does not
249
+ help, because `https://collect.example.com/harvest` passes it.
250
+
251
+ **A submission names a destination, and never carries one**
252
+ ([0065](decisions/0065-a-submission-names-a-destination-and-never-carries-one.md)).
253
+ A node names a registered endpoint and nothing else:
254
+
255
+ ```json
256
+ "loom:submit": { "to": "contact.enquiry" }
257
+ ```
258
+
259
+ `defineEndpoint` is the host's half — it answers with an `action`, a `method`,
260
+ and the hidden `fields` a form must carry, a CSRF token being why that list
261
+ exists. Resolution happens before the walk, beside the data seam and at the same
262
+ time as it, so the renderer stays synchronous. A form has a target, or an
263
+ `unavailable` with a reason, or nothing at all when the tree never said — three
264
+ states, because a submit button that silently goes nowhere is the failure the
265
+ shape exists to prevent. There are deliberately no params: a deployment with two
266
+ lists registers two endpoints, and the id is the whole AI-authored surface.
267
+
268
+ ### 4c — The documentation site ← current
269
+
270
+ Modelled on `nextjs.org/docs`. Two decisions are settled and are not worth
271
+ relitigating:
272
+
273
+ - **MDX for prose and code blocks.** Documentation is prose, and prose is not
274
+ improved by being a node tree. The tree model earns its keep where a page is
275
+ *configured* rather than written.
276
+ - **Every rendered example on the page is a real `LoomTree`**, mounted through
277
+ the runtime with a working propose-a-change box beside it. An example is a
278
+ registry entry, so an example that cannot render is a failing test rather than
279
+ a stale snippet — which is only affordable because a demonstrated change is a
280
+ deterministic interpreter
281
+ ([0057](decisions/0057-a-preset-is-a-deterministic-interpreter.md)) and needs
282
+ no key to run.
283
+
284
+ ### 4d — The marketing site
285
+
286
+ **Built entirely in Loom**: composed sections, themed, adapting. It reuses the
287
+ §4b step 3 primitives — the site is the proof, not a brochure about it — and it
288
+ embeds the demo rather than describing it, which is why the demo is public
289
+ ([0056](decisions/0056-the-demo-is-public-and-shares-nothing-but-the-deployment.md)).
290
+
291
+ Positioning, audience and licensing are the maintainer's and are not engineering
292
+ questions. They are asked, not invented.
293
+
294
+ ## Layout
295
+
296
+ ```
297
+ src/
298
+ ├── ids.ts # Brand-typed NodeId / TreeId / DeltaId + the IdFactory seam
299
+ ├── json.ts # The JSON value space every boundary is restricted to
300
+ ├── primitive-type.ts # Primitive type and slot name identifiers
301
+ ├── reserved-props.ts # The `loom:` namespace: the runtime's own props
302
+ ├── result.ts # Result<T, E> — nothing throws across a seam
303
+ ├── testing/ # Deterministic fixtures and test doubles
304
+ ├── tree/
305
+ │ ├── node.ts # The discriminated-union AST: element | text | slot
306
+ │ ├── tree.ts # The LoomTree document, revisions, boundary parsing
307
+ │ ├── navigation.ts # Read-only traversal
308
+ │ ├── configuration.ts # The settable surface of each node kind
309
+ │ ├── mutation.ts # Immutable structural edits
310
+ │ ├── delta.ts # TreeDelta and its four operations
311
+ │ ├── apply.ts # Pure, atomic delta application
312
+ │ ├── inverse.ts # The delta that undoes a delta
313
+ │ └── builders.ts # Construction helpers for trusted callers
314
+ ├── runtime/
315
+ │ ├── intent.ts # EditIntent — what someone wants, before interpretation
316
+ │ ├── proposal.ts # ProposedChange + Provenance — what came back, and from where
317
+ │ ├── interpreter.ts # The AI seam; the only non-deterministic step
318
+ │ ├── analysis.ts # Pure facts about what a delta does
319
+ │ ├── stakes.ts # How much damage, as named factors
320
+ │ ├── reversibility.ts # Whether it can be taken back, via the inverse
321
+ │ ├── policy.ts # GatePolicy — the knobs, host and structural
322
+ │ ├── policy-source.ts # Which policy judges a given change
323
+ │ ├── gate.ts # The pure decision function
324
+ │ ├── events.ts # RuntimeEvent, EventSink, Clock
325
+ │ └── pipeline.ts # composeChange / confirmChange
326
+ ├── interpretation/ # The model-backed ChangeInterpreter
327
+ │ ├── client.ts # ModelClient — the whole network boundary
328
+ │ ├── draft.ts # What a model may say: the AST, minus identity
329
+ │ ├── schema.ts # The JSON Schema its reply is constrained to
330
+ │ ├── render.ts # The tree as an outline the model can address
331
+ │ ├── prompt.ts # Prompt assembly and the provenance hash
332
+ │ ├── materialize.ts # Draft → TreeDelta, minting every new id
333
+ │ ├── interpreter.ts # The ChangeInterpreter itself
334
+ │ └── anthropic.ts # Vendor adapter — a separate entry point
335
+ ├── render/ # The adaptive renderer — a separate entry point
336
+ │ ├── primitive.ts # What a primitive receives; the resolver seam
337
+ │ ├── props.ts # The prop-validation seam
338
+ │ ├── editable.ts # Edit-mode decoration, as attributes
339
+ │ ├── diagnostics.ts # What rendering could not honour
340
+ │ ├── theme.ts # The reserved prop namespace, and the theme read from it
341
+ │ ├── text.ts # The strings a primitive owns, and the seam that translates them
342
+ │ ├── render.ts # The tree, projected into React
343
+ │ └── request.ts # Per-request resolution: load, validate, render
344
+ ├── data/ # The data seam — the only IO in serving a page
345
+ │ ├── source.ts # Source ids and binding names
346
+ │ ├── binding.ts # What a node asks, as it appears in the tree
347
+ │ ├── adapter.ts # defineSource, the adapter contract, the registry
348
+ │ ├── plan.ts # The tree's questions, deduplicated — a pure pass
349
+ │ ├── resolve.ts # Asking them, all at once, catching everything
350
+ │ ├── resolution.ts # The answers, indexed the way the walk needs them
351
+ │ └── catalogue.ts # What a deployment can ask about, as data
352
+ ├── submit/ # The submission seam — where a form's contents go
353
+ │ ├── endpoint.ts # defineEndpoint, the target contract, the registry
354
+ │ ├── declaration.ts # What a node names, as it appears in the tree
355
+ │ ├── plan.ts # The tree's endpoints, deduplicated — a pure pass
356
+ │ ├── resolve.ts # Asking them, all at once, catching everything
357
+ │ ├── resolution.ts # The targets, indexed the way the walk needs them
358
+ │ └── catalogue.ts # Where a deployment will accept a submission
359
+ ├── catalogue.ts # What a deployment can build with, as data
360
+ ├── primitives/ # The starter library — a separate entry point
361
+ │ ├── tokens.ts # The only way a primitive names a colour or a length
362
+ │ ├── url.ts # The scheme allowlist every href and src is held to
363
+ │ ├── loom.page.ts # …and one module per primitive, named for its type
364
+ │ └── index.ts # The ten, and a registry over them
365
+ ├── sdk/ # The framework SDK — a separate entry point
366
+ │ ├── definition.ts # The registration contract: definePrimitive
367
+ │ ├── registry.ts # The registry: resolver and validator in one object
368
+ │ ├── conformance.ts # Does a primitive spread loom.editable?
369
+ │ ├── audit.ts # The conformance check a host runs
370
+ │ ├── text.ts # Dictionaries, extraction, and what a translation covers
371
+ │ └── catalogue.ts # The registry, projected for consumers outside it
372
+ ├── cli/ # Scaffolding — a separate entry point
373
+ │ ├── args.ts # The grammar: two commands, one option
374
+ │ ├── templates.ts # What gets written, as pure functions of a name
375
+ │ ├── plan.ts # What a command would write, decided before writing
376
+ │ ├── filesystem.ts # The one impure seam
377
+ │ ├── run.ts # parse → plan → write
378
+ │ ├── main.ts # The executable entry point
379
+ │ └── scaffold-fixture/ # `loom init`'s output, committed so it is typechecked
380
+ └── store/ # Persistence — a separate entry point
381
+ ├── store.ts # TreeStore: the contract, and what it may refuse
382
+ ├── memory.ts # The reference implementation: log plus snapshot
383
+ ├── replay.ts # Folding the log, and auditing the snapshot against it
384
+ ├── attribution.ts # Who placed each node, walked back out of the log
385
+ └── source.ts # The store as the renderer's TreeSource
386
+ ```
387
+
388
+ ## The workspace
389
+
390
+ The repo is a pnpm workspace with two packages. `@jam-overture/loom` is the root;
391
+ `@loom/app` is `apps/loom`, and it depends on the runtime as `workspace:*` so it
392
+ can only reach the published entry points — a deep import into `src/` does not
393
+ resolve. When a surface needs something the public API does not expose, that is a
394
+ framework gap to close in the framework (see
395
+ [0018](decisions/0018-the-portal-is-a-consumer-not-an-insider.md)).
396
+
397
+ **`apps/loom` is one Next.js application with four surfaces in it**, one route
398
+ group each ([0067](decisions/0067-the-four-surfaces-are-one-application.md)). A
399
+ route group contributes nothing to a URL, so what a group holds is the surface's
400
+ own root layout, its own stylesheet and its own code — and what a reader types is
401
+ the segment underneath it.
402
+
403
+ ```
404
+ apps/loom/
405
+ ├── proxy.ts # Sign-in, scoped to /portal and nothing else
406
+ └── app/
407
+ ├── (marketing)/ # / — the site, composed in Loom
408
+ ├── (docs)/ # /docs — prose, in MDX
409
+ ├── (lessons)/ # /lessons — the course
410
+ └── (portal)/ # /portal — behind sign-in
411
+ ├── globals.css # The silver design system, as tokens
412
+ ├── layout.tsx # Topbar, rail, and the content column
413
+ ├── _components/ # Topbar, sidebar, nav items
414
+ ├── _lib/ # View models, the store, auth
415
+ └── portal/ # The routes themselves
416
+ ```
417
+
418
+ Three of the four are **built in Loom** — they compose registered primitives and
419
+ may not grow a component library of their own. The portal is the stated exception
420
+ (0067): it is a tool for reviewing Loom trees rather than content built out of
421
+ them.
422
+
423
+ `pnpm verify` at the root compiles the runtime, typechecks it, runs its tests,
424
+ then runs the application's typecheck, tests and build. The build is part of it
425
+ because prerendering is what proves the surfaces render.
426
+
427
+ **The build comes first, and that order is load-bearing.** `src/cli/scaffold-fixture/`
428
+ is checked-in scaffold output, and it imports `@jam-overture/loom/react` and
429
+ `@jam-overture/loom/sdk` the way a consumer does — through the `exports` map, which
430
+ points at `dist/`. Typechecking before the build fails on a clean clone with four
431
+ `TS2307`s, so the build has to have run. Keeping it in this order rather than
432
+ mapping those specifiers back to `src/` means the typecheck also proves the
433
+ `exports` map resolves, which is the thing a consumer actually depends on.
434
+
435
+ The runtime compiles to `dist/` and every entry point resolves there (0030), so
436
+ the application consumes it as an ordinary Node package rather than as TypeScript
437
+ source. `apps/loom` builds the runtime before its own typecheck and build,
438
+ because a clean clone has no `dist` and a build order that is not written down is
439
+ one that fails somewhere else.
440
+
441
+ ## Deploying
442
+
443
+ All four surfaces deploy to Vercel as one project from `apps/loom`. Settings, and
444
+ what a deployment can and cannot do before a backing store lands, are in
445
+ [`docs/deployment.md`](docs/deployment.md).
446
+
447
+ ## Learning Loom
448
+
449
+ `lessons/` is a course on the ideas rather than the API. Each lesson starts from
450
+ a problem, shows why the obvious solution fails, and only then shows what Loom
451
+ does instead — with exercises you run. [Start with the syllabus](lessons/README.md).
452
+
453
+ New to the codebase? Read [lesson 01](lessons/01-why-a-runtime.md) before
454
+ anything else; it is the thesis the rest of the system defends.
455
+
456
+ ## Decisions
457
+
458
+ `decisions/` holds numbered architectural decision records — what was chosen,
459
+ what was rejected, and why. [Start with the index](decisions/README.md).
460
+
461
+ Decision records and lessons answer different questions. A record says *what we
462
+ decided and what we rejected*; it is written for someone deciding whether to
463
+ change it. A lesson says *why this is the right shape and how to think in it*;
464
+ it is written for someone learning. Neither substitutes for the other.
465
+
466
+ ## Commands
467
+
468
+ ```bash
469
+ pnpm verify
470
+ ```
471
+
472
+ `pnpm typecheck`, `pnpm test`, `pnpm test:coverage` run the pieces individually.
473
+
474
+ ## Optional: the Anthropic interpreter
475
+
476
+ The model client is a one-method seam, and the Anthropic adapter is a separate
477
+ entry point so that hosts bringing their own model never load it:
478
+
479
+ ```bash
480
+ pnpm add @anthropic-ai/sdk # optional peer dependency
481
+ ```
482
+
483
+ ```ts
484
+ import Anthropic from "@anthropic-ai/sdk"
485
+ import { modelInterpreter, randomIdFactory, systemClock } from "@jam-overture/loom"
486
+ import { anthropicModelClient } from "@jam-overture/loom/anthropic"
487
+
488
+ const interpreter = modelInterpreter({
489
+ client: anthropicModelClient(new Anthropic().messages),
490
+ idFactory: randomIdFactory,
491
+ clock: systemClock,
492
+ })
493
+ ```
494
+
495
+ `ANTHROPIC_API_KEY` is read from the environment by the SDK. One live smoke test
496
+ exercises the real API and skips when the key is absent, so `pnpm verify` is
497
+ green offline.
498
+
499
+ That test reads **`LOOM_ANTHROPIC_API_KEY` first**, falling back to
500
+ `ANTHROPIC_API_KEY`. The scheduled agent that develops this repo authenticates
501
+ with `ANTHROPIC_API_KEY` itself and strips it from the environment of the
502
+ processes it spawns, so a key set under the standard name never reaches Vitest
503
+ there. Set `LOOM_ANTHROPIC_API_KEY` in that environment; the standard name works
504
+ everywhere else.
505
+
506
+ ## Optional: the React renderer
507
+
508
+ The renderer is a separate entry point too, and `react` is an optional peer
509
+ dependency, so a host that only composes and stores trees never installs it:
510
+
511
+ ```bash
512
+ pnpm add react # optional peer dependency
513
+ ```
514
+
515
+ ```ts
516
+ import { renderRequest, staticPrimitiveResolver } from "@jam-overture/loom/react"
517
+
518
+ const rendered = await renderRequest(
519
+ { treeId, editMode: false },
520
+ { source, resolver: staticPrimitiveResolver({ "loom.page": Page, "loom.card": Card }) }
521
+ )
522
+ ```
523
+
524
+ A primitive receives three props — `loom` (its node id, type, edit-mode
525
+ decoration, its named regions, and — on the root node only — the mounted theme),
526
+ `props` (the node's props, unspread), and `children`. Rendering is
527
+ pure and total: it has no hooks and no IO, so it runs per request at the edge or
528
+ in a Server Component, and anything it could not render comes back in
529
+ `diagnostics` rather than as a thrown error.
530
+
531
+ ### Named regions
532
+
533
+ A primitive that treats one part of its contents differently from the rest
534
+ declares a slot, and places it. The element's `slot` children arrive on
535
+ `loom.slots` keyed by name, and are **not** in `children` — so a region is a
536
+ place the primitive chooses, rather than a position in a list that any `move`
537
+ could change (0051):
538
+
539
+ ```tsx
540
+ const Split = ({ loom, children }) => (
541
+ <div {...loom.editable} style={{ display: "flex", flexWrap: "wrap" }}>
542
+ <div>{loom.slots.start}{children}</div>
543
+ <div>{loom.slots.end}</div>
544
+ </div>
545
+ )
546
+ ```
547
+
548
+ A region the primitive does not place renders nothing. A host still projects
549
+ into a region by name through `renderRequest`'s `slots` option, and what it
550
+ projects reaches the primitive the same way.
551
+
552
+ ## Wearing a theme
553
+
554
+ A theme is three registered ids — a palette, a font pack, a style preset —
555
+ carried on the root node under the runtime's reserved prop key, so changing one
556
+ is an ordinary `configure` the Gate weighs like any other change (0049):
557
+
558
+ ```ts
559
+ import { createThemeRegistry } from "@jam-overture/loom"
560
+ import { THEME_PROP_KEY } from "@jam-overture/loom/react"
561
+
562
+ const root = {
563
+ kind: "element",
564
+ type: "loom.page",
565
+ props: { [THEME_PROP_KEY]: { palette: "bold", fontPack: "bold-sans", stylePreset: "airy-modern" } },
566
+ // …
567
+ }
568
+
569
+ const rendered = await renderRequest(request, { source, resolver, themes: createThemeRegistry() })
570
+ ```
571
+
572
+ The renderer resolves the selection, flattens it into `--loom-*` custom
573
+ properties, and hands them to the **root** primitive as `loom.theme`. A
574
+ primitive applies it as its `style` and reads colour, type and spacing back out
575
+ through `var(--loom-accent)` and friends, so it never learns which palette it is
576
+ wearing and a re-theme touches no node below the root:
577
+
578
+ ```tsx
579
+ const Page = ({ loom, children }) => (
580
+ <main {...loom.editable} style={loom.theme}>{children}</main>
581
+ )
582
+ ```
583
+
584
+ Prop keys beginning with `loom:` belong to the runtime: they are read at the
585
+ render seam and never reach a primitive or its schema, so a root primitive can
586
+ declare `.strict()` props and still wear a theme. A theme that cannot be
587
+ resolved renders unstyled with a diagnostic, never a blank page, and there is no
588
+ fallback theme — the page is a function of the tree, not of deployment config.
589
+ Both are argued in
590
+ [0050](decisions/0050-the-runtimes-props-are-namespaced-and-the-root-mounts-the-theme.md).
591
+
592
+ ## Registering primitives
593
+
594
+ A primitive declares what a tree may set on it. The registry is both the
595
+ renderer's resolver and its prop validator, because a component's narrowed prop
596
+ type is only sound when the same object vetted the props:
597
+
598
+ ```ts
599
+ import { catalogueOf, createPrimitiveRegistry, definePrimitive } from "@jam-overture/loom/sdk"
600
+
601
+ const card = definePrimitive({
602
+ type: "loom.card",
603
+ description: "A bounded block of related content",
604
+ props: z.object({ variant: z.enum(["outlined", "filled"]), elevation: z.number().optional() }).strict(),
605
+ component: ({ loom, props, children }) =>
606
+ <article {...loom.editable} data-variant={props.variant}>{children}</article>,
607
+ })
608
+
609
+ const registry = createPrimitiveRegistry([card]) // Result — refuses duplicates and bad identifiers
610
+ if (!registry.ok) throw new Error(describeRegistryError(registry.error))
611
+
612
+ const rendered = await renderRequest(request, {
613
+ source,
614
+ resolver: registry.value,
615
+ validator: registry.value,
616
+ })
617
+ ```
618
+
619
+ A node whose props fail its primitive's schema is omitted with an `invalid-props`
620
+ diagnostic, exactly as an unknown primitive is. Validation is a predicate, never a
621
+ codec: a primitive is handed the tree's props unchanged, so the page is a function
622
+ of the tree and not of which schema version a deployment happens to run.
623
+
624
+ `catalogueOf(registry)` projects the registry into plain data. Give it to
625
+ `modelInterpreter({ …, catalogue })` and the model is told what it may build
626
+ instead of guessing at type names.
627
+
628
+ `auditRegistry(registry)` probes every primitive for the edit-mode contract and
629
+ reports which ones would be invisible to the portal. It is a function a host runs
630
+ in a test or a build step — registration itself never calls a primitive.
631
+
632
+ ### Registering part of a library
633
+
634
+ A primitive library is a set to choose from, not a set every deployment ships.
635
+ `selectPrimitives` takes the entries you want and refuses a name the library does
636
+ not carry — which a `filter` would not, and a deployment that quietly lost a
637
+ primitive finds out when a page fails to draw:
638
+
639
+ ```ts
640
+ import { createPrimitiveRegistry, describeSelectionError, selectPrimitives } from "@jam-overture/loom/sdk"
641
+ import { STARTER_PRIMITIVES } from "@jam-overture/loom/primitives"
642
+
643
+ const chosen = selectPrimitives(STARTER_PRIMITIVES, ["loom.page", "loom.section", "loom.prose"])
644
+ if (!chosen.ok) throw new Error(describeSelectionError(chosen.error))
645
+
646
+ const registry = createPrimitiveRegistry(chosen.value)
647
+ ```
648
+
649
+ Why it is worth choosing: every registered primitive is a line in every
650
+ interpretation request. `measureCatalogue(catalogueOf(registry))` says what a
651
+ vocabulary costs, whole and per entry, measured from the block that is actually
652
+ sent — so *what did registering more cost* is a number rather than a feeling
653
+ ([0170](decisions/0170-a-library-is-a-set-to-choose-from-and-a-vocabulary-is-priced-per-entry.md)).
654
+ There is no ceiling on how much a deployment may register, deliberately: how much
655
+ attention a model should spend on a vocabulary depends on the model and on the
656
+ latency you will accept, and both are yours.
657
+
658
+ ## The starter primitives
659
+
660
+ > **Not in the published package.** `@jam-overture/loom/primitives` is a subpath of
661
+ > this workspace only. Installing `@jam-overture/loom` from the registry gets you the
662
+ > framework and none of what follows in this section; the starter library ships
663
+ > separately (0194). This is written for somebody working in this repository.
664
+
665
+ A deployment does not have to start from an empty registry. `@jam-overture/loom/primitives`
666
+ ships ten, ported from the Hermes predecessor and chosen to cover the primitive
667
+ contract rather than the catalogue:
668
+
669
+ ```ts
670
+ import { createStarterPrimitiveRegistry } from "@jam-overture/loom/primitives"
671
+
672
+ const registry = createStarterPrimitiveRegistry([myOwnPrimitive]) // Result, like any other
673
+ ```
674
+
675
+ | | | |
676
+ | --- | --- | --- |
677
+ | `loom.page` | root, composes | Mounts the theme; one column, at a chosen measure |
678
+ | `loom.section` | composes, slot `heading` | A band of the page, with its heading placed above the content |
679
+ | `loom.split` | composes, slots `start` `end` | Two regions side by side, wrapping to one column with no media query |
680
+ | `loom.stat-grid` | composes | A responsive grid of `loom.stat` children |
681
+ | `loom.stat` | leaf | One figure, its label, and an optional caption |
682
+ | `loom.heading` | leaf | `level` sets both the outline and the size; the text is child nodes |
683
+ | `loom.prose` | leaf | A paragraph; the text is child nodes |
684
+ | `loom.divider` | leaf | Three genuinely different renderings, selected by one enum |
685
+ | `loom.media` | leaf | An image; alt text required unless it says it is decorative |
686
+ | `loom.action` | leaf | A call to action; its destination is scheme-checked |
687
+
688
+ Every one of them reads colour, type and spacing through `var(--loom-*)` and
689
+ hard-codes none of it, which is what makes a re-theme one `configure` on the
690
+ root. That is enforced by a test: the whole sample page is rendered under both
691
+ starter palettes, and the markup below the root has to be byte-identical and to
692
+ contain no literal colour.
693
+
694
+ Two rules govern the port, and the remaining sixty follow them:
695
+
696
+ - **A repeated item is a child node; a fixed field is a prop**
697
+ ([0052](decisions/0052-a-repeated-item-is-a-node-and-a-fixed-field-is-a-prop.md)).
698
+ Hermes held a stat list in an array field; here the grid is a primitive and
699
+ each stat is a node, so adding one is an `insert` the Gate weighs, the log
700
+ attributes and the inverse removes.
701
+ - **A URL is checked against a scheme allowlist, never merely parsed**
702
+ ([0053](decisions/0053-a-url-in-the-tree-is-checked-against-a-scheme-allowlist.md)).
703
+ `z.string().url()` accepts `javascript:alert(1)`, and props in a Loom tree are
704
+ AI-authored.
705
+
706
+ ## Scaffolding
707
+
708
+ ```
709
+ loom init [--dir <directory>]
710
+ loom add primitive <type> [--dir <directory>]
711
+ ```
712
+
713
+ `init` writes a starter primitive, a generated registry, and a conformance test
714
+ that runs `auditRegistry` — so the check exists from the first commit rather than
715
+ being something to remember later. `add primitive` declares one more and
716
+ regenerates the registry from the directory's contents.
717
+
718
+ A primitive's module is named after its type verbatim (`commerce.product-card.ts`)
719
+ because that is what lets the registry be regenerated exactly; the registry is a
720
+ generated file and says so. Both are argued in
721
+ [0015](decisions/0015-the-registry-is-generated-and-a-filename-is-a-type.md).
722
+
723
+ Nothing is written unless the whole command can complete: a clash with an existing
724
+ file is reported before the first write, so a refused command leaves the directory
725
+ as it was.
726
+
727
+ ```bash
728
+ pnpm loom init
729
+ pnpm loom add primitive commerce.product-card
730
+ ```
731
+
732
+ `bin` points at `src/cli/main.ts`, which runs through `tsx` — this package has no
733
+ build step, and Node's own type stripping does not resolve the `.js` import
734
+ specifiers the repo uses to their `.ts` sources. That makes `tsx` a dependency of
735
+ the executable rather than a convenience. When a build step exists, `bin` should
736
+ point at the emitted entry and the shebang should go.
737
+
738
+ The CLI is usable as library code too: `runCli(argv, nodeFileSystem)` from
739
+ `@jam-overture/loom/cli`, which is what its tests drive.
740
+
741
+ ## Daily reports
742
+
743
+ Each session's report and its diagram live in [`reports/`](reports/).