@solidjs/web 2.0.0-rc.2 → 2.0.0-rc.21

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 (124) hide show
  1. package/README.md +1 -1
  2. package/dist/server.dev.js +5165 -0
  3. package/dist/server.js +1876 -374
  4. package/dist/{server.cjs → server.observe.js} +2070 -577
  5. package/dist/{dev.cjs → web.dev.js} +955 -567
  6. package/dist/web.js +646 -350
  7. package/dist/{dev.js → web.observe.js} +699 -421
  8. package/frames/dist/assets.js +92 -0
  9. package/frames/dist/client.dev.js +1296 -1198
  10. package/frames/dist/client.js +1128 -1191
  11. package/frames/dist/client.observe.js +2041 -0
  12. package/frames/dist/regions.js +171 -0
  13. package/frames/dist/server.dev.js +2545 -0
  14. package/frames/dist/server.js +1683 -3004
  15. package/frames/dist/server.observe.js +2544 -0
  16. package/frames/dist/trace.js +45 -0
  17. package/frames/dist/wire.js +594 -0
  18. package/frames/package.json +2 -25
  19. package/package.json +244 -256
  20. package/performance-tracks/dist/performance-tracks.dev.js +679 -0
  21. package/performance-tracks/dist/performance-tracks.js +6 -0
  22. package/performance-tracks/dist/performance-tracks.observe.js +667 -0
  23. package/performance-tracks/package.json +7 -0
  24. package/performance-tracks/types/index.d.ts +69 -0
  25. package/serialization/decode/package.json +2 -15
  26. package/serialization/dist/decode.js +121 -25
  27. package/serialization/dist/serialization.js +282 -88
  28. package/serialization/package.json +2 -15
  29. package/serialization/types/index.d.ts +115 -153
  30. package/serialization/types/serializer-decode.d.ts +173 -114
  31. package/serialization/types/serializer.d.ts +144 -0
  32. package/server-functions/dist/client.dev.js +1462 -0
  33. package/server-functions/dist/client.js +667 -165
  34. package/server-functions/dist/client.observe.js +1441 -0
  35. package/server-functions/dist/rich-args.js +102 -1
  36. package/server-functions/dist/server.dev.js +2802 -299
  37. package/server-functions/dist/server.js +2724 -314
  38. package/server-functions/dist/server.observe.js +3680 -0
  39. package/server-functions/package.json +2 -35
  40. package/server-functions/rich-args/package.json +2 -15
  41. package/skills/server-components/SKILL.md +117 -0
  42. package/storage/package.json +2 -15
  43. package/types/client.d.ts +342 -288
  44. package/types/constants.d.ts +22 -0
  45. package/types/cookies.d.ts +32 -84
  46. package/types/diagnostics.d.ts +80 -0
  47. package/types/frames/assets-tier.d.ts +78 -0
  48. package/types/frames/client.d.ts +40 -1
  49. package/types/frames/frame-client.d.ts +443 -280
  50. package/types/frames/frame-container-plugin.d.ts +64 -0
  51. package/types/frames/frame-morph.d.ts +29 -0
  52. package/types/frames/frame-sink.d.ts +141 -161
  53. package/types/frames/frame-transport.d.ts +263 -184
  54. package/types/frames/regions-tier.d.ts +60 -0
  55. package/types/frames/serializer-decode.d.ts +241 -0
  56. package/types/frames/serializer.d.ts +115 -153
  57. package/types/frames/server.d.ts +2 -2
  58. package/types/frames/trace-tier.d.ts +2 -0
  59. package/types/frames/tree-rewrite.d.ts +39 -0
  60. package/types/frames/wire-tier.d.ts +169 -0
  61. package/types/head.d.ts +20 -0
  62. package/types/index.d.ts +98 -81
  63. package/types/index.server.d.ts +159 -0
  64. package/types/jsx.d.ts +49 -44
  65. package/types/observe.d.ts +535 -0
  66. package/types/reconcile.d.ts +1 -0
  67. package/types/render.d.ts +11 -0
  68. package/types/request-error-hook.d.ts +5 -0
  69. package/types/response.d.ts +95 -147
  70. package/types/serializer-decode.d.ts +173 -114
  71. package/types/serializer.d.ts +115 -153
  72. package/types/server-functions/argument-codec.d.ts +30 -0
  73. package/types/server-functions/client.d.ts +237 -223
  74. package/types/server-functions/flash.d.ts +28 -30
  75. package/types/server-functions/registry.d.ts +105 -0
  76. package/types/server-functions/rich-args.d.ts +1 -10
  77. package/types/server-functions/server.d.ts +538 -531
  78. package/types/server-functions/shared.d.ts +398 -425
  79. package/types/server-functions/uploads.d.ts +53 -0
  80. package/types/server-mock.d.ts +154 -20
  81. package/types/server-observe.d.ts +86 -0
  82. package/types/server.d.ts +601 -422
  83. package/types/trace.d.ts +127 -0
  84. package/LICENSE +0 -21
  85. package/dist/web.cjs +0 -2033
  86. package/frames/dist/client.cjs +0 -2002
  87. package/frames/dist/client.dev.cjs +0 -2022
  88. package/frames/dist/server.cjs +0 -3877
  89. package/serialization/dist/decode.cjs +0 -139
  90. package/serialization/dist/serialization.cjs +0 -261
  91. package/serialization/types-cjs/index.d.cts +0 -182
  92. package/serialization/types-cjs/package.json +0 -3
  93. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  94. package/server-functions/dist/client.cjs +0 -834
  95. package/server-functions/dist/rich-args.cjs +0 -11
  96. package/server-functions/dist/server.cjs +0 -1242
  97. package/server-functions/dist/server.dev.cjs +0 -1242
  98. package/storage/dist/storage.cjs +0 -12
  99. package/storage/types-cjs/index.d.cts +0 -28
  100. package/storage/types-cjs/package.json +0 -3
  101. package/types/core.d.ts +0 -9
  102. package/types-cjs/client.d.cts +0 -337
  103. package/types-cjs/cookies.d.cts +0 -93
  104. package/types-cjs/core.d.cts +0 -9
  105. package/types-cjs/frames/client.d.cts +0 -36
  106. package/types-cjs/frames/frame-client.d.cts +0 -356
  107. package/types-cjs/frames/frame-sink.d.cts +0 -194
  108. package/types-cjs/frames/frame-transport.d.cts +0 -222
  109. package/types-cjs/frames/serializer.d.cts +0 -182
  110. package/types-cjs/frames/server.d.cts +0 -52
  111. package/types-cjs/index.d.cts +0 -244
  112. package/types-cjs/jsx-properties.d.cts +0 -93
  113. package/types-cjs/jsx.d.cts +0 -4159
  114. package/types-cjs/package.json +0 -3
  115. package/types-cjs/response.d.cts +0 -174
  116. package/types-cjs/serializer-decode.d.cts +0 -182
  117. package/types-cjs/serializer.d.cts +0 -182
  118. package/types-cjs/server-functions/client.d.cts +0 -262
  119. package/types-cjs/server-functions/flash.d.cts +0 -38
  120. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  121. package/types-cjs/server-functions/server.d.cts +0 -681
  122. package/types-cjs/server-functions/shared.d.cts +0 -523
  123. package/types-cjs/server-mock.d.cts +0 -286
  124. package/types-cjs/server.d.cts +0 -544
@@ -12,164 +12,177 @@
12
12
  * shapes and the wire format may change between prereleases (RFC 11).
13
13
  * Every export in this module is `@experimental`.
14
14
  */
15
-
16
15
  /**
17
- * One transport chunk of a frame stream, addressed by frame `id`.
16
+ * Row ops for a live hole whose value is a `For`'s rows (#4064): the new
17
+ * row count `n` and the rows that changed or were appended, as
18
+ * `[index, html]`. A count below the range's truncates it.
19
+ */
20
+ export type HoleRows = {
21
+ n: number;
22
+ r: [number, string][];
23
+ };
24
+ /**
25
+ * A `data` message: one node of the response-scoped data table the
26
+ * records' `{$ref}` args resolve through — not frame state (it never enters
27
+ * the store), ordered ahead of the records that read it.
18
28
  * @experimental
19
29
  */
20
- export type FrameChunk =
21
- | { type: "start"; id: string; version: number }
22
- | { type: "html"; id: string; version: number; html: string }
23
- | { type: "fragment"; id: string; version: number; key: string; html: string }
24
- | {
25
- type: "reveal";
26
- id: string;
27
- version: number;
28
- keys: string[];
29
- waitForStyles?: boolean;
30
- fallback?: boolean;
31
- }
32
- | {
33
- type: "data";
34
- id: string;
35
- version: number;
36
- key?: string;
37
- node?: unknown;
38
- initial?: boolean;
39
- /** Eval-style hydration script — only when produced with the hydration serializer. */
40
- payload?: string;
41
- }
42
- | {
43
- type: "assets";
44
- id: string;
45
- version: number;
46
- key: string;
47
- modules?: string[];
48
- styles?: string[];
49
- inlineStyles?: { id: string; content?: string; attrs?: Record<string, string> }[];
50
- }
51
- | { type: "slot"; id: string; version: number; key: string; args: Record<string, unknown> }
52
- | { type: "complete"; id: string; version: number }
53
- | { type: "error"; id: string; version: number; key?: string; error: unknown };
54
-
30
+ export type FrameData = {
31
+ type: "data";
32
+ id: string;
33
+ version: number;
34
+ key?: string;
35
+ node?: unknown;
36
+ initial?: boolean;
37
+ /** Eval-style hydration script — only when produced with the hydration serializer. */
38
+ payload?: string;
39
+ };
55
40
  /**
56
- * Maps a wire chunk onto resident-store record writes. `data` chunks map to
57
- * no records — they are response-scoped and the host applies them through
58
- * its data hook.
41
+ * The in-band tier announcement (frames savings pass §2; additive — RFC 11
42
+ * addendum): the frames-client tiers the render first needed since the
43
+ * last message left — `"regions"`, `"assets"`, `"trace"`, `"wire"` — on whichever chunk leaves next. The response head carries the
44
+ * tiers minted before it (`X-Frame-Tiers`); a tier minted later rides
45
+ * here. The client starts each named tier's load before applying the
46
+ * chunk; a `data` chunk additionally AWAITS them (its node tree needs the
47
+ * tier to decode). Absent on every chunk of a response that minted nothing
48
+ * after its head, and ignored by a client that predates it.
59
49
  * @experimental
60
50
  */
61
- export function chunkToRecords(chunk: FrameChunk): Record<string, unknown>;
62
-
51
+ export interface TierAnnouncement {
52
+ tiers?: string[];
53
+ }
63
54
  /**
64
- * One store write applied to a frame: `r` maps record keys to values
65
- * (`chunkToRecords` produces these from wire chunks) and `version` is the
66
- * stream stamp — an older version than the frame's current one is ignored.
55
+ * One message of a frame stream on the wire, addressed by frame `id`: a
56
+ * versioned batch of keyed records — the store write itself (`r`, see
57
+ * `FrameWrite`) — or one of the messages that are not records: `start`
58
+ * (a response's version opens on the address), `data` (a node of the
59
+ * response's data table). Any message may carry `tiers` (see
60
+ * `TierAnnouncement`).
61
+ * @experimental
62
+ */
63
+ export type FrameMessage = ({
64
+ type?: undefined;
65
+ id: string;
66
+ version: number;
67
+ r: Record<string, unknown>;
68
+ } | {
69
+ type: "start";
70
+ id: string;
71
+ version: number;
72
+ /** Observe tier: when the response's request went out (see `landing`). */
73
+ startedAt?: number;
74
+ } | FrameData) & TierAnnouncement;
75
+ /**
76
+ * One store write applied to a frame: `r` maps record keys to values (a
77
+ * wire batch's own `r`) and `version` is the stream stamp — an older
78
+ * version than the frame's current one is ignored.
67
79
  * @experimental
68
80
  */
69
81
  export interface FrameWrite {
70
- version: number;
71
- r: Record<string, unknown>;
82
+ version: number;
83
+ r: Record<string, unknown>;
72
84
  }
73
-
74
85
  /**
75
86
  * Context passed to a slot callback.
76
87
  * @experimental
77
88
  */
78
89
  export interface SlotContext {
79
- /**
80
- * True only for the hydration-attach invocation of an adopted
81
- * document-SSR range — the one call a consumer may answer with a claim
82
- * (`existing` IS the server-rendered output for these args). Unset on
83
- * stream-driven re-calls: those must render for real, or content the
84
- * re-call displaced (e.g. `{$frame}` region ranges) is dropped.
85
- */
86
- adopted?: boolean;
87
- /**
88
- * Whether this occurrence is a render-prop CALL (the producer placed it
89
- * with arguments — possibly empty — via a slot record) as opposed to a
90
- * direct-insert position. Consumers cannot tell from the resolved props
91
- * alone: an argless render prop and a direct insert both arrive as `{}`,
92
- * but one is a function to invoke and the other a value to place.
93
- */
94
- invoked?: boolean;
95
- /**
96
- * Register cleanup for when this occurrence's range is removed from the
97
- * server content, or the owning frame is disposed.
98
- */
99
- onCleanup(fn: () => void): void;
100
- /**
101
- * Live-props opt-in: a binding that registers here receives the
102
- * re-resolved props when a re-sent record's args CHANGE in value, instead
103
- * of the occurrence being re-called — the invocation's instance (and its
104
- * client state) survives the change. Register synchronously during the
105
- * invocation; one updater per occurrence (last registration wins). A
106
- * genuine re-call or unmount clears it before/with the binding it served.
107
- */
108
- onUpdate(fn: (props: Record<string, unknown>) => void): void;
109
- /**
110
- * The range's current interior — server-rendered client content on an
111
- * adopted document-SSR boot, or the previous output on a re-call. A
112
- * framework binding hydrates onto it and returns `undefined` to claim it
113
- * in place (zero DOM mutation).
114
- */
115
- existing: ChildNode[];
116
- /**
117
- * The range's own marker comments, when the occurrence has a placed range.
118
- * A framework binding whose slot content is reactive at the top level (a
119
- * boundary accessor, changing route children) owns the interior instead of
120
- * returning nodes: bind before `end` with the framework's insert primitive
121
- * and return `undefined` — the frame leaves the range alone (server morphs
122
- * already protect slot ranges).
123
- */
124
- range?: { start: Comment; end: Comment };
90
+ /**
91
+ * True only for the hydration-attach invocation of an adopted
92
+ * document-SSR range — the one call a consumer may answer with a claim
93
+ * (`existing` IS the server-rendered output for these args). Unset on
94
+ * stream-driven re-calls: those must render for real, or content the
95
+ * re-call displaced (e.g. `{$frame}` region ranges) is dropped.
96
+ */
97
+ adopted?: boolean;
98
+ /**
99
+ * Whether this occurrence is a render-prop CALL (the producer placed it
100
+ * with arguments — possibly empty — via a slot record) as opposed to a
101
+ * direct-insert position. Consumers cannot tell from the resolved props
102
+ * alone: an argless render prop and a direct insert both arrive as `{}`,
103
+ * but one is a function to invoke and the other a value to place.
104
+ */
105
+ invoked?: boolean;
106
+ /**
107
+ * Register cleanup for when this occurrence's range is removed from the
108
+ * server content, or the owning frame is disposed.
109
+ */
110
+ onCleanup(fn: () => void): void;
111
+ /**
112
+ * Live-props opt-in: a binding that registers here receives the
113
+ * re-resolved props when a re-sent record's args CHANGE in value, instead
114
+ * of the occurrence being re-called — the invocation's instance (and its
115
+ * client state) survives the change. Register synchronously during the
116
+ * invocation; one updater per occurrence (last registration wins). A
117
+ * genuine re-call or unmount clears it before/with the binding it served.
118
+ */
119
+ onUpdate(fn: (props: Record<string, unknown>) => void): void;
120
+ /**
121
+ * The range's current interior — server-rendered client content on an
122
+ * adopted document-SSR boot, or the previous output on a re-call. A
123
+ * framework binding hydrates onto it (a claim: zero DOM mutation) or
124
+ * replaces it.
125
+ */
126
+ existing: ChildNode[];
127
+ /**
128
+ * The range's own marker comments, when the occurrence has a placed range
129
+ * — the anchor the fill owns its interior through: bind or place the
130
+ * output before `end` (over `existing`) with the framework's insert
131
+ * primitive. The frame never touches a range's interior itself (server
132
+ * morphs protect slot ranges). Absent for a range whose end marker is
133
+ * missing.
134
+ */
135
+ range?: {
136
+ start: Comment;
137
+ end: Comment;
138
+ };
125
139
  }
126
-
127
140
  /**
128
141
  * Client content for a server-declared slot. Direct-insert occurrences
129
142
  * call it with empty props; render-prop occurrences pass the occurrence's
130
143
  * resolved args (primitives literal, `{$ref}` data resolved through the
131
- * host, `{$frame}` regions as marker-range fragments). Return nodes to fill
132
- * the range, or `undefined` to claim `ctx.existing` untouched.
144
+ * host, `{$frame}` regions as frame elements). The fill owns its range: it
145
+ * places or binds its output before `ctx.range.end`, over `ctx.existing`
146
+ * (claimed in place on hydration), and disposes it through `ctx.onCleanup`.
147
+ * The return value is not read.
133
148
  * @experimental
134
149
  */
135
- export type Slot = (props: Record<string, unknown>, ctx: SlotContext) => Node | Node[] | undefined;
136
-
150
+ export type Slot = (props: Record<string, unknown>, ctx: SlotContext) => void;
137
151
  /** @experimental */
138
152
  export interface Frame {
139
- /** Merge a write into the store and flush (morph/reveal/slot sync). */
140
- apply(write: FrameWrite): void;
141
- /** The active version, or undefined before the first apply. */
142
- readonly version: number | undefined;
143
- /** Read-only view of the resident record store. */
144
- readonly store: Readonly<Record<string, unknown>>;
145
- /** The stream's error record, if an `error` chunk arrived. */
146
- readonly error: unknown;
147
- /** Whether the named fragment has been revealed into the boundary. */
148
- isRevealed(segment: string): boolean;
149
- /**
150
- * Re-key this live frame to a different boundary id (the mount-preserving
151
- * half of a call-site handoff): nothing tears down — the element, store,
152
- * and slot state stay — while leaving the old id stashes a retention
153
- * snapshot under it and joining the new id seeds/drains its retained
154
- * store and buffered chunks. Version affinity resets: histories are per
155
- * boundary id.
156
- */
157
- rebind(id: string): void;
158
- /**
159
- * Forget the version baseline without touching content — the next write
160
- * is accepted whatever its number. Called by the host after seeding a
161
- * registration from a retained snapshot, whose numbering belongs to a
162
- * different stream space.
163
- */
164
- rebase(): void;
165
- /** Tear down: slot cleanups cascade, later chunks are ignored. Idempotent. */
166
- dispose(): void;
153
+ /** Merge a write into the store and flush (morph/reveal/slot sync). */
154
+ apply(write: FrameWrite): void;
155
+ /** The active version, or undefined before the first apply. */
156
+ readonly version: number | undefined;
157
+ /** Read-only view of the resident record store. */
158
+ readonly store: Readonly<Record<string, unknown>>;
159
+ /** The stream's error record, if an `error` chunk arrived. */
160
+ readonly error: unknown;
161
+ /**
162
+ * Re-key this live frame to a different boundary id (the mount-preserving
163
+ * half of a call-site handoff): nothing tears down — the element, store,
164
+ * and slot state stay — while leaving the old id stashes a retention
165
+ * snapshot under it and joining the new id seeds/drains its retained
166
+ * store and buffered chunks. Version affinity resets: histories are per
167
+ * boundary id.
168
+ */
169
+ rebind(id: string): void;
170
+ /**
171
+ * Push a staged response's slot args into the live occurrences they
172
+ * address, ahead of the records' real apply (see `FrameHost.preview`).
173
+ * @internal
174
+ */
175
+ preview?(records: Record<string, unknown>): void;
176
+ /** Tear down: slot cleanups cascade, later chunks are ignored. Idempotent. */
177
+ dispose(): void;
167
178
  }
168
-
169
179
  /**
170
- * Routes a flat stream of addressed chunks to frames by id, buffering chunks
171
- * for frames that have not registered yet (only the newest version's chunks
172
- * are kept). `data` chunks are response-scoped and go to `applyData`.
180
+ * Routes a flat stream of addressed messages to frames by id, writing each
181
+ * batch into the address's resident store (an address no frame has
182
+ * registered for yet simply warms). `data` messages are response-scoped and
183
+ * go to `applyData`; a `slot:` record's `{$ref}` args are resolved at the
184
+ * write, through the response's data (a value, or a pending read the
185
+ * response settles).
173
186
  *
174
187
  * An id may have several frames (the same server component mounted more
175
188
  * than once): chunks fan out to all of them, and a frame registering after
@@ -177,170 +190,286 @@ export interface Frame {
177
190
  * @experimental
178
191
  */
179
192
  export interface FrameHost {
180
- register(id: string, frame: Frame): void;
181
- /** Remove one frame (or all frames of the id when `frame` is omitted). */
182
- unregister(id: string, frame?: Frame): void;
183
- apply(chunk: FrameChunk): void;
184
- /** The first registered frame under the id, if any. */
185
- get(id: string): Frame | undefined;
186
- serialize(value: unknown): { $ref: string };
187
- /** `frameId` is the resolving frame's id — route to its stream's table. */
188
- resolve(ref: { $ref: string }, frameId?: string): unknown;
189
- /** See FrameHostOptions.revive. */
190
- revive?(value: unknown): unknown;
191
- /** See FrameHostOptions.isContainer. */
192
- isContainer?(value: unknown): boolean;
193
+ register(id: string, frame: Frame): void;
194
+ /** Remove one frame (or all frames of the id when `frame` is omitted). */
195
+ unregister(id: string, frame?: Frame): void;
196
+ apply(msg: FrameMessage): void;
197
+ /**
198
+ * The reactive half of a staged response (see
199
+ * `createServerComponentHandler`): a batch's `slot:` records' args —
200
+ * settled through its own response's table, as at a write — reach the
201
+ * occurrences mounted under its id as re-resolved props into their live
202
+ * bindings, while the store, the markup, and every structural change
203
+ * wait for the batch's `apply`. Other records are ignored.
204
+ * @internal
205
+ */
206
+ preview?(msg: FrameMessage): void;
207
+ /** The first registered frame under the id, if any. */
208
+ get(id: string): Frame | undefined;
209
+ /**
210
+ * The address as an async source: its first landing is the first flush of
211
+ * the first response for it — the root content or its completion; the
212
+ * stream's error is the source ERRORING (frames-rulings 3.3, A0
213
+ * corollary 4 outward: the frame is one async value, and its `:error`
214
+ * is that value rejecting, exactly as any `createAsync` that rejects). A
215
+ * promise resolved at the write that lands it while that response is in
216
+ * flight and REJECTED with the error record at an `:error` write;
217
+ * `undefined` once the address has a landing to show (a later response
218
+ * in flight then morphs over it — the committed value holds), or when
219
+ * nothing has begun for the address. An errored address has no landing
220
+ * to show: a read of it is a promise for the NEXT flight's landing — an
221
+ * errored landing is not a landing for a fresh consumer, and the
222
+ * consumer that reads it re-asks (the integration's `reset`). A mount's
223
+ * covering `<Loading>` pends on this — and on nothing inside the frame —
224
+ * exactly as it pends on any async source's first landing.
225
+ */
226
+ landing(id: string): Promise<void> | undefined;
227
+ serialize(value: unknown): {
228
+ $ref: string;
229
+ };
230
+ /**
231
+ * See FrameHostOptions.revive. Assignable after creation: the frames
232
+ * client's traces tier installs the container-trace reviver on the
233
+ * shared host when its chunk loads (`@solidjs/web/frames/trace`).
234
+ */
235
+ revive?(value: unknown, claiming?: boolean): unknown;
193
236
  }
194
-
195
- /**
196
- * The bubbling DOM event (`"frame:applied"`) a frame dispatches from its
197
- * parent element whenever server content lands in the document — root
198
- * materialize/morph, segment reveal, fallback materialization — with
199
- * `detail: { id, version, reason }`. One document-level listener sees every
200
- * boundary (nested region frames dispatch too); use it to re-apply
201
- * client-owned decorations on server-owned markup (router affordance
202
- * reflection, e.g. `aria-current`) without a MutationObserver.
203
- * @experimental
204
- */
205
- export const FRAME_APPLIED_EVENT: "frame:applied";
206
-
207
237
  /**
208
238
  * Options for `createFrameHost`.
209
239
  * @experimental
210
240
  */
211
241
  export interface FrameHostOptions {
212
- /**
213
- * Backs `{$ref}` slot args (typically a codec data table's `resolve`).
214
- * `frameId` identifies the resolving frame — data tables are
215
- * response-scoped, so multi-stream hosts route by it (nested region ids
216
- * prefix-match their root).
217
- */
218
- resolve?(ref: { $ref: string }, frameId?: string): unknown;
219
- /** Test/host-side counterpart of `resolve`. */
220
- serialize?(value: unknown): { $ref: string };
221
- /**
222
- * Receives each `data` chunk whole. Wire a codec table:
223
- * `applyData: c => table.apply(c)` (see `createJSONDataTable`).
224
- */
225
- applyData?(chunk: Extract<FrameChunk, { type: "data" }>): void;
226
- /**
227
- * A lazily-loaded deserializer's load, awaited by the transport before it
228
- * delivers a `data` chunk — `applyData`/`resolve` can assume the codec is
229
- * resident once data has arrived. Keeps codec weight out of the eager
230
- * client graph for responses that never carry serialized data.
231
- */
232
- prepareData?(): Promise<unknown>;
233
- /**
234
- * Revive protocol markers inside LITERAL slot args (values that are
235
- * neither `{$ref}` nor `{$frame}`) at arg-resolution time. Document-face
236
- * container traces ride this way — inline in the record, revived by the
237
- * integration (`reviveContainerTraces`) into live local containers.
238
- */
239
- revive?(value: unknown): unknown;
240
- /**
241
- * Whether a resolved arg value is a LIVE CONTAINER (a materialized trace —
242
- * see `isMaterializedContainer`). The record-dedupe compare must know: a
243
- * pending container's property reads throw not-ready, so async probes and
244
- * serialization compares would detonate it. Containers compare by
245
- * identity only.
246
- */
247
- isContainer?(value: unknown): boolean;
248
- /**
249
- * Arms event types for behavior claims: the `_bnd` sweep collects the
250
- * event names it finds and hands them here so delegated dispatch can
251
- * reach them. Platform glue passes its `delegateEvents` — the option
252
- * exists (rather than client.js importing the event system) so
253
- * tree-shaken subsets without events pay nothing. Frames registered
254
- * with this host inherit it unless they pass their own `delegate`.
255
- */
256
- delegate?(eventNames: Iterable<string>): void;
242
+ /**
243
+ * Backs `{$ref}` slot args (typically a codec data table's `resolve`).
244
+ * Called at a `slot` chunk's write with the chunk's frame id and version
245
+ * — the RESPONSE the record belongs to (data tables are response-scoped;
246
+ * one response is one version of one id), so the integration answers from
247
+ * that response's table and never a later one's. Answers the key's value,
248
+ * or — for a key the response has not delivered yet — the table's own
249
+ * PENDING READ: a promise marked `s = 0`, carrying `c` (the callbacks run
250
+ * when it settles), that the key's `data` chunk settles (stamped `s`/`v`
251
+ * as it does) and `closeData` rejects (frames-rulings 1.3; the L1 rule —
252
+ * a value that never comes is an error, not a silence). The host counts
253
+ * a record's pending reads so a fresh mount waits for them
254
+ * (`record.pending`) and re-applies the record when the last settles.
255
+ * `current` is the version the id's store is at — every version below it
256
+ * is superseded, and an integration keeping a table per response may
257
+ * drop theirs.
258
+ */
259
+ resolve?(ref: {
260
+ $ref: string;
261
+ }, frameId: string, version: number, current?: number): unknown;
262
+ /** Test/host-side counterpart of `resolve`. */
263
+ serialize?(value: unknown): {
264
+ $ref: string;
265
+ };
266
+ /**
267
+ * Receives each `data` chunk whole. Wire a codec table:
268
+ * `applyData: c => table.apply(c)` (see `createJSONDataTable`); a table
269
+ * per response keys on `chunk.version` (see `resolve` for `current`).
270
+ */
271
+ applyData?(chunk: FrameData, current?: number): void;
272
+ /**
273
+ * The response (one version of one id) has ended — its `complete`, or
274
+ * its `error` with no key — and a key it never delivered never comes:
275
+ * the integration closes that response's table so every pending read of
276
+ * it rejects (`table.close(error)`, with the response's error record when
277
+ * it ended by one). Called after the end chunk's own apply, so the frame
278
+ * has the response's last word first.
279
+ */
280
+ closeData?(frameId: string, version: number, error?: unknown): void;
281
+ /**
282
+ * A lazily-loaded deserializer's load, awaited by the transport before it
283
+ * delivers a `data` chunk or a `slot` chunk whose args carry a `{$ref}` —
284
+ * `applyData`/`resolve` can assume the codec is resident when a chunk
285
+ * that reads data arrives. Keeps codec weight out of the eager client
286
+ * graph for responses that never carry serialized data.
287
+ */
288
+ prepareData?(): Promise<unknown>;
289
+ /**
290
+ * Revive protocol markers inside LITERAL slot args (values that are
291
+ * neither `{$ref}` nor `{$frame}`) at arg-resolution time — the mount's
292
+ * read of the record, where an adopted occurrence's claim can read the
293
+ * revived value as the markup was rendered from it. Document-face
294
+ * container traces ride this way — inline in the record, revived by the
295
+ * integration (`reviveContainerTraces`) into live local containers.
296
+ * `claiming` marks the args of an adopt-time mount — the occurrence is
297
+ * about to hydrate server markup rendered from these values (the
298
+ * materializer parks a trace's backlog beyond the snapshot the markup
299
+ * shows until hydration ends — frames-rulings 3.6 (iii)).
300
+ */
301
+ revive?(value: unknown, claiming?: boolean): unknown;
257
302
  }
258
-
259
- /** @experimental */
260
- export function createFrameHost(options?: FrameHostOptions): FrameHost;
261
-
262
303
  /**
263
304
  * Options for `createFrame` / `createFrameElement`.
264
305
  * @experimental
265
306
  */
266
307
  export interface FrameOptions {
267
- /** Register with this host under `id`, receiving routed/buffered chunks. */
268
- host?: FrameHost;
269
- id?: string;
270
- /** Client content keyed by prop name (occurrences resolve by prop). */
271
- slots?: Record<string, Slot>;
272
- /**
273
- * Raw client props for behavior-claim resolution: server elements carrying
274
- * `_bnd="pos=prop"` markers (compiled under the `serverComponents` option)
275
- * resolve ref/event positions by name through this object — read live at
276
- * dispatch/materialize time, so compiled prop getters stay latest-value.
277
- */
278
- props?: Record<string, unknown>;
279
- /**
280
- * Adopt existing server-rendered DOM: the first apply morphs against it,
281
- * and slots sync immediately (hydration attach) — a document-SSR boot
282
- * needs no chunk.
283
- */
284
- adopt?: boolean;
285
- /** Called after each apply flush (tests/telemetry). */
286
- onApply?(info: { version: number; reason: "materialize" | "morph" | "reveal" | "error" }): void;
287
- /**
288
- * Wraps element-claim sweeps (`a[href]`/`form[action]` in materialized
289
- * server content — and only those) so claim consumers register their
290
- * per-element cleanup against the boundary's reactive owner, e.g.
291
- * `fn => runWithOwner(owner, fn)`. Nested region frames inherit it.
292
- * Without it, sweeps run under whatever owner is current (none, for
293
- * streamed chunks).
294
- */
295
- ownerScope?<T>(fn: () => T): T;
296
- /** Per-frame override of the host's `delegate` (see FrameHostOptions). */
297
- delegate?(eventNames: Iterable<string>): void;
298
- /**
299
- * Boundary-driven segment reveal. When present, `#revealSegment` hands the
300
- * placeholder seam to this hook instead of swapping imperatively: the binding
301
- * reconstructs a client `<Loading>` there — `fallback` is the placeholder's
302
- * own template content (shown while holding), `content()` materializes the
303
- * segment and renders its client fills INSIDE the boundary so their readiness
304
- * gates the reveal — and inserts it before `before`. An unboundaried async
305
- * fill suspends up to that boundary and is covered instead of orphaned; one
306
- * boundary per revealed segment, i.e. per author-placed `<Loading>`. Omit it
307
- * for the framework-agnostic imperative swap (no reactive reveal).
308
- */
309
- reveal?(seam: { before: Node; fallback: Node[]; content: () => Node | DocumentFragment }): void;
310
- /**
311
- * Document-face record-race guard (adopt path only — solidjs/solid#2968).
312
- * Nothing on the wire formally orders an occurrence's args-record data
313
- * script before the event that triggers adoption, so a recordless
314
- * occurrence is ambiguous while this returns true: the frame defers its
315
- * mount one macrotask (all currently parsed scripts run first), calls
316
- * `drainRecords`, and classifies with whatever is then resolvable. Return
317
- * false once the document can run no further data scripts.
318
- */
319
- recordsPending?(): boolean;
320
- /** Re-absorb the document's arrived-by-now records (idempotent per key). */
321
- drainRecords?(): void;
308
+ /** Register with this host under `id`, receiving routed/buffered chunks. */
309
+ host?: FrameHost;
310
+ id?: string;
311
+ /** Client content keyed by prop name (occurrences resolve by prop). */
312
+ slots?: Record<string, Slot>;
313
+ /**
314
+ * Adopt existing server-rendered DOM: the first apply morphs against it,
315
+ * and slots sync immediately (hydration attach) — a document-SSR boot
316
+ * needs no chunk.
317
+ */
318
+ adopt?: boolean;
319
+ /**
320
+ * With `adopt`: leave the slot occurrences unmounted for the client's
321
+ * deferred-hydration driver (`setDeferDriver`) to mount on demand. Region
322
+ * frames inside such a frame inherit it. Ignored with no driver set.
323
+ * @internal
324
+ */
325
+ defer?: boolean;
326
+ /** Called after each apply flush (tests/telemetry). */
327
+ onApply?(info: {
328
+ version: number;
329
+ reason: "materialize" | "morph" | "reveal" | "error";
330
+ }): void;
331
+ /**
332
+ * Wraps element-claim sweeps (`a[href]`/`form[action]` in materialized
333
+ * server content — and only those) so claim consumers register their
334
+ * per-element cleanup against the boundary's reactive owner, e.g.
335
+ * `fn => runWithOwner(owner, fn)`. Nested region frames inherit it.
336
+ * Without it, sweeps run under whatever owner is current (none, for
337
+ * streamed chunks).
338
+ */
339
+ ownerScope?<T>(fn: () => T): T;
340
+ /**
341
+ * Boundary-driven segment reveal. `#revealSegment` hands the placeholder
342
+ * seam to this hook: the binding reconstructs a client `<Loading>` there —
343
+ * `fallback` is the placeholder's own template content (shown while
344
+ * holding), `content()` materializes the segment and renders its client
345
+ * fills INSIDE the boundary so their readiness gates the reveal — and
346
+ * inserts it before `before`. An unboundaried async fill suspends up to
347
+ * that boundary and is covered instead of orphaned; one boundary per
348
+ * revealed segment, i.e. per author-placed `<Loading>`. Omitted, the
349
+ * default seam inserts `content()` before `before` at once and removes
350
+ * `before` (the framework-agnostic swap: no boundary, no reactive reveal).
351
+ */
352
+ reveal?(seam: {
353
+ before: Node;
354
+ fallback: Node[];
355
+ content: () => Node | DocumentFragment;
356
+ }): void;
357
+ /**
358
+ * Adopt path only. Called when a sync leaves an adopted occurrence
359
+ * waiting — for its args record, for a read of it to settle, or for the
360
+ * tier its mount needs to load — while none was before; returns the
361
+ * release, called when a sync leaves none waiting or the frame disposes. The
362
+ * integration registers the hold with whatever counts its page as not
363
+ * yet settled (hydration-done counts it as a pending boundary —
364
+ * frames-rulings 3.1): a claim the frame has not made yet is page work
365
+ * still pending. The record's delivery is the integration's to observe
366
+ * (the document declares it at the marker and settles it — see
367
+ * `adoptBoundary`); the frame only re-syncs on the write.
368
+ */
369
+ hold?(): () => void;
322
370
  }
323
-
371
+ export declare const CLAIMED_ELEMENTS = "a[href], form[action]";
372
+ export declare const claimedAttr: (name: any) => boolean;
373
+ export declare const SLOT_START: RegExp;
374
+ export declare const SLOT_END: RegExp;
375
+ export declare const slotEnd: (id: any) => string;
324
376
  /**
325
- * A frame rendering into an EXISTING element boundary. Pass `adopt: true` for
326
- * the document-SSR path: the element already holds server-rendered content,
327
- * so the first apply morphs against it and slots sync immediately (hydration
328
- * attach), claiming their server-rendered DOM — a document boot needs no
329
- * chunk.
330
- * @experimental
377
+ * Whether a slot arg value is an async value passed whole (a promise or an
378
+ * async iterable) — DR-2's value tier. The server never resolves these to
379
+ * dead values; the client suspends at the consumption read.
380
+ * @internal (the client entry's)
331
381
  */
332
- export function createFrame(boundary: Element, options?: FrameOptions): Frame;
333
-
382
+ export declare function isAsyncValue(v: any): boolean;
383
+ /** @experimental */
384
+ export declare function createFrameHost(options?: FrameHostOptions): FrameHost;
385
+ /**
386
+ * The bubbling DOM event a frame dispatches from its parent element after
387
+ * server content lands in the document (root materialize/morph, segment
388
+ * reveal, fallback materialization) — `detail: { id, version, reason }`.
389
+ * Document-level listeners (router affordance reflection, scroll
390
+ * restoration) react to server-driven DOM changes without a
391
+ * MutationObserver; nested region frames dispatch too and the event
392
+ * bubbles, so one listener sees every boundary. Client-side renders never
393
+ * fire it — client code has reactivity to subscribe with.
394
+ */
395
+ export declare const FRAME_APPLIED_EVENT = "frame:applied";
334
396
  /**
335
- * The default boundary/region element tag and its id attribute — the DOM
336
- * contract the producer emits at t=0 and the consumer creates/adopts.
397
+ * A frames-client tier's module, as its loader resolves it: its exports are
398
+ * the tier's appliers — the functions the runtime dispatches to once the
399
+ * module is resident (the regions tier's `resolve` / `bind` / …, the assets
400
+ * tier's `gate` / `apply`) — and the optional `install()` runs once at the
401
+ * load, for state that lives outside the runtime's dispatch (the traces
402
+ * tier sets the shared host's `revive`). The index signature is what lets a
403
+ * module with no `install` — a module whose exports are all appliers — be
404
+ * one (TypeScript's weak-type rule would otherwise reject it).
337
405
  * @experimental
338
406
  */
339
- export const FRAME_TAG: "dx-frame";
340
- /** @experimental */
341
- export const FRAME_ID_ATTR: "data-fid";
342
-
407
+ export interface TierModule {
408
+ install?(): void;
409
+ [applier: string]: unknown;
410
+ }
411
+ export declare const tierLoaders: Record<string, () => Promise<TierModule>>;
412
+ /** @internal */
413
+ export declare const tierLoads: Record<string, Promise<void> & {
414
+ r?: any;
415
+ }>;
416
+ /**
417
+ * Deferred hydration (see client.ts `installServerComponents`): while a
418
+ * driver is installed, an adopting frame with slots mounts NO occurrence at
419
+ * adoption — no walk, no record resolution, no fill — and hands itself to
420
+ * the driver, which mounts occurrences when an event lands in one
421
+ * (`mountEnclosing`), before a write lands (`mountDeferred` with no
422
+ * deadline) and in idle slices (`mountDeferred` with one). Unset, every
423
+ * frame mounts at adoption.
424
+ * @internal
425
+ */
426
+ export declare let deferDriver: ((frame: any) => void) | null;
427
+ /** @internal */
428
+ export declare function setDeferDriver(driver: ((frame: any) => void) | null): void;
429
+ /**
430
+ * @internal Dev only: wraps every deferred occurrence mount, with the claim
431
+ * scope (the document frame's site) and the occurrence id — the frames
432
+ * client's identity-drift check (client.ts).
433
+ */
434
+ export declare let deferMountWatch: ((site: string, id: string, mount: () => void) => void) | null;
435
+ /** @internal */
436
+ export declare function setDeferMountWatch(watch: ((site: string, id: string, mount: () => void) => void) | null): void;
437
+ /** @internal The live frames still owing their adoption-time mounts, outermost first. */
438
+ export declare function deferredFrames(): any[];
439
+ /** @internal Deferred hydration finished page-wide: every frame's adoption hold lifts. */
440
+ export declare function releaseDeferHolds(): void;
441
+ /** @internal The innermost live frame whose element contains `node`. */
442
+ export declare function liveFrameAt(node: Node): any;
343
443
  /**
444
+ * Start (or join) a tier's load. Idempotent per name; a name with no loader
445
+ * is resident already and resolves at once. Resolves once the module has
446
+ * installed and every live frame has been flushed.
447
+ * @internal The frames client's own seam (the announcement reads call it).
448
+ */
449
+ export declare function prepareTier(name: string): Promise<void> & {
450
+ r?: any;
451
+ };
452
+ /**
453
+ * Whether a tier's code is resident — eager (no loader: `true`), or
454
+ * installed (its module). A tier that is neither has its load started here
455
+ * (the un-announced fallback: detection at the readiness check), and the
456
+ * caller holds. A tier dispatched off the stamp (`assets`) needs its loader
457
+ * wired — the client entry does; a spec driving this module directly wires
458
+ * and warms it (see frames-assets-client.spec).
459
+ */
460
+ /**
461
+ * A call is about to go to the wire on a page that shows frames: its answer
462
+ * will most likely land over content (a navigation, a refetch), and that
463
+ * morph rides the wire tier — start its load now, so it races the request
464
+ * instead of following the response's header.
465
+ * @internal
466
+ */
467
+ export declare const prepareMorph: () => Promise<void> & {
468
+ r?: any;
469
+ };
470
+ export declare function createFrame(boundary: Element, options?: FrameOptions): Frame;
471
+ export declare const FRAME_TAG = "solid-frame";
472
+ export declare const FRAME_ID_ATTR = "data-fid"; /**
344
473
  * Create a boundary/region ELEMENT and bind a host-registered frame to it.
345
474
  * The frame mounts INTO the element (server content is its children, morphed
346
475
  * in place). Because the boundary is a real node, `insert` places the
@@ -349,8 +478,42 @@ export const FRAME_ID_ATTR: "data-fid";
349
478
  * `dispose()` (register it with your owner's cleanup).
350
479
  * @experimental
351
480
  */
352
- export function createFrameElement(options: FrameOptions): {
353
- readonly element: Element;
354
- readonly frame: Frame;
355
- dispose(): void;
481
+ export declare function createFrameElement(options: FrameOptions): {
482
+ readonly element: Element;
483
+ readonly frame: Frame;
484
+ dispose(): void;
356
485
  };
486
+ /**
487
+ * Create a bare boundary/region element (no frame bound yet). `<solid-frame>` is
488
+ * inlined as `display:contents` — not a stylesheet or custom-element
489
+ * registration — so it holds before any bundle loads and needs nothing
490
+ * defined: an undefined custom element is inert HTMLUnknownElement, and
491
+ * `display:contents` makes it generate no box, so its children lay out in the
492
+ * frame's parent.
493
+ *
494
+ * Exported (with `isFrameElement` and `eachInRange`) for the regions tier
495
+ * (`regions-tier.ts`), which bundles its own copy of these pure helpers;
496
+ * the eager entry re-exports none of them.
497
+ * @internal
498
+ */
499
+ export declare function makeFrameElement(id: any): HTMLElement;
500
+ /** Whether `node` is a frame boundary/region element (carries our id attr).
501
+ * @internal */
502
+ export declare function isFrameElement(node: any): any;
503
+ /** Parse an HTML string into a document fragment, preserving comments. */
504
+ export declare function parseFragment(html: any): DocumentFragment;
505
+ /** The `<!--pl-KEY-->` comment closing a placeholder range, or null. */
506
+ export declare function rangeClose(start: any, id: any): any;
507
+ /**
508
+ * Walk a slot range's interior — every node between `start` and the range's
509
+ * end marker — calling `cb` on each. The next sibling is captured before the
510
+ * callback runs, so callbacks may detach the node. Returns the end marker
511
+ * (null if the range is truncated).
512
+ * @internal (exported for the regions tier — see `makeFrameElement`)
513
+ */
514
+ export declare function eachInRange(start: any, key: any, cb: any): any;
515
+ /** If `node` is a `slot:<id>:start` comment, return its id; else `null`. */
516
+ export declare function slotStartId(node: any): string;
517
+ export declare function preservesOpen(el: any): boolean;
518
+ /** The sibling immediately after the `slot:<id>:end` marker for `start`. */
519
+ export declare const afterRange: (start: any, id: any) => any;