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

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 +5065 -0
  3. package/dist/server.js +1757 -355
  4. package/dist/{server.cjs → server.observe.js} +1951 -558
  5. package/dist/{dev.cjs → web.dev.js} +945 -550
  6. package/dist/web.js +635 -332
  7. package/dist/{dev.js → web.observe.js} +688 -403
  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 +2549 -0
  14. package/frames/dist/server.js +1688 -3005
  15. package/frames/dist/server.observe.js +2548 -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 +242 -88
  28. package/serialization/package.json +2 -15
  29. package/serialization/types/index.d.ts +85 -158
  30. package/serialization/types/serializer-decode.d.ts +173 -114
  31. package/serialization/types/serializer.d.ts +109 -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 +84 -1
  36. package/server-functions/dist/server.dev.js +2714 -297
  37. package/server-functions/dist/server.js +2595 -271
  38. package/server-functions/dist/server.observe.js +3594 -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 +85 -158
  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 +85 -158
  72. package/types/server-functions/argument-codec.d.ts +30 -0
  73. package/types/server-functions/client.d.ts +238 -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 +539 -531
  78. package/types/server-functions/shared.d.ts +398 -425
  79. package/types/server-functions/uploads.d.ts +50 -0
  80. package/types/server-mock.d.ts +120 -13
  81. package/types/server-observe.d.ts +86 -0
  82. package/types/server.d.ts +571 -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
@@ -1,222 +1,301 @@
1
- // EXPERIMENTAL — the frames/server-components surface ships as an
2
- // experimental preview, excluded from the 2.0 stability guarantee: API
3
- // shapes and the wire format may change between prereleases (RFC 11).
4
- // Every export in this module is @experimental.
5
- import { FrameChunk, FrameHost } from "./frame-client.js";
1
+ import { FrameHost } from "./frame-client.js";
6
2
  import { JSONCodecOptions } from "./serializer-decode.js";
7
-
8
- // Structural mirror of server-functions/shared.js's FlightDataConsumer:
9
- // this file may only reference siblings that ship with it when integrations
10
- // copy the frames declaration set (solid-web's types build), and the
11
- // server-functions declarations are copied to a different root.
12
- type FlightConsumer = (data: unknown, context: { response: Response }) => void | Promise<void>;
13
-
14
3
  /**
15
- * Header tagging a Response as a frame stream; its value is the producing
16
- * frame's id. Frame-owned wire contract — deliberately not a server-function
17
- * `BodyFormat` entry, since the body is frame chunks, not a serialized value.
4
+ * Options for `applyFrameResponse`.
18
5
  * @experimental
19
6
  */
20
- export const FRAME_STREAM_HEADER: "X-Frame-Stream";
21
-
7
+ export interface ApplyFrameResponseOptions {
8
+ /**
9
+ * Remap the producer's root frame id onto a local one — the id your
10
+ * insertable/frame registered under — so navigations to the same boundary
11
+ * reuse the same frame regardless of what the server called it. Boundary
12
+ * identity belongs to the client.
13
+ */
14
+ as?: string;
15
+ /**
16
+ * Restamp every chunk of the response with this version (one response IS
17
+ * one version). Versions belong to the client too: the producer cannot
18
+ * know how many streams a boundary has consumed, so pass the Nth-response
19
+ * counter to make policy A's stale-guard real across navigations. A
20
+ * single-flight response addresses several boundaries, each with its own
21
+ * history — pass a function and it is called once per frame in the
22
+ * response.
23
+ */
24
+ version?: number | ((frameId: string) => number);
25
+ /**
26
+ * Receives the payload text of each `outcome` chunk — the response-scoped
27
+ * single-flight envelope, the caller's result rather than anything the
28
+ * host renders.
29
+ */
30
+ onOutcome?(payload: string): void;
31
+ }
22
32
  /**
23
- * Whether a fetch Response carries a frame stream.
33
+ * The value under `COMPONENT_BINDING` on a transport-resolved binding.
24
34
  * @experimental
25
35
  */
26
- export function isFrameStreamResponse(response: Response): boolean;
27
-
36
+ export interface ComponentBinding<C = unknown> {
37
+ /** The per-function mount component (the equals-gate identity). */
38
+ component: C;
39
+ /** The call's intrinsic (function, arguments) address — its store's key. */
40
+ address: string;
41
+ }
28
42
  /**
29
- * Options for `applyFrameResponse`.
43
+ * Options for `createServerComponentHandler`.
30
44
  * @experimental
31
45
  */
32
- export interface ApplyFrameResponseOptions {
33
- /**
34
- * Remap the producer's root frame id onto a local one — the id your
35
- * insertable/frame registered under — so navigations to the same boundary
36
- * reuse the same frame regardless of what the server called it. Boundary
37
- * identity belongs to the client.
38
- */
39
- as?: string;
40
- /**
41
- * Restamp every chunk of the response with this version (one response IS
42
- * one version). Versions belong to the client too: the producer cannot
43
- * know how many streams a boundary has consumed, so pass the Nth-response
44
- * counter to make policy A's stale-guard real across navigations. A
45
- * single-flight response addresses several boundaries, each with its own
46
- * history — pass a function and it is called once per frame in the
47
- * response.
48
- */
49
- version?: number | ((frameId: string) => number);
50
- /**
51
- * Receives the payload text of each `outcome` chunk — the response-scoped
52
- * single-flight envelope, the caller's result rather than anything the
53
- * host renders.
54
- */
55
- onOutcome?(payload: string): void;
46
+ export interface ServerComponentHandlerOptions<C = unknown> {
47
+ host: FrameHost;
48
+ /**
49
+ * Builds the framework's mount component for a server FUNCTION. Invoked
50
+ * once per function and cached — this is the equals-gate identity every
51
+ * call of the function resolves through. The component is CALLED (by the
52
+ * binding wrapper or a gated reader), receiving its current address as a
53
+ * second argument (`() => string`); it should (re-)bind its frame's pull
54
+ * to that address's store. Multi-mount fans out per site.
55
+ */
56
+ component(fnId: string): C;
57
+ /**
58
+ * Answer a call before any request is made (t = 0 local answers — a
59
+ * boundary the document already carries). Returning `undefined` is a
60
+ * miss; any other value is a hit, SYNCHRONOUS, resolving the call with
61
+ * its binding — a hydrating consumer never observes a pending beat. A
62
+ * PROMISE is a deferred hit (a boundary the document is still
63
+ * delivering): the call resolves with its binding when it settles truthy,
64
+ * and is a miss after all — the caller fetches — when it settles falsy.
65
+ */
66
+ intercept?(info: {
67
+ id: string;
68
+ meta: unknown;
69
+ args: unknown[];
70
+ }): unknown | PromiseLike<unknown>;
56
71
  }
57
-
58
72
  /**
59
- * Reads a frame-stream Response to completion, applying every chunk to
60
- * `host`. Chunks are length-prefixed JSON over the server-function wire
61
- * framing. Resolves with the id the chunks were applied under once the
62
- * stream ends; rejects on a malformed or errored stream.
63
- *
64
- * @example
65
- * ```ts
66
- * const response = await getStory(id); // frame-tagged server function result
67
- * if (isFrameStreamResponse(response)) {
68
- * await applyFrameResponse(response, host, { as: "story-pane" });
69
- * }
70
- * ```
71
- * @experimental
73
+ * Header tagging a Response as a frame stream; its value is the producing
74
+ * frame's id. Frame-owned contract (hence the namespace) — deliberately not
75
+ * a `BodyFormat` entry, since the body is frame chunks, not a serialized
76
+ * value.
72
77
  */
73
- export function applyFrameResponse(
74
- response: Response,
75
- host: FrameHost,
76
- options?: ApplyFrameResponseOptions
77
- ): Promise<string>;
78
-
78
+ export declare const FRAME_STREAM_HEADER = "X-Frame-Stream";
79
79
  /**
80
- * Brands an inline-rendered server component with its function id.
80
+ * The tiers a frame stream needs (frames savings pass §2, the
81
+ * server-announced tier mechanism): the names, comma-separated, of the
82
+ * frames-client tiers the render had minted when the response head left
83
+ * — `bind,regions,assets,trace,wire` — so the client starts their loads
84
+ * before it reads the body. Omitted when nothing was minted. A tier first
85
+ * needed after the head rides in-band instead: `tiers` on the next chunk
86
+ * (`FrameMessage.tiers`). Additive wire: an old client ignores both; a new
87
+ * client without them falls back to detection at the readiness check and
88
+ * holds (frames-rulings 3.1) — the same DOM, later.
81
89
  * @experimental
82
90
  */
83
- export const SERVER_COMPONENT: unique symbol;
84
-
91
+ export declare const FRAME_TIERS_HEADER = "X-Frame-Tiers";
85
92
  /**
86
- * The unwrapped server component behind an inline-render wrap.
93
+ * The resume request's have-list (RFC 11 §9.5, Resume request): the
94
+ * digests the client holds for the address it is reconnecting — the root
95
+ * skeleton under `""`, then one entry per live hole (`lh:N`), attr hole
96
+ * (`lha:N`) and revealed fragment (`pl-N`). Its PRESENCE makes the render a
97
+ * conditional one: the server emits a hole or fragment only when it has
98
+ * settled and its digest differs, and never a root or a fallback over
99
+ * content the list names. Rides only to the live address (a `no-store`
100
+ * response nothing keys on) — never as an argument. Decision (f): this
101
+ * name; a list whose encoding would exceed `FRAME_HAVE_BUDGET` bytes is
102
+ * omitted and the client accepts a full snapshot.
87
103
  * @experimental
88
104
  */
89
- export const SERVER_COMPONENT_SOURCE: unique symbol;
90
-
105
+ export declare const FRAME_HAVE_HEADER = "X-Frame-Have";
106
+ /** The have-list's size ceiling in encoded bytes (see FRAME_HAVE_HEADER). */
107
+ export declare const FRAME_HAVE_BUDGET = 4096;
91
108
  /**
92
- * The call's wire address (`frameAddress`), for regions to be emitted under.
93
- * @experimental
109
+ * Decodes a have-list header value; `undefined` for an absent/empty one.
110
+ * Tolerant of malformed entries (skipped) — a wrong entry costs one
111
+ * unneeded emission, never a wrong skip.
112
+ * @internal
94
113
  */
95
- export const SERVER_COMPONENT_ADDRESS: unique symbol;
96
-
114
+ export declare function decodeHaveList(text: string | null | undefined): Record<string, string> | undefined;
115
+ export declare function isFrameStreamResponse(response: Response): boolean;
116
+ export declare const applyFrameResponse: (response: Response, host: FrameHost, options?: ApplyFrameResponseOptions) => Promise<string>;
97
117
  /**
98
- * The binding brand on values the transport resolves: `{ component, address }`
99
- * — the identity split (DR-1). `component` is the mount identity, one per
100
- * server function; `address` names the call's content store. An equals-gated
101
- * reader compares `component` across resolutions: same function means "same
102
- * instance, new binding" — keep the mounted instance and deliver the new
103
- * address into it; a different function swaps normally. `Symbol.for`, so
104
- * frameworks can honor it without importing this module.
105
- * @experimental
118
+ * Reads a frame-stream Response to completion, applying every chunk to
119
+ * `host`. The client owns boundary identity: pass `options.as` to remap the
120
+ * producer's root frame id onto a local one (the id your insertable/frame
121
+ * registered under), so navigations to the same boundary reuse the same
122
+ * frame regardless of what the server called it. Resolves with the id the
123
+ * chunks were applied under once the stream ends.
124
+ *
125
+ * The client owns versions too: the producer can't know how many streams a
126
+ * boundary has consumed, so `options.version` restamps the response's
127
+ * chunks, making policy A's stale-guard real across navigations. A number
128
+ * versions the whole response — one response IS one version — which holds
129
+ * while a response addresses one boundary. A single-flight response
130
+ * addresses several (each invalidated region is its own boundary, with its
131
+ * own history), so `version` may instead be a function called once per
132
+ * frame in the response.
133
+ *
134
+ * `options.onOutcome` receives the payload text of each `outcome` chunk —
135
+ * the response-scoped single-flight envelope, which is the caller's result
136
+ * rather than anything the host renders.
106
137
  */
107
- export const COMPONENT_BINDING: unique symbol;
108
-
109
138
  /**
110
- * The value under `COMPONENT_BINDING` on a transport-resolved binding.
111
- * @experimental
139
+ * Whether a message ends its frame's response: a batch writing `:complete`
140
+ * (the server declared the frame done) or `:error` (the failing kind of it).
141
+ * @internal (the live wire tier's too)
112
142
  */
113
- export interface ComponentBinding<C = unknown> {
114
- /** The per-function mount component (the equals-gate identity). */
115
- component: C;
116
- /** The call's intrinsic (function, arguments) address — its store's key. */
117
- address: string;
118
- }
119
-
143
+ export declare const ends: (msg: any) => boolean;
144
+ /** Brands an inline-rendered server component with its function id. */
145
+ export declare const SERVER_COMPONENT: unique symbol;
146
+ /** The unwrapped server component behind an inline-render wrap. */
147
+ export declare const SERVER_COMPONENT_SOURCE: unique symbol;
148
+ /** The call's wire address (`frameAddress`), for regions to be emitted under. */
149
+ export declare const SERVER_COMPONENT_ADDRESS: unique symbol;
120
150
  /**
121
- * Seroval plugin for a server component crossing a serialization boundary:
122
- * a branded component serializes as a REFERENCE — a per-function document
123
- * placeholder in the hydration serializer, a live-registry lookup by call
124
- * address in the JSON codec (single-flight envelopes) — its markup never
125
- * rides as data.
126
- * @experimental
151
+ * The binding brand on values the transport resolves: `{ component, address }`
152
+ * (see `createServerComponentHandler`). The identity split (DR-1,
153
+ * docs/server-components-principles.md): `component` is the MOUNT identity —
154
+ * one per server function, stable across every call — while `address` names
155
+ * the call's content store. An equals-gated reader (a framework's `dynamic`)
156
+ * compares `component` across resolutions: same function means "same
157
+ * instance, new binding" — it keeps its mounted instance and delivers the
158
+ * new address into it (the instance's frame re-binds its pull to that
159
+ * address's resident store) — and a different function swaps normally.
160
+ * `Symbol.for`, so consumers honor it without importing this module.
127
161
  */
128
- export const ServerComponentPlugin: unknown;
129
-
162
+ export declare const COMPONENT_BINDING: unique symbol;
130
163
  /**
131
- * Installs the hydration-serializer registry prefix: given the emitted
132
- * script's serializer context, returns the expression the next serialized
133
- * reference reads the `_$SC` registry through (the self-bootstrapping form
134
- * on a script's first reference, a bare read after). Loaded document-SSR
135
- * modules install this (see frame-sink); client bundles never carry the
136
- * bootstrap text.
137
- * @experimental
164
+ * The address a content token belongs to; a plain address passes through.
165
+ * @internal
138
166
  */
139
- export function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
140
-
167
+ export declare function contentAddress(token: string): string;
141
168
  /**
142
- * The codec options for a single-flight envelope: `codec` plus
143
- * `ServerComponentPlugin` (deduped by tag). Injected by the protocol on both
144
- * legs; exported for integrations composing their own flight carriers.
145
- * @experimental
169
+ * The live handler's staged content (see `createServerComponentHandler`),
170
+ * by token; a plain address, or a token already committed or superseded,
171
+ * is a no-op. Mounts call both halves from the render effect that follows
172
+ * their address accessor: `preview` from its compute half — under the
173
+ * transaction that delivered the token, so the slot args it pushes into the
174
+ * live fills (see `FrameHost.preview`) are staged with it and a fill's
175
+ * derivation over an arg re-derives in that pass, never one flush behind
176
+ * the intent it held (principles §9.2.2) — and `commit` from its effect
177
+ * half, landing the buffered response as the store's writes in the commit.
178
+ * Installed by the handler (one active handler at a time, as for
179
+ * `resolveServerComponent` below).
180
+ * @internal
146
181
  */
147
- export function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
148
-
182
+ export declare const stagedContent: {
183
+ preview(token: string): void;
184
+ commit(token: string): void;
185
+ };
149
186
  /**
150
- * Options for `createServerComponentHandler`.
151
- * @experimental
187
+ * The call recorded for an address — `{ id, meta, args, retry }`, `retry`
188
+ * the thunk that makes the same call again — or `undefined` for an address
189
+ * no response or document answer named.
190
+ * @internal
152
191
  */
153
- export interface ServerComponentHandlerOptions<C = unknown> {
154
- host: FrameHost;
155
- /**
156
- * Builds the framework's mount component for a server FUNCTION. Invoked
157
- * once per function and cached — this is the equals-gate identity every
158
- * call of the function resolves through. The component is CALLED (by the
159
- * binding wrapper or a gated reader), receiving its current address as a
160
- * second argument (`() => string`); it should (re-)bind its frame's pull
161
- * to that address's store. Multi-mount fans out per site.
162
- */
163
- component(fnId: string): C;
164
- /**
165
- * A new response is about to stream into an address: rotate
166
- * response-scoped state (codec data tables) here. `version` is the
167
- * client-owned stream counter the chunks will be stamped with.
168
- */
169
- onStream?(address: string, version: number, response: Response): void;
170
- /**
171
- * Answer a call SYNCHRONOUSLY before any request is made (t = 0 local
172
- * answers — e.g. a boundary the document already carries). Returning a
173
- * non-undefined value resolves the call with it; a hydrating consumer
174
- * never observes a pending beat.
175
- */
176
- intercept?(info: { id: string; meta: unknown; args: unknown[] }): C | undefined;
177
- /**
178
- * Reads the registered single-flight consumer at delivery time. The
179
- * consumer is module state in the server-function client's SHARED
180
- * instance; pass a getter reading that instance when your bundling gives
181
- * this module a private copy. Defaults to the local copy's reader.
182
- */
183
- consumer?(): FlightConsumer | undefined;
184
- /**
185
- * Reads the configured codec options at decode time — same instance-
186
- * identity contract as `consumer`. Defaults to the local copy's reader.
187
- */
188
- codec?(): JSONCodecOptions | undefined;
189
- }
190
-
192
+ export declare function callFor(address: string): {
193
+ id: string;
194
+ meta: unknown;
195
+ args: unknown[];
196
+ retry(): Promise<unknown>;
197
+ } | undefined;
198
+ export declare function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
191
199
  /**
192
- * The client mirror of `frameTransformResult`, shaped for the server-function
193
- * client's `responseHandler` seam: frame-stream responses resolve the call
194
- * with a **binding** — a callable wrapper branded `COMPONENT_BINDING` — so
195
- * an equals-gated consumer (Solid's `dynamic`) never remounts across
196
- * refetches or argument changes; the response streams into the address's
197
- * resident store as the only observable effect.
200
+ * Seroval plugin for a server component crossing a serialization boundary.
201
+ * A branded component (see `frameTransformDirectResult`) serializes as a
202
+ * REFERENCE — its markup never rides as data.
203
+ *
204
+ * Two distinct consumers share the one tag:
198
205
  *
199
- * The identity split (DR-1): stores are keyed per-ADDRESS — the call's
200
- * intrinsic (function, arguments) name, one-to-one with a query cache's
201
- * per-args entries — while mounts are per-SITE, rendering the per-function
202
- * component and following delivered addresses. An address nothing is bound
203
- * to warms its store (preload isolation is the default, not a rule).
206
+ * - `serialize` (eval-style, the document hydration serializer): emits
207
+ * `self._$SC.r("<function id>", "<address>")`. The document shell's inline
208
+ * bootstrap memoizes a stable placeholder per FUNCTION — a delegating
209
+ * shell whose every mount binds to its own SSR'd element during adoption
210
+ * — and resolves the addressed reference to the call's BINDING over it
211
+ * (`COMPONENT_BINDING`, the same shape `bindingFor` below mints), so a
212
+ * reader that adopted the reference during hydration (an async
213
+ * `dynamic()` instance's record) holds the same identity a later answer
214
+ * for the call resolves to.
215
+ * - `deserialize` (the JSON codec): the codec only ever carries a component
216
+ * inside a single-flight envelope, so this is a FLIGHT reference. It must
217
+ * resolve to the exact object the reading call site already holds — an
218
+ * integration seeding its cache with anything else fails the consumer's
219
+ * equals-gate and remounts the boundary — so it resolves through the live
220
+ * transport registry by the call's address.
221
+ */
222
+ declare function parseServerComponent(value: any, ctx: any): {
223
+ id: any;
224
+ address: any;
225
+ };
226
+ /** @type {import("seroval").Plugin<Function, { id: any, address: any }>} */
227
+ export declare const ServerComponentPlugin: {
228
+ tag: string;
229
+ test(value: any): boolean;
230
+ parse: {
231
+ sync: typeof parseServerComponent;
232
+ async(value: any, ctx: any): Promise<{
233
+ id: any;
234
+ address: any;
235
+ }>;
236
+ stream: typeof parseServerComponent;
237
+ };
238
+ serialize(node: any, ctx: any): string;
239
+ deserialize(node: any, ctx: any): any;
240
+ }; /**
241
+ * The codec options for a single-flight envelope: `codec` plus
242
+ * `ServerComponentPlugin` (deduped by tag). Injected by the protocol on both
243
+ * legs; exported for integrations composing their own flight carriers.
204
244
  * @experimental
205
245
  */
206
- export function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
207
- intercept?(info: { id: string; meta: unknown; args: unknown[] }): unknown;
208
- handle(
209
- response: Response,
210
- ctx: { id: string; meta: unknown; args: unknown[]; context: unknown }
211
- ): unknown;
212
- /**
213
- * Declares that the document is showing a call: hydration-data references
214
- * carry their call's address (`_$SC.r(id, address)`) but never travel
215
- * through the transport, so the integration forwards those records here.
216
- * Mints the call's binding (a post-load refetch then resolves a value
217
- * whose component matches what the document mounted) and brands the
218
- * per-function component so cache-seeded readers deliver instead of
219
- * remounting when their site later switches calls.
220
- */
221
- showing(address: string, functionId: string): void;
246
+ export declare function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
247
+ export declare function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
248
+ /**
249
+ * `retry` (the server-function client's thunk for the call it is
250
+ * answering or dispatched, declared shape included) is recorded behind
251
+ * the call's address for the re-ask (`callFor`, frames-rulings 3.3).
252
+ */
253
+ intercept?(info: {
254
+ id: string;
255
+ meta: unknown;
256
+ args: unknown[];
257
+ retry?(): Promise<unknown>;
258
+ }): unknown;
259
+ handle(response: Response, ctx: {
260
+ id: string;
261
+ meta: unknown;
262
+ args: unknown[];
263
+ context: unknown;
264
+ retry?(): Promise<unknown>;
265
+ /** Observe tier: when the request went out (`performance.now()`). */
266
+ startedAt?: number;
267
+ }): unknown;
268
+ /**
269
+ * A `live()` call was made (before its first fetch): starts the live wire
270
+ * tier's load (`prepareTier("wire")`), so the import races only the
271
+ * request — preload-at-call.
272
+ */
273
+ onLive(): void;
274
+ /**
275
+ * What a `live` (re)connect of the call resumes from (RFC 11 §9.5,
276
+ * Resume request): the address's version ordinal as the position
277
+ * (`Last-Event-ID`) and, when a mount shows the address with a ledger,
278
+ * its have-list under `FRAME_HAVE_HEADER` — omitted over budget, so the
279
+ * render is a full snapshot then. `undefined` when nothing here has
280
+ * shown the call — or while the live wire tier, which keeps the ledger
281
+ * and answers this, is not resident yet (a first connect over content a
282
+ * plain call applied: a full snapshot, the degraded case accepted).
283
+ */
284
+ resume(info: {
285
+ id: string;
286
+ meta: unknown;
287
+ args: unknown[];
288
+ }): {
289
+ position: string;
290
+ headers?: Record<string, string>;
291
+ } | undefined;
292
+ /**
293
+ * Declares that the document is showing a call: hydration-data references
294
+ * carry their call's address (`_$SC.r(id, address)`) but never travel
295
+ * through the transport, so the integration forwards those records here.
296
+ * Mints the call's binding, so a post-load refetch resolves a value
297
+ * whose component matches what the document mounted.
298
+ */
299
+ showing(address: string, functionId: string): void;
222
300
  };
301
+ export {};
@@ -0,0 +1,60 @@
1
+ /**
2
+ * The `{$frame}` arm of a frame's arg resolution: for each region arg of
3
+ * the record (`regions`: arg name -> wire id), the region ELEMENT the
4
+ * wrapper places goes into `props` — cached per occurrence, so a re-call
5
+ * re-places the SAME element (no marker range to walk, no fragment refill)
6
+ * and the bound frame's parent follows live. `start` is given on the
7
+ * adopt-time mount (the frame's `claiming`): the interior's region elements
8
+ * are discovered first, so the record's addresses resolve to them.
9
+ */
10
+ export declare function resolve(frame: any, occurrence: string, regions: Record<string, string>, props: Record<string, unknown>, start?: unknown): void;
11
+ /**
12
+ * Bind a frame over each of the occurrence's region elements that has none
13
+ * yet — those `resolve` minted during the invoke or, on the adopt path,
14
+ * discovered in the interior before the fill ran (the fill owns its range
15
+ * through the framework's insert; the frame never reads its output back).
16
+ * Bind eagerly — the region ELEMENT always exists (unlike a marker range,
17
+ * which needs placement to count).
18
+ * This is what makes an OCCLUDED region work: its element is created when
19
+ * args resolve but the wrapper doesn't place it until (e.g.) expand, so it
20
+ * must bind and fill (from buffered/streamed chunks) off-DOM, then reveal
21
+ * in place when the wrapper finally inserts the single node. Host
22
+ * buffering flushes any queued childId chunks. The region inherits this
23
+ * frame's slot resolution (`parent`), so client slots revealed in its
24
+ * streamed content are filled by the same callbacks the client threaded
25
+ * down — no global registry.
26
+ */
27
+ export declare function bind(frame: any, occurrence: string): void;
28
+ /**
29
+ * A fill read a region element: the reader's owner places it, as reading
30
+ * `props.children` places client children. The region's nested fills mount
31
+ * under it — those waiting for a placement, and those the last placement's
32
+ * disposal took down with it.
33
+ */
34
+ export declare function place(el: Element): void;
35
+ /**
36
+ * Invoke a fill (`mount`, the binding's) for an occurrence: one in a region
37
+ * mounts under the owner that placed the region — so it reads the context
38
+ * the enclosing fill provides there — and lives as long as that placement.
39
+ * While the region is unplaced (occluded, or its placement disposed) it
40
+ * waits; the next placement mounts it afresh over what the range holds.
41
+ */
42
+ export declare function nest(mount: (props: any, ctx: any) => void, props: any, ctx: any): void;
43
+ /**
44
+ * Dispose the frames bound over an occurrence's regions and forget them;
45
+ * without an occurrence, every region of the frame (the frame is being
46
+ * disposed).
47
+ */
48
+ export declare function unmount(frame: any, occurrence?: string): void;
49
+ /**
50
+ * For the staged preview (`Frame.preview`): whether the record adds a
51
+ * region to the occurrence or renames one of its regions — its chunks ride
52
+ * the new name, so the rename must land with them at the commit, not in
53
+ * the preview. Read off the host's note of the record's `{$frame}` args.
54
+ */
55
+ export declare function changed(frame: any, occurrence: string, record: {
56
+ regions?: Record<string, string>;
57
+ }): boolean;
58
+ /** The frames bound over the frame's regions (the staged preview recurses
59
+ * into them). */
60
+ export declare function frames(frame: any): any[];