@jam-overture/loom 0.2.0 → 0.3.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 (194) hide show
  1. package/dist/audience/compose.d.ts +112 -0
  2. package/dist/audience/compose.js +134 -0
  3. package/dist/audience/memory.d.ts +14 -0
  4. package/dist/audience/memory.js +71 -0
  5. package/dist/audience/overlay-store.d.ts +343 -0
  6. package/dist/audience/overlay-store.js +217 -0
  7. package/dist/audience/rule.d.ts +121 -0
  8. package/dist/audience/rule.js +78 -0
  9. package/dist/cli/index.d.ts +3 -4
  10. package/dist/cli/index.js +3 -4
  11. package/dist/data/adapter.d.ts +9 -1
  12. package/dist/data/adapter.js +2 -0
  13. package/dist/data/resolve.d.ts +1 -1
  14. package/dist/interpretation/anthropic.d.ts +1 -1
  15. package/dist/interpretation/anthropic.js +2 -22
  16. package/dist/interpretation/client.d.ts +1 -1
  17. package/dist/interpretation/materialize.js +67 -22
  18. package/dist/interpretation/openai-compatible.d.ts +36 -0
  19. package/dist/interpretation/openai-compatible.js +79 -0
  20. package/dist/interpretation/status.d.ts +19 -0
  21. package/dist/interpretation/status.js +26 -0
  22. package/dist/live/index.d.ts +73 -0
  23. package/dist/live/index.js +73 -0
  24. package/dist/live/pages.d.ts +187 -0
  25. package/dist/live/pages.js +161 -0
  26. package/dist/live/pull.d.ts +147 -0
  27. package/dist/live/pull.js +398 -0
  28. package/dist/live/pulling.d.ts +79 -0
  29. package/dist/live/pulling.js +117 -0
  30. package/dist/live/window.d.ts +129 -0
  31. package/dist/live/window.js +132 -0
  32. package/dist/render/addressed.d.ts +35 -0
  33. package/dist/render/addressed.js +79 -0
  34. package/dist/render/document-theme.d.ts +70 -0
  35. package/dist/render/document-theme.js +139 -0
  36. package/dist/render/editable.d.ts +15 -1
  37. package/dist/render/editable.js +13 -1
  38. package/dist/render/expected.d.ts +98 -0
  39. package/dist/render/expected.js +88 -0
  40. package/dist/render/index.d.ts +2 -0
  41. package/dist/render/index.js +2 -0
  42. package/dist/render/render.d.ts +11 -0
  43. package/dist/render/render.js +192 -46
  44. package/dist/render/request.d.ts +8 -1
  45. package/dist/render/request.js +1 -0
  46. package/dist/runtime/auto-apply-ceiling.d.ts +54 -0
  47. package/dist/runtime/auto-apply-ceiling.js +66 -0
  48. package/dist/runtime/gate.js +69 -10
  49. package/dist/runtime/index.d.ts +1 -0
  50. package/dist/runtime/index.js +1 -0
  51. package/dist/runtime/nesting.d.ts +13 -1
  52. package/dist/runtime/nesting.js +41 -24
  53. package/dist/runtime/policy-change.js +8 -2
  54. package/dist/runtime/policy-log.d.ts +5 -5
  55. package/dist/runtime/policy.d.ts +8 -6
  56. package/dist/runtime/policy.js +5 -2
  57. package/dist/runtime/repointing.js +0 -0
  58. package/dist/sdk/definition.d.ts +65 -6
  59. package/dist/sdk/definition.js +44 -0
  60. package/dist/sdk/registry.d.ts +17 -1
  61. package/dist/sdk/registry.js +39 -0
  62. package/dist/signals/acted.contract.d.ts +21 -0
  63. package/dist/signals/acted.contract.js +236 -0
  64. package/dist/signals/acted.d.ts +359 -0
  65. package/dist/signals/acted.js +135 -0
  66. package/dist/signals/agenda.d.ts +585 -0
  67. package/dist/signals/agenda.js +295 -0
  68. package/dist/signals/arrivals.contract.d.ts +21 -0
  69. package/dist/signals/arrivals.contract.js +180 -0
  70. package/dist/signals/arrivals.d.ts +375 -0
  71. package/dist/signals/arrivals.js +254 -0
  72. package/dist/signals/broadcast.d.ts +25 -15
  73. package/dist/signals/broadcast.js +209 -36
  74. package/dist/signals/collect.d.ts +137 -43
  75. package/dist/signals/collect.js +103 -36
  76. package/dist/signals/conversion.d.ts +348 -0
  77. package/dist/signals/conversion.js +235 -0
  78. package/dist/signals/correlated.contract.d.ts +24 -0
  79. package/dist/signals/correlated.contract.js +94 -0
  80. package/dist/signals/counters.d.ts +51 -0
  81. package/dist/signals/counters.js +58 -0
  82. package/dist/signals/deployment-change.d.ts +28 -4
  83. package/dist/signals/deployment-change.js +57 -16
  84. package/dist/signals/deployment.d.ts +18 -5
  85. package/dist/signals/deployment.js +37 -11
  86. package/dist/signals/door.d.ts +34 -12
  87. package/dist/signals/door.js +37 -13
  88. package/dist/signals/expire.d.ts +192 -0
  89. package/dist/signals/expire.js +213 -0
  90. package/dist/signals/frontier.d.ts +268 -0
  91. package/dist/signals/frontier.js +145 -0
  92. package/dist/signals/funnel-hours.contract.d.ts +21 -0
  93. package/dist/signals/funnel-hours.contract.js +221 -0
  94. package/dist/signals/funnel-hours.d.ts +293 -0
  95. package/dist/signals/funnel-hours.js +99 -0
  96. package/dist/signals/funnel.d.ts +60 -0
  97. package/dist/signals/funnel.js +35 -20
  98. package/dist/signals/health.d.ts +201 -4
  99. package/dist/signals/health.js +214 -2
  100. package/dist/signals/index.d.ts +19 -0
  101. package/dist/signals/index.js +19 -0
  102. package/dist/signals/inside.d.ts +190 -0
  103. package/dist/signals/inside.js +263 -0
  104. package/dist/signals/join.d.ts +56 -0
  105. package/dist/signals/join.js +60 -0
  106. package/dist/signals/journal.d.ts +112 -9
  107. package/dist/signals/kept.contract.d.ts +22 -0
  108. package/dist/signals/kept.contract.js +111 -0
  109. package/dist/signals/library-agenda-change.d.ts +324 -0
  110. package/dist/signals/library-agenda-change.js +199 -0
  111. package/dist/signals/library-agenda.d.ts +258 -0
  112. package/dist/signals/library-agenda.js +167 -0
  113. package/dist/signals/library-reach-change.d.ts +10 -0
  114. package/dist/signals/library-reach-change.js +11 -3
  115. package/dist/signals/library-senders-change.d.ts +457 -0
  116. package/dist/signals/library-senders-change.js +367 -0
  117. package/dist/signals/library-senders-reach-change.d.ts +486 -0
  118. package/dist/signals/library-senders-reach-change.js +538 -0
  119. package/dist/signals/library-senders-reach.d.ts +340 -0
  120. package/dist/signals/library-senders-reach.js +252 -0
  121. package/dist/signals/library-senders.d.ts +271 -0
  122. package/dist/signals/library-senders.js +180 -0
  123. package/dist/signals/library-word-reach-change.js +2 -6
  124. package/dist/signals/memory.js +142 -1
  125. package/dist/signals/migrate.d.ts +6 -5
  126. package/dist/signals/migrate.js +150 -6
  127. package/dist/signals/notice.d.ts +88 -33
  128. package/dist/signals/notice.js +38 -16
  129. package/dist/signals/part-pace.d.ts +378 -0
  130. package/dist/signals/part-pace.js +333 -0
  131. package/dist/signals/parts.d.ts +25 -15
  132. package/dist/signals/parts.js +32 -73
  133. package/dist/signals/postgres.js +400 -26
  134. package/dist/signals/region.d.ts +1 -1
  135. package/dist/signals/retention.d.ts +43 -21
  136. package/dist/signals/retention.js +25 -8
  137. package/dist/signals/rhythm.d.ts +302 -0
  138. package/dist/signals/rhythm.js +262 -0
  139. package/dist/signals/rollup.d.ts +127 -1
  140. package/dist/signals/rollup.js +211 -24
  141. package/dist/signals/schema.d.ts +640 -3
  142. package/dist/signals/schema.js +239 -3
  143. package/dist/signals/silences.d.ts +310 -11
  144. package/dist/signals/silences.js +243 -0
  145. package/dist/signals/subtrees.d.ts +123 -0
  146. package/dist/signals/subtrees.js +102 -0
  147. package/dist/signals/tally.d.ts +125 -4
  148. package/dist/signals/unread.d.ts +292 -0
  149. package/dist/signals/unread.js +137 -0
  150. package/dist/signals/window-agenda.d.ts +276 -0
  151. package/dist/signals/window-agenda.js +83 -0
  152. package/dist/signals/window-funnels.d.ts +88 -0
  153. package/dist/signals/window-funnels.js +47 -0
  154. package/dist/store/cache.d.ts +101 -0
  155. package/dist/store/cache.js +149 -0
  156. package/dist/store/history.d.ts +82 -0
  157. package/dist/store/history.js +36 -0
  158. package/dist/store/index.d.ts +11 -0
  159. package/dist/store/index.js +11 -0
  160. package/dist/store/migrate.d.ts +26 -0
  161. package/dist/store/migrate.js +64 -0
  162. package/dist/store/postgres-audience.d.ts +14 -0
  163. package/dist/store/postgres-audience.js +272 -0
  164. package/dist/store/postgres.d.ts +1 -0
  165. package/dist/store/postgres.js +1 -0
  166. package/dist/store/schema.d.ts +312 -0
  167. package/dist/store/schema.js +77 -0
  168. package/dist/store/source.d.ts +57 -1
  169. package/dist/store/source.js +65 -1
  170. package/dist/submit/resolve.d.ts +1 -1
  171. package/dist/telemetry/index.d.ts +1 -0
  172. package/dist/telemetry/index.js +1 -0
  173. package/dist/telemetry/journal.d.ts +32 -0
  174. package/dist/telemetry/memory.js +10 -1
  175. package/dist/telemetry/postgres.js +18 -2
  176. package/dist/telemetry/window.d.ts +135 -0
  177. package/dist/telemetry/window.js +101 -0
  178. package/dist/testing/audience-overlay-contract.d.ts +31 -0
  179. package/dist/testing/audience-overlay-contract.js +354 -0
  180. package/dist/testing/contracts.d.ts +1 -0
  181. package/dist/testing/contracts.js +1 -0
  182. package/dist/testing/journal-contract.js +158 -5
  183. package/dist/theme/contrast.d.ts +19 -14
  184. package/dist/theme/contrast.js +181 -17
  185. package/dist/tree/apply.js +13 -0
  186. package/dist/tree/mutation.d.ts +18 -0
  187. package/dist/tree/mutation.js +24 -12
  188. package/dist/tree/navigation.d.ts +5 -0
  189. package/dist/tree/navigation.js +32 -10
  190. package/dist/tree/outline.d.ts +7 -0
  191. package/dist/tree/outline.js +9 -5
  192. package/package.json +39 -96
  193. package/dist/runtime/inverse-interpreter.d.ts +0 -90
  194. package/dist/runtime/inverse-interpreter.js +0 -56
@@ -0,0 +1,139 @@
1
+ import { themeGround, themeStyle } from "./theme.js";
2
+ /**
3
+ * Mounting a theme on the **document element** rather than on a tree.
4
+ *
5
+ * ## The boundary a tree has, and what is outside it
6
+ *
7
+ * A root primitive paints `bg-canvas` across the page and mounts every
8
+ * `--loom-*` variable below it ([`themeStyle`](./theme.ts)), and for everything
9
+ * a tree contains that is the whole answer. Three things a reader sees are not
10
+ * in it: the scrollbar the browser draws beside the document, the canvas it
11
+ * paints past the end of a short page, and the rendering it gives a form
12
+ * control that nobody styled. They belong to the document, and **no tree ever
13
+ * contains the document** — the root primitive is an element inside a `<body>`
14
+ * some layout rendered.
15
+ *
16
+ * `color-scheme` is the declaration those three read, and it is inherited, so
17
+ * putting it on the tree's root reaches every primitive below it — which needed
18
+ * it least — and reaches none of them. On a dark palette that is a black page
19
+ * with a light scrollbar beside it and a white band past the end of it: the
20
+ * defect `Loom marketing` measured on `/?theme=bold` on 8 October, where the
21
+ * served document carried `color-scheme` nowhere at all.
22
+ *
23
+ * So the answer to *should the root primitive declare it* is **no**, and it is
24
+ * not a matter of taste: the root primitive cannot reach the surface the
25
+ * declaration is for. A host is handed the rule for its own `<html>` instead,
26
+ * which is the same bargain [`themeGround`](./theme.ts) already makes for a
27
+ * host's own frame — the parts of a page Loom does not draw are answered by
28
+ * giving the host the palette's answer, never by guessing in a stylesheet.
29
+ *
30
+ * ## Why a CSS rule and not a style object
31
+ *
32
+ * A style object is how a *surface* mounts a theme, because there the root
33
+ * primitive is an element inside a document its layout already rendered. The
34
+ * document element is not an element any page may render: a page that renders
35
+ * its own `<html>` gets it **nested inside the real one**, and the variables
36
+ * reach the page only through the HTML parser's error recovery, which merges a
37
+ * stray `<html>`'s attributes onto the real element. It happens to work, and a
38
+ * test can never see that it only happens to — React hoists a rendered
39
+ * `<html>`'s attributes onto the document element under jsdom, so a suite sees
40
+ * the outcome a browser arrives at by accident.
41
+ *
42
+ * A `:root` rule is true where it is written. It goes in a `<style>`, which
43
+ * React hoists into the head, and it needs no element of the host's own.
44
+ *
45
+ * Written by hand once before it was here, in this repository's own application
46
+ * shell, which is the second instance of the rule `themeGround`'s docblock
47
+ * states: a copy of a decision the palette owns, kept somewhere the palette
48
+ * cannot reach, is wrong the moment the palette moves and nothing anywhere can
49
+ * see that it has.
50
+ */
51
+ /**
52
+ * A style object's key as CSS spells it.
53
+ *
54
+ * Custom properties pass through: `--loom-accent` is already CSS, and lowering
55
+ * it would be a no-op that only looked safe. Everything else is a camelCased
56
+ * CSS property, and `backgroundColor: #fff` is not a declaration any browser
57
+ * applies — it is discarded by the parser, with no error anywhere, leaving an
58
+ * element that renders as though nobody had styled it.
59
+ */
60
+ const cssProperty = (key) => key.startsWith("--") ? key : key.replace(/[A-Z]/g, (capital) => `-${capital.toLowerCase()}`);
61
+ /** A declaration pair as CSS text, or nothing when the value is absent. */
62
+ const declaration = (key, value) => value === undefined ? [] : [` ${cssProperty(key)}: ${String(value)};`];
63
+ const declarations = (properties) => Object.entries(properties).flatMap(([key, value]) => declaration(key, value));
64
+ /** The declarations given, as one rule on the document element. */
65
+ const rootRule = (lines) => [":root {", ...lines, "}"].join("\n");
66
+ /**
67
+ * A resolved theme as the `:root` rule a host puts on its own document.
68
+ *
69
+ * Every variable `themeStyle` mounts, and then the ground — `background-color`,
70
+ * `color` and `color-scheme` — so one rule answers both the page's palette and
71
+ * the furniture around it. `:root` **is** the document element, which is what
72
+ * makes the ground reach the overscroll area past the end of a short page; the
73
+ * same declarations on a wrapper inside the document leave the browser's own
74
+ * white there, invisible under a light palette and not under the next one.
75
+ *
76
+ * Takes a `ResolvedTheme` rather than a `ThemeResolution`, the bargain
77
+ * `themeStyle` and `themeGround` both make: there is no fallback theme (0049),
78
+ * so *the tree names no theme* is the host's question about its own document and
79
+ * not one the runtime can answer by handing back a rule.
80
+ *
81
+ * **The ground may be absent and the rule is still returned.** A palette whose
82
+ * body-copy pair cannot be read gets no ground rather than a guessed one, and
83
+ * `ThemeGround` already documents what follows: whatever `color-scheme` the
84
+ * host's own stylesheet sets stands. The variables are unaffected by that and
85
+ * are the half a host cannot write for itself, so withholding the rule over it
86
+ * would cost a page its whole palette to avoid mis-stating one declaration of
87
+ * it. Every registered palette resolves both ends.
88
+ *
89
+ * Nothing is restated here: both halves are derived from the one resolved theme
90
+ * by the two functions a surface uses, so only the serialisation is this
91
+ * function's own and a re-theme has no second source of truth to miss.
92
+ */
93
+ export const themeDocumentCss = (theme, ramp = "fluid") => rootRule([
94
+ ...declarations(themeStyle(theme, ramp)),
95
+ ...declarations(themeGround(theme) ?? {}),
96
+ ]);
97
+ /**
98
+ * The ground alone, as the same `:root` rule — for a host whose page is already
99
+ * a tree to its edges.
100
+ *
101
+ * `themeDocumentCss` above answers a host that has no tree: the
102
+ * application shell draws its own frame, mounts nothing, and needs every
103
+ * variable as well as the ground. A *surface* is the other host, and it is not
104
+ * the same host. `(marketing)` composes a tree whose root primitive already
105
+ * mounts every `--loom-*` below it, so the variables in the document rule are
106
+ * read by nothing inside the page — they are a second copy of a mounting that
107
+ * already happened, in the one place no primitive looks. What that page actually
108
+ * needs from the document is the three declarations a tree cannot reach:
109
+ * `background-color`, `color` and `color-scheme`, on the element the scrollbar
110
+ * and the overscroll canvas belong to.
111
+ *
112
+ * `Loom marketing` measured the duplicate at 1,976 bytes on `/?theme=bold` and
113
+ * filed the shape rather than hand-writing the shorter rule, which was the right
114
+ * call twice over: a three-declaration rule written in a surface is a copy of a
115
+ * decision the palette owns, kept where the palette cannot reach it, and that is
116
+ * the hazard [`themeGround`](./theme.ts) and the docblock above both exist to
117
+ * refuse. The answer is to publish the half, not to let a caller rebuild it.
118
+ *
119
+ * **A second export rather than a flag on the first**, because the two differ in
120
+ * their inputs and not only in their output. `ramp` decides how the variables
121
+ * are written and has nothing to say about the ground, so a flag would leave a
122
+ * parameter that is read on one setting and silently ignored on the other —
123
+ * and a caller passing both would have written something that cannot be true.
124
+ * Two functions, one private serialiser, and neither has an argument it
125
+ * disregards.
126
+ *
127
+ * **`undefined` when the palette has no ground**, which mirrors `themeGround`
128
+ * exactly and for its reason: a palette whose body-copy pair cannot be read gets
129
+ * no ground rather than a guessed one. `themeDocumentCss` still returns its rule
130
+ * in that case because the variables are the half the host cannot write for
131
+ * itself and they are unaffected. Here there is no other half, so a rule would
132
+ * be an empty block — and *nothing to say* is a state a caller should have to
133
+ * answer rather than render. Every registered palette resolves both ends.
134
+ */
135
+ export const themeGroundCss = (theme) => {
136
+ const ground = themeGround(theme);
137
+ return ground === undefined ? undefined : rootRule(declarations(ground));
138
+ };
139
+ //# sourceMappingURL=document-theme.js.map
@@ -1,3 +1,4 @@
1
+ import type { AudienceId } from "../audience/audience.js";
1
2
  import type { ElementNode } from "../tree/node.js";
2
3
  import type { LoomTree } from "../tree/tree.js";
3
4
  /**
@@ -16,12 +17,15 @@ export declare const LOOM_NODE_ATTRIBUTE = "data-loom-node";
16
17
  export declare const LOOM_TYPE_ATTRIBUTE = "data-loom-type";
17
18
  export declare const LOOM_TREE_ATTRIBUTE = "data-loom-tree";
18
19
  export declare const LOOM_REVISION_ATTRIBUTE = "data-loom-revision";
20
+ export declare const LOOM_AUDIENCE_ATTRIBUTE = "data-loom-audience";
19
21
  export type EditableAttributes = {
20
22
  readonly [LOOM_NODE_ATTRIBUTE]: string;
21
23
  readonly [LOOM_TYPE_ATTRIBUTE]: string;
22
24
  /** Root element only — see `editableAttributes`. */
23
25
  readonly [LOOM_TREE_ATTRIBUTE]?: string;
24
26
  readonly [LOOM_REVISION_ATTRIBUTE]?: string;
27
+ /** Root element only, and only when the page was served to a segment. */
28
+ readonly [LOOM_AUDIENCE_ATTRIBUTE]?: string;
25
29
  };
26
30
  /**
27
31
  * The root element additionally carries the tree it belongs to and the revision
@@ -29,6 +33,16 @@ export type EditableAttributes = {
29
33
  * base. A portal can author an intent from the DOM alone, and an intent
30
34
  * authored against a stale render names the stale revision rather than
31
35
  * silently claiming the current one.
36
+ *
37
+ * It carries the segment the page was served to as well, when it was served to
38
+ * one (0284, 0371), because the browser cannot work that out for itself: the
39
+ * site's server sorted the reader, and this is how the page's signals learn
40
+ * which segment to be filed under. The renderer never hands it `aud_everyone`
41
+ * (see `RenderOptions.audience`), because a page that names no audience already
42
+ * means it.
43
+ *
44
+ * Only a type is imported for it: this file is what `addressed.ts` hands a
45
+ * reader's browser, and the id's schema would bring the schema library with it.
32
46
  */
33
- export declare const editableAttributes: (node: ElementNode, tree?: LoomTree) => EditableAttributes;
47
+ export declare const editableAttributes: (node: ElementNode, tree?: LoomTree, audience?: AudienceId) => EditableAttributes;
34
48
  //# sourceMappingURL=editable.d.ts.map
@@ -14,19 +14,31 @@ export const LOOM_NODE_ATTRIBUTE = "data-loom-node";
14
14
  export const LOOM_TYPE_ATTRIBUTE = "data-loom-type";
15
15
  export const LOOM_TREE_ATTRIBUTE = "data-loom-tree";
16
16
  export const LOOM_REVISION_ATTRIBUTE = "data-loom-revision";
17
+ export const LOOM_AUDIENCE_ATTRIBUTE = "data-loom-audience";
17
18
  /**
18
19
  * The root element additionally carries the tree it belongs to and the revision
19
20
  * it was rendered from, which is exactly the pair an `EditIntent` needs as its
20
21
  * base. A portal can author an intent from the DOM alone, and an intent
21
22
  * authored against a stale render names the stale revision rather than
22
23
  * silently claiming the current one.
24
+ *
25
+ * It carries the segment the page was served to as well, when it was served to
26
+ * one (0284, 0371), because the browser cannot work that out for itself: the
27
+ * site's server sorted the reader, and this is how the page's signals learn
28
+ * which segment to be filed under. The renderer never hands it `aud_everyone`
29
+ * (see `RenderOptions.audience`), because a page that names no audience already
30
+ * means it.
31
+ *
32
+ * Only a type is imported for it: this file is what `addressed.ts` hands a
33
+ * reader's browser, and the id's schema would bring the schema library with it.
23
34
  */
24
- export const editableAttributes = (node, tree) => tree
35
+ export const editableAttributes = (node, tree, audience) => tree
25
36
  ? {
26
37
  [LOOM_NODE_ATTRIBUTE]: node.id,
27
38
  [LOOM_TYPE_ATTRIBUTE]: node.type,
28
39
  [LOOM_TREE_ATTRIBUTE]: tree.treeId,
29
40
  [LOOM_REVISION_ATTRIBUTE]: String(tree.revision),
41
+ ...(audience === undefined ? {} : { [LOOM_AUDIENCE_ATTRIBUTE]: audience }),
30
42
  }
31
43
  : {
32
44
  [LOOM_NODE_ATTRIBUTE]: node.id,
@@ -0,0 +1,98 @@
1
+ import type { NodeData } from "../data/resolution.js";
2
+ import type { JsonObject, JsonValue } from "../json.js";
3
+ import type { PrimitiveType } from "../primitive-type.js";
4
+ import { type BindingDeclaration } from "./reads.js";
5
+ /**
6
+ * What a primitive said it could read, and the answer that arrived instead.
7
+ *
8
+ * A binding has three ways of being wrong and two of them were closed when the
9
+ * seam was built (0058): an unregistered source is refused, and a param the
10
+ * source did not declare is refused. `reads` closed a third — a name nothing
11
+ * reads (0181). This module closes the one left: an answer that arrives under a
12
+ * name the primitive does read, from a source whose own schema accepted it,
13
+ * **in a shape the primitive cannot draw**.
14
+ *
15
+ * The source's schema is a claim about a host's database and says nothing about
16
+ * what can go on a page, which is 0180's reasoning for a primitive carrying its
17
+ * own schema for what it draws. Until now that schema was private to the
18
+ * component — `loom.feed` re-parses every answer by hand, `loom.tally` the same
19
+ * — so nothing outside the component could tell a list bound to a figure from a
20
+ * figure bound to a figure, and the only report of the mistake was whatever the
21
+ * component chose to draw.
22
+ *
23
+ * What this adds is the declaration, not the reading. **The top-level shape is
24
+ * the framework's question and each row stays the primitive's**, because a row's
25
+ * shape is the one thing only the component knows (0175, 0206) and a listing
26
+ * that skips one row is doing its job rather than failing. So an expectation
27
+ * answers *is this the kind of answer I asked for* and never *is every row in
28
+ * it drawable*.
29
+ */
30
+ /** Whether an answer is the shape the primitive declared it reads. */
31
+ export type AnswerVerdict = {
32
+ readonly outcome: "readable";
33
+ } | {
34
+ readonly outcome: "unreadable";
35
+ readonly detail: string;
36
+ };
37
+ /**
38
+ * One primitive's reading of one binding's answer, with its schema erased.
39
+ *
40
+ * A function rather than the Zod schema it came from, for `validate`'s reason in
41
+ * `sdk/definition.ts`: the erasure happens once, where the schema is still in
42
+ * hand, and nothing in the render path then depends on which schema library
43
+ * declared it. Total — it answers for every `JsonValue` and never throws, which
44
+ * is what lets the walk call it while rendering stays total.
45
+ */
46
+ export type AnswerExpectation = (answer: JsonValue) => AnswerVerdict;
47
+ /**
48
+ * Which answers a primitive says it can read, asked per type.
49
+ *
50
+ * Structural, and detected the way `BindingReader` and `UnshownReader` are: a
51
+ * registry built by the SDK satisfies it, and a host resolving from a plain map
52
+ * has registered nothing that could have declared an expectation. So there is
53
+ * nothing here to wire and nothing that can go missing.
54
+ *
55
+ * Keyed by the **declared** name rather than the name a node asked under, which
56
+ * are different whenever a declaration takes its name from a prop (0184). The
57
+ * shape a primitive draws does not change because a node renamed the binding it
58
+ * draws it from, so the expectation belongs to the declaration and the walk is
59
+ * what resolves one to the other.
60
+ */
61
+ export interface AnswerReader {
62
+ readonly answersExpectedBy: (type: PrimitiveType) => Readonly<Record<string, AnswerExpectation>> | undefined;
63
+ }
64
+ export declare const isAnswerReader: (value: object) => value is AnswerReader;
65
+ /** The name a declaration is keyed under: itself, or the name it falls back to. */
66
+ export declare const declaredName: (declaration: BindingDeclaration) => string;
67
+ /** One answer this node's primitive was given and said it could not read. */
68
+ export type RefusedAnswer = {
69
+ /** The name the node asked under, which is what a reader of the tree sees. */
70
+ readonly name: string;
71
+ readonly detail: string;
72
+ };
73
+ export type CheckedAnswers = {
74
+ readonly data: NodeData;
75
+ readonly refused: readonly RefusedAnswer[];
76
+ };
77
+ /**
78
+ * This node's answers with every one its primitive cannot read turned into the
79
+ * named absence of an answer, and the list of the ones that moved.
80
+ *
81
+ * A refused answer becomes `unavailable` rather than being passed through with a
82
+ * diagnostic beside it, and that is the whole point of the declaration. 0058 is
83
+ * explicit that a binding either has an answer or has a **named reason** it does
84
+ * not, and a primitive handed rows it declared it cannot read has no answer in
85
+ * every sense that matters to the page. What it draws is the rendering 0180
86
+ * already designed for that state — a declared line, announced — rather than
87
+ * whatever a hand-written parse happened to fall through to.
88
+ *
89
+ * Returns the data it was given, by reference, whenever nothing was declared or
90
+ * nothing was refused. That is the path every render takes on every node: the
91
+ * check costs one map read per bound node and allocates nothing unless an answer
92
+ * actually moves.
93
+ *
94
+ * An `unavailable` answer is not re-checked. It has no value to be the wrong
95
+ * shape, and the reason it already carries is the more specific of the two.
96
+ */
97
+ export declare const checkAnswers: (data: NodeData, declared: readonly BindingDeclaration[] | undefined, expectations: Readonly<Record<string, AnswerExpectation>> | undefined, props: JsonObject) => CheckedAnswers;
98
+ //# sourceMappingURL=expected.d.ts.map
@@ -0,0 +1,88 @@
1
+ import { namesRead } from "./reads.js";
2
+ export const isAnswerReader = (value) => typeof value.answersExpectedBy === "function";
3
+ /** The name a declaration is keyed under: itself, or the name it falls back to. */
4
+ export const declaredName = (declaration) => typeof declaration === "string" ? declaration : declaration.default;
5
+ const NOTHING_REFUSED = Object.freeze([]);
6
+ /**
7
+ * This node's answers with every one its primitive cannot read turned into the
8
+ * named absence of an answer, and the list of the ones that moved.
9
+ *
10
+ * A refused answer becomes `unavailable` rather than being passed through with a
11
+ * diagnostic beside it, and that is the whole point of the declaration. 0058 is
12
+ * explicit that a binding either has an answer or has a **named reason** it does
13
+ * not, and a primitive handed rows it declared it cannot read has no answer in
14
+ * every sense that matters to the page. What it draws is the rendering 0180
15
+ * already designed for that state — a declared line, announced — rather than
16
+ * whatever a hand-written parse happened to fall through to.
17
+ *
18
+ * Returns the data it was given, by reference, whenever nothing was declared or
19
+ * nothing was refused. That is the path every render takes on every node: the
20
+ * check costs one map read per bound node and allocates nothing unless an answer
21
+ * actually moves.
22
+ *
23
+ * An `unavailable` answer is not re-checked. It has no value to be the wrong
24
+ * shape, and the reason it already carries is the more specific of the two.
25
+ */
26
+ export const checkAnswers = (data, declared, expectations, props) => {
27
+ if (!declared || !expectations)
28
+ return { data, refused: NOTHING_REFUSED };
29
+ const asked = namesRead(declared, props);
30
+ const refused = [];
31
+ let checked;
32
+ for (const [index, name] of asked.entries()) {
33
+ if (!Object.hasOwn(data, name))
34
+ continue;
35
+ /**
36
+ * Two declarations can resolve to one name — a fixed `entries` beside a
37
+ * prop-named one that fell back to `entries`. That is a strange thing to
38
+ * declare and the registry does not refuse it, so the first expectation
39
+ * holding an opinion decides and the answer is not re-checked. Reading from
40
+ * `data` rather than from the copy is what makes the guard necessary: the
41
+ * copy has the refusal in it and the original still has the answer.
42
+ */
43
+ if (checked && Object.hasOwn(checked, name) && data[name] !== checked[name])
44
+ continue;
45
+ const outcome = data[name];
46
+ if (!outcome || outcome.status !== "ready")
47
+ continue;
48
+ const declaration = declared[index];
49
+ if (!declaration)
50
+ continue;
51
+ /**
52
+ * `Object.hasOwn` before the read, and it is not belt-and-braces: a binding
53
+ * name is an identifier and `constructor` is a valid one, so a declaration
54
+ * map built as a plain object literal would answer every undeclared name
55
+ * with something off `Object.prototype`. `freezeExpectations` gives the
56
+ * registry's map no prototype, and this is the half that holds for a caller
57
+ * handing one over directly — a probe, a test, a host assembling its own.
58
+ * Without it an expectation nobody declared is *called*, and `Object` is not
59
+ * a verdict, so every answer under that name would be refused.
60
+ */
61
+ const key = declaredName(declaration);
62
+ if (!Object.hasOwn(expectations, key))
63
+ continue;
64
+ const expectation = expectations[key];
65
+ if (!expectation)
66
+ continue;
67
+ const verdict = expectation(outcome.value);
68
+ if (verdict.outcome === "readable")
69
+ continue;
70
+ refused.push({ name, detail: verdict.detail });
71
+ if (!checked) {
72
+ checked = Object.create(null);
73
+ for (const held in data) {
74
+ const carried = data[held];
75
+ if (carried)
76
+ checked[held] = carried;
77
+ }
78
+ }
79
+ checked[name] = {
80
+ status: "unavailable",
81
+ unavailable: { reason: "unreadable-answer", detail: verdict.detail },
82
+ };
83
+ }
84
+ if (!checked)
85
+ return { data, refused: NOTHING_REFUSED };
86
+ return { data: Object.freeze(checked), refused: Object.freeze(refused) };
87
+ };
88
+ //# sourceMappingURL=expected.js.map
@@ -17,7 +17,9 @@ export * from "./behaviour.js";
17
17
  export * from "./control.js";
18
18
  export * from "./decorative.js";
19
19
  export * from "./diagnostics.js";
20
+ export * from "./document-theme.js";
20
21
  export * from "./editable.js";
22
+ export * from "./expected.js";
21
23
  export * from "./frame.js";
22
24
  /**
23
25
  * Named one at a time rather than `export *`: `literalThemeElement` is how the
@@ -17,7 +17,9 @@ export * from "./behaviour.js";
17
17
  export * from "./control.js";
18
18
  export * from "./decorative.js";
19
19
  export * from "./diagnostics.js";
20
+ export * from "./document-theme.js";
20
21
  export * from "./editable.js";
22
+ export * from "./expected.js";
21
23
  export * from "./frame.js";
22
24
  /**
23
25
  * Named one at a time rather than `export *`: `literalThemeElement` is how the
@@ -1,4 +1,5 @@
1
1
  import { type ReactNode } from "react";
2
+ import { type AudienceId } from "../audience/audience.js";
2
3
  import { type DataResolution } from "../data/resolution.js";
3
4
  import type { FrameOriginRegistry } from "../frame/origin.js";
4
5
  import type { NodeId } from "../ids.js";
@@ -97,6 +98,16 @@ export type RenderOptions = {
97
98
  * the addresses an event about a reader has to carry (0136).
98
99
  */
99
100
  readonly addressed?: boolean;
101
+ /**
102
+ * The segment the site's server sorted this reader into, when it sorted them
103
+ * into one (0371) — what `segmentOf` from `@jam-overture/loom/live` answers.
104
+ *
105
+ * Written on the root of an addressed page so its reader signals are filed
106
+ * under that segment (0284), and nowhere else: it changes no node and no
107
+ * prop. Absent, or `aud_everyone`, writes nothing, which is every page as it
108
+ * was before segments.
109
+ */
110
+ readonly audience?: AudienceId | undefined;
100
111
  readonly slots?: SlotContent;
101
112
  /**
102
113
  * How the mounted theme reaches the elements: as the `var()` references