@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.
- package/LICENSE +21 -0
- package/README.md +743 -0
- package/dist/catalogue.d.ts +70 -0
- package/dist/catalogue.js +88 -0
- package/dist/cli/args.d.ts +17 -0
- package/dist/cli/args.js +83 -0
- package/dist/cli/filesystem.d.ts +15 -0
- package/dist/cli/filesystem.js +31 -0
- package/dist/cli/index.d.ts +12 -0
- package/dist/cli/index.js +12 -0
- package/dist/cli/main.d.ts +3 -0
- package/dist/cli/main.js +30 -0
- package/dist/cli/namespace.d.ts +40 -0
- package/dist/cli/namespace.js +40 -0
- package/dist/cli/plan.d.ts +84 -0
- package/dist/cli/plan.js +113 -0
- package/dist/cli/run.d.ts +17 -0
- package/dist/cli/run.js +75 -0
- package/dist/cli/templates.d.ts +43 -0
- package/dist/cli/templates.js +134 -0
- package/dist/closed-set.d.ts +34 -0
- package/dist/closed-set.js +34 -0
- package/dist/data/adapter.d.ts +123 -0
- package/dist/data/adapter.js +91 -0
- package/dist/data/binding.d.ts +48 -0
- package/dist/data/binding.js +39 -0
- package/dist/data/catalogue.d.ts +26 -0
- package/dist/data/catalogue.js +6 -0
- package/dist/data/index.d.ts +14 -0
- package/dist/data/index.js +14 -0
- package/dist/data/plan.d.ts +58 -0
- package/dist/data/plan.js +0 -0
- package/dist/data/resolution.d.ts +91 -0
- package/dist/data/resolution.js +96 -0
- package/dist/data/resolve.d.ts +46 -0
- package/dist/data/resolve.js +37 -0
- package/dist/data/source.d.ts +40 -0
- package/dist/data/source.js +45 -0
- package/dist/deadline.d.ts +57 -0
- package/dist/deadline.js +78 -0
- package/dist/frame/catalogue.d.ts +24 -0
- package/dist/frame/catalogue.js +5 -0
- package/dist/frame/index.d.ts +12 -0
- package/dist/frame/index.js +12 -0
- package/dist/frame/origin.d.ts +87 -0
- package/dist/frame/origin.js +114 -0
- package/dist/frame/resolution.d.ts +85 -0
- package/dist/frame/resolution.js +79 -0
- package/dist/grammar.d.ts +26 -0
- package/dist/grammar.js +28 -0
- package/dist/ids.d.ts +57 -0
- package/dist/ids.js +104 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.js +26 -0
- package/dist/interactivity.d.ts +50 -0
- package/dist/interactivity.js +22 -0
- package/dist/interpretation/anthropic.d.ts +22 -0
- package/dist/interpretation/anthropic.js +76 -0
- package/dist/interpretation/client.d.ts +83 -0
- package/dist/interpretation/client.js +2 -0
- package/dist/interpretation/draft.d.ts +234 -0
- package/dist/interpretation/draft.js +84 -0
- package/dist/interpretation/index.d.ts +15 -0
- package/dist/interpretation/index.js +15 -0
- package/dist/interpretation/interpreter.d.ts +62 -0
- package/dist/interpretation/interpreter.js +151 -0
- package/dist/interpretation/materialize.d.ts +42 -0
- package/dist/interpretation/materialize.js +107 -0
- package/dist/interpretation/prompt.d.ts +229 -0
- package/dist/interpretation/prompt.js +285 -0
- package/dist/interpretation/render.d.ts +76 -0
- package/dist/interpretation/render.js +272 -0
- package/dist/interpretation/schema.d.ts +49 -0
- package/dist/interpretation/schema.js +131 -0
- package/dist/json.d.ts +35 -0
- package/dist/json.js +11 -0
- package/dist/paging.d.ts +60 -0
- package/dist/paging.js +49 -0
- package/dist/primitive-type.d.ts +32 -0
- package/dist/primitive-type.js +39 -0
- package/dist/render/addressing.d.ts +59 -0
- package/dist/render/addressing.js +60 -0
- package/dist/render/anchor.d.ts +105 -0
- package/dist/render/anchor.js +84 -0
- package/dist/render/behaviour-adjust.d.ts +62 -0
- package/dist/render/behaviour-adjust.js +78 -0
- package/dist/render/behaviour-copy.d.ts +53 -0
- package/dist/render/behaviour-copy.js +75 -0
- package/dist/render/behaviour-disclose.d.ts +74 -0
- package/dist/render/behaviour-disclose.js +77 -0
- package/dist/render/behaviour-present.d.ts +123 -0
- package/dist/render/behaviour-present.js +173 -0
- package/dist/render/behaviour.d.ts +243 -0
- package/dist/render/behaviour.js +284 -0
- package/dist/render/control.d.ts +81 -0
- package/dist/render/control.js +80 -0
- package/dist/render/decorative.d.ts +62 -0
- package/dist/render/decorative.js +2 -0
- package/dist/render/diagnostics.d.ts +260 -0
- package/dist/render/diagnostics.js +61 -0
- package/dist/render/disclosed.d.ts +37 -0
- package/dist/render/disclosed.js +37 -0
- package/dist/render/editable.d.ts +34 -0
- package/dist/render/editable.js +35 -0
- package/dist/render/frame.d.ts +42 -0
- package/dist/render/frame.js +31 -0
- package/dist/render/index.d.ts +35 -0
- package/dist/render/index.js +35 -0
- package/dist/render/inline-variables.d.ts +77 -0
- package/dist/render/inline-variables.js +220 -0
- package/dist/render/presented.d.ts +82 -0
- package/dist/render/presented.js +82 -0
- package/dist/render/primitive.d.ts +228 -0
- package/dist/render/primitive.js +36 -0
- package/dist/render/props.d.ts +48 -0
- package/dist/render/props.js +2 -0
- package/dist/render/reads.d.ts +73 -0
- package/dist/render/reads.js +45 -0
- package/dist/render/render.d.ts +164 -0
- package/dist/render/render.js +571 -0
- package/dist/render/request.d.ts +111 -0
- package/dist/render/request.js +60 -0
- package/dist/render/text.d.ts +91 -0
- package/dist/render/text.js +44 -0
- package/dist/render/theme.d.ts +61 -0
- package/dist/render/theme.js +52 -0
- package/dist/reserved-props.d.ts +35 -0
- package/dist/reserved-props.js +45 -0
- package/dist/result.d.ts +27 -0
- package/dist/result.js +30 -0
- package/dist/role.d.ts +71 -0
- package/dist/role.js +22 -0
- package/dist/runtime/analysis.d.ts +149 -0
- package/dist/runtime/analysis.js +187 -0
- package/dist/runtime/assessment.d.ts +35 -0
- package/dist/runtime/assessment.js +13 -0
- package/dist/runtime/disposition.d.ts +102 -0
- package/dist/runtime/disposition.js +59 -0
- package/dist/runtime/events.d.ts +187 -0
- package/dist/runtime/events.js +7 -0
- package/dist/runtime/gate.d.ts +43 -0
- package/dist/runtime/gate.js +169 -0
- package/dist/runtime/index.d.ts +27 -0
- package/dist/runtime/index.js +27 -0
- package/dist/runtime/intent.d.ts +60 -0
- package/dist/runtime/intent.js +36 -0
- package/dist/runtime/interpreter.d.ts +117 -0
- package/dist/runtime/interpreter.js +46 -0
- package/dist/runtime/inverse-interpreter.d.ts +90 -0
- package/dist/runtime/inverse-interpreter.js +56 -0
- package/dist/runtime/inverse.d.ts +87 -0
- package/dist/runtime/inverse.js +48 -0
- package/dist/runtime/narration.d.ts +24 -0
- package/dist/runtime/narration.js +36 -0
- package/dist/runtime/nesting.d.ts +31 -0
- package/dist/runtime/nesting.js +46 -0
- package/dist/runtime/pipeline.d.ts +124 -0
- package/dist/runtime/pipeline.js +178 -0
- package/dist/runtime/policy-fingerprint.d.ts +29 -0
- package/dist/runtime/policy-fingerprint.js +119 -0
- package/dist/runtime/policy-source.d.ts +42 -0
- package/dist/runtime/policy-source.js +8 -0
- package/dist/runtime/policy.d.ts +156 -0
- package/dist/runtime/policy.js +107 -0
- package/dist/runtime/proposal.d.ts +423 -0
- package/dist/runtime/proposal.js +109 -0
- package/dist/runtime/redirection.d.ts +53 -0
- package/dist/runtime/redirection.js +38 -0
- package/dist/runtime/repointing.d.ts +71 -0
- package/dist/runtime/repointing.js +0 -0
- package/dist/runtime/reversibility.d.ts +36 -0
- package/dist/runtime/reversibility.js +39 -0
- package/dist/runtime/stake-level.d.ts +33 -0
- package/dist/runtime/stake-level.js +58 -0
- package/dist/runtime/stakes.d.ts +47 -0
- package/dist/runtime/stakes.js +305 -0
- package/dist/runtime/vocabulary.d.ts +122 -0
- package/dist/runtime/vocabulary.js +87 -0
- package/dist/sdk/audit.d.ts +195 -0
- package/dist/sdk/audit.js +128 -0
- package/dist/sdk/catalogue.d.ts +37 -0
- package/dist/sdk/catalogue.js +16 -0
- package/dist/sdk/conformance.d.ts +342 -0
- package/dist/sdk/conformance.js +494 -0
- package/dist/sdk/copy.d.ts +105 -0
- package/dist/sdk/copy.js +90 -0
- package/dist/sdk/definition.d.ts +242 -0
- package/dist/sdk/definition.js +64 -0
- package/dist/sdk/index.d.ts +19 -0
- package/dist/sdk/index.js +19 -0
- package/dist/sdk/interactivity.d.ts +29 -0
- package/dist/sdk/interactivity.js +34 -0
- package/dist/sdk/pairings.d.ts +124 -0
- package/dist/sdk/pairings.js +81 -0
- package/dist/sdk/registry.d.ts +162 -0
- package/dist/sdk/registry.js +329 -0
- package/dist/sdk/selection.d.ts +46 -0
- package/dist/sdk/selection.js +24 -0
- package/dist/sdk/text.d.ts +100 -0
- package/dist/sdk/text.js +105 -0
- package/dist/sdk/vocabulary.d.ts +39 -0
- package/dist/sdk/vocabulary.js +36 -0
- package/dist/signals/broadcast.d.ts +134 -0
- package/dist/signals/broadcast.js +451 -0
- package/dist/signals/collect.d.ts +184 -0
- package/dist/signals/collect.js +196 -0
- package/dist/signals/deliver.d.ts +64 -0
- package/dist/signals/deliver.js +85 -0
- package/dist/signals/fold.d.ts +112 -0
- package/dist/signals/fold.js +76 -0
- package/dist/signals/index.d.ts +31 -0
- package/dist/signals/index.js +31 -0
- package/dist/signals/ingest.d.ts +51 -0
- package/dist/signals/ingest.js +70 -0
- package/dist/signals/intake.d.ts +149 -0
- package/dist/signals/intake.js +154 -0
- package/dist/signals/journal.d.ts +94 -0
- package/dist/signals/journal.js +11 -0
- package/dist/signals/kinds.d.ts +22 -0
- package/dist/signals/kinds.js +22 -0
- package/dist/signals/ledger.d.ts +46 -0
- package/dist/signals/ledger.js +81 -0
- package/dist/signals/memory.d.ts +17 -0
- package/dist/signals/memory.js +99 -0
- package/dist/signals/migrate.d.ts +27 -0
- package/dist/signals/migrate.js +78 -0
- package/dist/signals/postgres.d.ts +7 -0
- package/dist/signals/postgres.js +295 -0
- package/dist/signals/rollup.d.ts +142 -0
- package/dist/signals/rollup.js +0 -0
- package/dist/signals/schema.d.ts +534 -0
- package/dist/signals/schema.js +92 -0
- package/dist/signals/signal.d.ts +381 -0
- package/dist/signals/signal.js +150 -0
- package/dist/signals/tally.d.ts +70 -0
- package/dist/signals/tally.js +2 -0
- package/dist/signals/view.d.ts +51 -0
- package/dist/signals/view.js +54 -0
- package/dist/store/attribution.d.ts +125 -0
- package/dist/store/attribution.js +116 -0
- package/dist/store/database.d.ts +14 -0
- package/dist/store/database.js +2 -0
- package/dist/store/driver.d.ts +29 -0
- package/dist/store/driver.js +39 -0
- package/dist/store/errors.d.ts +56 -0
- package/dist/store/errors.js +37 -0
- package/dist/store/index.d.ts +16 -0
- package/dist/store/index.js +16 -0
- package/dist/store/memory.d.ts +3 -0
- package/dist/store/memory.js +115 -0
- package/dist/store/migrate.d.ts +54 -0
- package/dist/store/migrate.js +122 -0
- package/dist/store/postgres-holds.d.ts +4 -0
- package/dist/store/postgres-holds.js +192 -0
- package/dist/store/postgres.d.ts +8 -0
- package/dist/store/postgres.js +262 -0
- package/dist/store/replay.d.ts +94 -0
- package/dist/store/replay.js +82 -0
- package/dist/store/revert.d.ts +116 -0
- package/dist/store/revert.js +243 -0
- package/dist/store/schema.d.ts +371 -0
- package/dist/store/schema.js +78 -0
- package/dist/store/source.d.ts +23 -0
- package/dist/store/source.js +37 -0
- package/dist/store/store.d.ts +231 -0
- package/dist/store/store.js +52 -0
- package/dist/store/undone.d.ts +18 -0
- package/dist/store/undone.js +89 -0
- package/dist/submit/catalogue.d.ts +20 -0
- package/dist/submit/catalogue.js +5 -0
- package/dist/submit/declaration.d.ts +39 -0
- package/dist/submit/declaration.js +30 -0
- package/dist/submit/endpoint.d.ts +131 -0
- package/dist/submit/endpoint.js +160 -0
- package/dist/submit/index.d.ts +13 -0
- package/dist/submit/index.js +13 -0
- package/dist/submit/plan.d.ts +49 -0
- package/dist/submit/plan.js +47 -0
- package/dist/submit/resolution.d.ts +61 -0
- package/dist/submit/resolution.js +64 -0
- package/dist/submit/resolve.d.ts +45 -0
- package/dist/submit/resolve.js +36 -0
- package/dist/telemetry/calibration.d.ts +132 -0
- package/dist/telemetry/calibration.js +151 -0
- package/dist/telemetry/episode.d.ts +140 -0
- package/dist/telemetry/episode.js +272 -0
- package/dist/telemetry/event.d.ts +2310 -0
- package/dist/telemetry/event.js +405 -0
- package/dist/telemetry/index.d.ts +15 -0
- package/dist/telemetry/index.js +15 -0
- package/dist/telemetry/journal.d.ts +116 -0
- package/dist/telemetry/journal.js +11 -0
- package/dist/telemetry/memory.d.ts +24 -0
- package/dist/telemetry/memory.js +75 -0
- package/dist/telemetry/migrate.d.ts +26 -0
- package/dist/telemetry/migrate.js +40 -0
- package/dist/telemetry/postgres.d.ts +6 -0
- package/dist/telemetry/postgres.js +139 -0
- package/dist/telemetry/retention.d.ts +131 -0
- package/dist/telemetry/retention.js +217 -0
- package/dist/telemetry/schema.d.ts +113 -0
- package/dist/telemetry/schema.js +33 -0
- package/dist/telemetry/sink.d.ts +42 -0
- package/dist/telemetry/sink.js +61 -0
- package/dist/testing/contracts.d.ts +34 -0
- package/dist/testing/contracts.js +34 -0
- package/dist/testing/definitions.d.ts +15 -0
- package/dist/testing/definitions.js +48 -0
- package/dist/testing/doubles.d.ts +94 -0
- package/dist/testing/doubles.js +141 -0
- package/dist/testing/episode-harness.d.ts +49 -0
- package/dist/testing/episode-harness.js +65 -0
- package/dist/testing/filesystem.d.ts +17 -0
- package/dist/testing/filesystem.js +17 -0
- package/dist/testing/fixtures.d.ts +57 -0
- package/dist/testing/fixtures.js +84 -0
- package/dist/testing/hold-contract.d.ts +19 -0
- package/dist/testing/hold-contract.js +374 -0
- package/dist/testing/index.d.ts +41 -0
- package/dist/testing/index.js +41 -0
- package/dist/testing/journal-contract.d.ts +17 -0
- package/dist/testing/journal-contract.js +353 -0
- package/dist/testing/model-replies.d.ts +34 -0
- package/dist/testing/model-replies.js +101 -0
- package/dist/testing/primitives.d.ts +7 -0
- package/dist/testing/primitives.js +29 -0
- package/dist/testing/reader-signal-contract.d.ts +38 -0
- package/dist/testing/reader-signal-contract.js +318 -0
- package/dist/testing/row-security.d.ts +17 -0
- package/dist/testing/row-security.js +21 -0
- package/dist/testing/store-contract.d.ts +25 -0
- package/dist/testing/store-contract.js +500 -0
- package/dist/theme/apply.d.ts +17 -0
- package/dist/theme/apply.js +60 -0
- package/dist/theme/contrast.d.ts +197 -0
- package/dist/theme/contrast.js +259 -0
- package/dist/theme/derive.d.ts +77 -0
- package/dist/theme/derive.js +167 -0
- package/dist/theme/faces.d.ts +73 -0
- package/dist/theme/faces.js +119 -0
- package/dist/theme/font-packs.d.ts +25 -0
- package/dist/theme/font-packs.js +257 -0
- package/dist/theme/index.d.ts +20 -0
- package/dist/theme/index.js +20 -0
- package/dist/theme/lab.d.ts +30 -0
- package/dist/theme/lab.js +46 -0
- package/dist/theme/library.d.ts +114 -0
- package/dist/theme/library.js +300 -0
- package/dist/theme/measure.d.ts +144 -0
- package/dist/theme/measure.js +145 -0
- package/dist/theme/palettes.d.ts +64 -0
- package/dist/theme/palettes.js +497 -0
- package/dist/theme/registry.d.ts +59 -0
- package/dist/theme/registry.js +60 -0
- package/dist/theme/separation.d.ts +177 -0
- package/dist/theme/separation.js +203 -0
- package/dist/theme/style-presets.d.ts +60 -0
- package/dist/theme/style-presets.js +124 -0
- package/dist/theme/theme.d.ts +253 -0
- package/dist/theme/theme.js +171 -0
- package/dist/tree/apply.d.ts +16 -0
- package/dist/tree/apply.js +104 -0
- package/dist/tree/builders.d.ts +19 -0
- package/dist/tree/builders.js +20 -0
- package/dist/tree/compare.d.ts +68 -0
- package/dist/tree/compare.js +75 -0
- package/dist/tree/configuration.d.ts +25 -0
- package/dist/tree/configuration.js +108 -0
- package/dist/tree/delta.d.ts +288 -0
- package/dist/tree/delta.js +88 -0
- package/dist/tree/errors.d.ts +69 -0
- package/dist/tree/errors.js +34 -0
- package/dist/tree/identity.d.ts +117 -0
- package/dist/tree/identity.js +145 -0
- package/dist/tree/index.d.ts +21 -0
- package/dist/tree/index.js +21 -0
- package/dist/tree/inverse.d.ts +24 -0
- package/dist/tree/inverse.js +112 -0
- package/dist/tree/mutation.d.ts +18 -0
- package/dist/tree/mutation.js +49 -0
- package/dist/tree/naming.d.ts +4 -0
- package/dist/tree/naming.js +35 -0
- package/dist/tree/navigation.d.ts +38 -0
- package/dist/tree/navigation.js +83 -0
- package/dist/tree/node.d.ts +103 -0
- package/dist/tree/node.js +46 -0
- package/dist/tree/outline.d.ts +28 -0
- package/dist/tree/outline.js +10 -0
- package/dist/tree/tree.d.ts +83 -0
- package/dist/tree/tree.js +62 -0
- package/dist/write/commit.d.ts +124 -0
- package/dist/write/commit.js +234 -0
- package/dist/write/held.d.ts +674 -0
- package/dist/write/held.js +185 -0
- package/dist/write/index.d.ts +11 -0
- package/dist/write/index.js +11 -0
- package/dist/write/liveness.d.ts +132 -0
- package/dist/write/liveness.js +91 -0
- package/dist/write/revert.d.ts +79 -0
- package/dist/write/revert.js +134 -0
- 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/).
|