@solidjs/web 2.0.0-rc.1 → 2.0.0-rc.11

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 (107) hide show
  1. package/dist/server.dev.js +4472 -0
  2. package/dist/server.js +1301 -251
  3. package/dist/{server.cjs → server.observe.js} +1501 -452
  4. package/dist/{dev.cjs → web.dev.js} +699 -360
  5. package/dist/web.js +454 -139
  6. package/dist/{dev.js → web.observe.js} +505 -211
  7. package/frames/dist/client.dev.js +463 -71
  8. package/frames/dist/client.js +363 -70
  9. package/frames/dist/{client.dev.cjs → client.observe.js} +486 -133
  10. package/frames/dist/server.dev.js +1713 -0
  11. package/frames/dist/server.js +552 -2583
  12. package/frames/dist/server.observe.js +1713 -0
  13. package/frames/package.json +2 -25
  14. package/package.json +214 -255
  15. package/performance-tracks/dist/performance-tracks.dev.js +678 -0
  16. package/performance-tracks/dist/performance-tracks.js +6 -0
  17. package/performance-tracks/dist/performance-tracks.observe.js +666 -0
  18. package/performance-tracks/package.json +7 -0
  19. package/performance-tracks/types/index.d.ts +67 -0
  20. package/serialization/decode/package.json +2 -15
  21. package/serialization/dist/decode.js +92 -15
  22. package/serialization/dist/serialization.js +103 -23
  23. package/serialization/package.json +2 -15
  24. package/serialization/types/index.d.ts +76 -157
  25. package/serialization/types/serializer-decode.d.ts +149 -112
  26. package/serialization/types/serializer.d.ts +101 -0
  27. package/server-functions/dist/client.dev.js +1364 -0
  28. package/server-functions/dist/client.js +611 -97
  29. package/server-functions/dist/client.observe.js +1343 -0
  30. package/server-functions/dist/server.dev.js +2138 -202
  31. package/server-functions/dist/server.js +2042 -199
  32. package/server-functions/dist/server.observe.js +3043 -0
  33. package/server-functions/package.json +2 -35
  34. package/server-functions/rich-args/package.json +2 -15
  35. package/storage/package.json +2 -15
  36. package/types/client.d.ts +193 -288
  37. package/types/constants.d.ts +20 -0
  38. package/types/cookies.d.ts +32 -84
  39. package/types/diagnostics.d.ts +56 -0
  40. package/types/frames/client.d.ts +1 -1
  41. package/types/frames/frame-client.d.ts +323 -259
  42. package/types/frames/frame-container-plugin.d.ts +72 -0
  43. package/types/frames/frame-sink.d.ts +101 -158
  44. package/types/frames/frame-transport.d.ts +192 -190
  45. package/types/frames/serializer-decode.d.ts +219 -0
  46. package/types/frames/serializer.d.ts +76 -157
  47. package/types/frames/server.d.ts +1 -1
  48. package/types/head.d.ts +19 -0
  49. package/types/index.d.ts +52 -80
  50. package/types/index.server.d.ts +174 -0
  51. package/types/jsx.d.ts +33 -35
  52. package/types/observe.d.ts +358 -0
  53. package/types/reconcile.d.ts +1 -0
  54. package/types/render.d.ts +9 -0
  55. package/types/response.d.ts +75 -150
  56. package/types/serializer-decode.d.ts +149 -112
  57. package/types/serializer.d.ts +76 -157
  58. package/types/server-functions/client.d.ts +192 -194
  59. package/types/server-functions/flash.d.ts +28 -30
  60. package/types/server-functions/registry.d.ts +102 -0
  61. package/types/server-functions/rich-args.d.ts +1 -10
  62. package/types/server-functions/server.d.ts +511 -475
  63. package/types/server-functions/shared.d.ts +366 -425
  64. package/types/server-mock.d.ts +110 -13
  65. package/types/server-observe.d.ts +77 -0
  66. package/types/server.d.ts +425 -425
  67. package/types/trace.d.ts +127 -0
  68. package/LICENSE +0 -21
  69. package/dist/web.cjs +0 -2008
  70. package/frames/dist/client.cjs +0 -1916
  71. package/frames/dist/server.cjs +0 -3756
  72. package/serialization/dist/decode.cjs +0 -122
  73. package/serialization/dist/serialization.cjs +0 -244
  74. package/serialization/types-cjs/index.d.cts +0 -182
  75. package/serialization/types-cjs/package.json +0 -3
  76. package/serialization/types-cjs/serializer-decode.d.cts +0 -182
  77. package/server-functions/dist/client.cjs +0 -793
  78. package/server-functions/dist/rich-args.cjs +0 -11
  79. package/server-functions/dist/server.cjs +0 -1171
  80. package/server-functions/dist/server.dev.cjs +0 -1171
  81. package/storage/dist/storage.cjs +0 -12
  82. package/storage/types-cjs/index.d.cts +0 -28
  83. package/storage/types-cjs/package.json +0 -3
  84. package/types/core.d.ts +0 -6
  85. package/types-cjs/client.d.cts +0 -337
  86. package/types-cjs/cookies.d.cts +0 -93
  87. package/types-cjs/core.d.cts +0 -6
  88. package/types-cjs/frames/client.d.cts +0 -36
  89. package/types-cjs/frames/frame-client.d.cts +0 -338
  90. package/types-cjs/frames/frame-sink.d.cts +0 -194
  91. package/types-cjs/frames/frame-transport.d.cts +0 -222
  92. package/types-cjs/frames/serializer.d.cts +0 -182
  93. package/types-cjs/frames/server.d.cts +0 -52
  94. package/types-cjs/index.d.cts +0 -244
  95. package/types-cjs/jsx-properties.d.cts +0 -93
  96. package/types-cjs/jsx.d.cts +0 -4159
  97. package/types-cjs/package.json +0 -3
  98. package/types-cjs/response.d.cts +0 -174
  99. package/types-cjs/serializer-decode.d.cts +0 -182
  100. package/types-cjs/serializer.d.cts +0 -182
  101. package/types-cjs/server-functions/client.d.cts +0 -231
  102. package/types-cjs/server-functions/flash.d.cts +0 -38
  103. package/types-cjs/server-functions/rich-args.d.cts +0 -10
  104. package/types-cjs/server-functions/server.d.cts +0 -616
  105. package/types-cjs/server-functions/shared.d.cts +0 -523
  106. package/types-cjs/server-mock.d.cts +0 -277
  107. package/types-cjs/server.d.cts +0 -523
@@ -1,222 +1,224 @@
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
- /**
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.
18
- * @experimental
19
- */
20
- export const FRAME_STREAM_HEADER: "X-Frame-Stream";
21
-
22
- /**
23
- * Whether a fetch Response carries a frame stream.
24
- * @experimental
25
- */
26
- export function isFrameStreamResponse(response: Response): boolean;
27
-
28
3
  /**
29
4
  * Options for `applyFrameResponse`.
30
5
  * @experimental
31
6
  */
32
7
  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;
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;
56
31
  }
57
-
58
32
  /**
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
- * ```
33
+ * The value under `COMPONENT_BINDING` on a transport-resolved binding.
71
34
  * @experimental
72
35
  */
73
- export function applyFrameResponse(
74
- response: Response,
75
- host: FrameHost,
76
- options?: ApplyFrameResponseOptions
77
- ): Promise<string>;
78
-
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
+ }
79
42
  /**
80
- * Brands an inline-rendered server component with its function id.
43
+ * Options for `createServerComponentHandler`.
81
44
  * @experimental
82
45
  */
83
- export const SERVER_COMPONENT: unique symbol;
84
-
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
+ * A new response is about to stream into an address: rotate
59
+ * response-scoped state (codec data tables) here. `version` is the
60
+ * client-owned stream counter the chunks will be stamped with.
61
+ */
62
+ onStream?(address: string, version: number, response: Response): void;
63
+ /**
64
+ * Answer a call before any request is made (t = 0 local answers — a
65
+ * boundary the document already carries). Returning `undefined` is a
66
+ * miss; any other value is a hit, SYNCHRONOUS, resolving the call with
67
+ * its binding — a hydrating consumer never observes a pending beat. A
68
+ * PROMISE is a deferred hit (a boundary the document is still
69
+ * delivering): the call resolves with its binding when it settles truthy,
70
+ * and is a miss after all — the caller fetches — when it settles falsy.
71
+ */
72
+ intercept?(info: {
73
+ id: string;
74
+ meta: unknown;
75
+ args: unknown[];
76
+ }): unknown | PromiseLike<unknown>;
77
+ }
85
78
  /**
86
- * The unwrapped server component behind an inline-render wrap.
87
- * @experimental
79
+ * Header tagging a Response as a frame stream; its value is the producing
80
+ * frame's id. Frame-owned contract (hence the namespace) — deliberately not
81
+ * a `BodyFormat` entry, since the body is frame chunks, not a serialized
82
+ * value.
88
83
  */
89
- export const SERVER_COMPONENT_SOURCE: unique symbol;
90
-
84
+ export declare const FRAME_STREAM_HEADER = "X-Frame-Stream";
91
85
  /**
92
- * The call's wire address (`frameAddress`), for regions to be emitted under.
86
+ * The resume request's have-list (RFC 11 §9.5, Resume request): the
87
+ * digests the client holds for the address it is reconnecting — the root
88
+ * skeleton under `""`, then one entry per live hole (`lh:N`), attr hole
89
+ * (`lha:N`) and revealed fragment (`pl-N`). Its PRESENCE makes the render a
90
+ * conditional one: the server emits a hole or fragment only when it has
91
+ * settled and its digest differs, and never a root or a fallback over
92
+ * content the list names. Rides only to the live address (a `no-store`
93
+ * response nothing keys on) — never as an argument. Decision (f): this
94
+ * name; a list whose encoding would exceed `FRAME_HAVE_BUDGET` bytes is
95
+ * omitted and the client accepts a full snapshot.
93
96
  * @experimental
94
97
  */
95
- export const SERVER_COMPONENT_ADDRESS: unique symbol;
96
-
98
+ export declare const FRAME_HAVE_HEADER = "X-Frame-Have";
99
+ /** The have-list's size ceiling in encoded bytes (see FRAME_HAVE_HEADER). */
100
+ export declare const FRAME_HAVE_BUDGET = 4096;
97
101
  /**
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
102
+ * Encodes a have-list for the header: `key=digest` pairs, comma-joined
103
+ * (keys never contain either separator; the root's key is empty).
104
+ * `undefined` when the list is empty or over budget.
105
+ * @internal
106
106
  */
107
- export const COMPONENT_BINDING: unique symbol;
108
-
107
+ export declare function encodeHaveList(have: Record<string, string>): string | undefined;
109
108
  /**
110
- * The value under `COMPONENT_BINDING` on a transport-resolved binding.
111
- * @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
112
113
  */
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
-
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>;
117
+ /** Brands an inline-rendered server component with its function id. */
118
+ export declare const SERVER_COMPONENT: unique symbol;
119
+ /** The unwrapped server component behind an inline-render wrap. */
120
+ export declare const SERVER_COMPONENT_SOURCE: unique symbol;
121
+ /** The call's wire address (`frameAddress`), for regions to be emitted under. */
122
+ export declare const SERVER_COMPONENT_ADDRESS: unique symbol;
120
123
  /**
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
124
+ * The binding brand on values the transport resolves: `{ component, address }`
125
+ * (see `createServerComponentHandler`). The identity split (DR-1,
126
+ * docs/server-components-principles.md): `component` is the MOUNT identity —
127
+ * one per server function, stable across every call — while `address` names
128
+ * the call's content store. An equals-gated reader (a framework's `dynamic`)
129
+ * compares `component` across resolutions: same function means "same
130
+ * instance, new binding" — it keeps its mounted instance and delivers the
131
+ * new address into it (the instance's frame re-binds its pull to that
132
+ * address's resident store) — and a different function swaps normally.
133
+ * `Symbol.for`, so consumers honor it without importing this module.
127
134
  */
128
- export const ServerComponentPlugin: unknown;
129
-
135
+ export declare const COMPONENT_BINDING: unique symbol;
136
+ export declare function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
130
137
  /**
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
138
+ * Seroval plugin for a server component crossing a serialization boundary.
139
+ * A branded component (see `frameTransformDirectResult`) serializes as a
140
+ * REFERENCE — its markup never rides as data.
141
+ *
142
+ * Two distinct consumers share the one tag:
143
+ *
144
+ * - `serialize` (eval-style, the document hydration serializer): emits
145
+ * `self._$SC.r("<function id>", "<address>")`. The document shell's inline
146
+ * bootstrap memoizes a stable placeholder per FUNCTION — a delegating
147
+ * shell whose every mount binds to its own SSR'd element during adoption
148
+ * — and resolves the addressed reference to the call's BINDING over it
149
+ * (`COMPONENT_BINDING`, the same shape `bindingFor` below mints), so a
150
+ * reader that adopted the reference during hydration (an async
151
+ * `dynamic()` instance's record) holds the same identity a later answer
152
+ * for the call resolves to.
153
+ * - `deserialize` (the JSON codec): the codec only ever carries a component
154
+ * inside a single-flight envelope, so this is a FLIGHT reference. It must
155
+ * resolve to the exact object the reading call site already holds — an
156
+ * integration seeding its cache with anything else fails the consumer's
157
+ * equals-gate and remounts the boundary — so it resolves through the live
158
+ * transport registry by the call's address.
138
159
  */
139
- export function setServerComponentBootstrap(resolve: (ctx: unknown) => string): void;
140
-
141
- /**
160
+ declare function parseServerComponent(value: any, ctx: any): {
161
+ id: any;
162
+ address: any;
163
+ };
164
+ /** @type {import("seroval").Plugin<Function, { id: any, address: any }>} */
165
+ export declare const ServerComponentPlugin: {
166
+ tag: string;
167
+ test(value: any): boolean;
168
+ parse: {
169
+ sync: typeof parseServerComponent;
170
+ async(value: any, ctx: any): Promise<{
171
+ id: any;
172
+ address: any;
173
+ }>;
174
+ stream: typeof parseServerComponent;
175
+ };
176
+ serialize(node: any, ctx: any): string;
177
+ deserialize(node: any, ctx: any): any;
178
+ }; /**
142
179
  * The codec options for a single-flight envelope: `codec` plus
143
180
  * `ServerComponentPlugin` (deduped by tag). Injected by the protocol on both
144
181
  * legs; exported for integrations composing their own flight carriers.
145
182
  * @experimental
146
183
  */
147
- export function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
148
-
149
- /**
150
- * Options for `createServerComponentHandler`.
151
- * @experimental
152
- */
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
-
191
- /**
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.
198
- *
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).
204
- * @experimental
205
- */
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;
184
+ export declare function flightCodec(codec?: JSONCodecOptions): JSONCodecOptions;
185
+ export declare function createServerComponentHandler<C>(options: ServerComponentHandlerOptions<C>): {
186
+ intercept?(info: {
187
+ id: string;
188
+ meta: unknown;
189
+ args: unknown[];
190
+ }): unknown;
191
+ handle(response: Response, ctx: {
192
+ id: string;
193
+ meta: unknown;
194
+ args: unknown[];
195
+ context: unknown;
196
+ }): unknown;
197
+ /**
198
+ * What a `live` (re)connect of the call resumes from (RFC 11 §9.5,
199
+ * Resume request): the address's version ordinal as the position
200
+ * (`Last-Event-ID`) and, when a mount shows the address with a ledger,
201
+ * its have-list under `FRAME_HAVE_HEADER` — omitted over budget, so the
202
+ * render is a full snapshot then. `undefined` when nothing here has
203
+ * shown the call.
204
+ */
205
+ resume(info: {
206
+ id: string;
207
+ meta: unknown;
208
+ args: unknown[];
209
+ }): {
210
+ position: string;
211
+ headers?: Record<string, string>;
212
+ } | undefined;
213
+ /**
214
+ * Declares that the document is showing a call: hydration-data references
215
+ * carry their call's address (`_$SC.r(id, address)`) but never travel
216
+ * through the transport, so the integration forwards those records here.
217
+ * Mints the call's binding (a post-load refetch then resolves a value
218
+ * whose component matches what the document mounted) and brands the
219
+ * per-function component so cache-seeded readers deliver instead of
220
+ * remounting when their site later switches calls.
221
+ */
222
+ showing(address: string, functionId: string): void;
222
223
  };
224
+ export {};
@@ -0,0 +1,219 @@
1
+ /**
2
+ * Seroval's node shape — the intermediate representation `serializeJSON`
3
+ * emits and `createJSONDeserializer` consumes. Safe to `JSON.stringify`.
4
+ * Declared by hand like the plugin types below (same rationale): the
5
+ * observable envelope — a numeric type tag, an optional reference id —
6
+ * with the rest owned by the codec. Real seroval nodes satisfy it; treat
7
+ * it as an opaque token.
8
+ *
9
+ * Integration-facing; may change (see the entry banner).
10
+ */
11
+ export interface SerovalNode {
12
+ /** Node type tag (seroval-internal enum). */
13
+ t: number;
14
+ /** Reference id, when the node participates in cross-referencing. */
15
+ i?: number | undefined;
16
+ [key: string]: unknown;
17
+ }
18
+ /** Per-plugin bookkeeping seroval hands each plugin callback. */
19
+ export interface PluginData {
20
+ id: number;
21
+ }
22
+ /**
23
+ * The shape of a plugin's parsed payload: a map of `SerovalNode`s produced
24
+ * by the parse contexts, consumed by `serialize`/`deserialize`.
25
+ */
26
+ export type PluginInfo = {
27
+ [key: string]: SerovalNode;
28
+ };
29
+ /** Parse context for `parse.sync`: turns child values into nodes. */
30
+ export interface SyncParsePluginContext {
31
+ parse<T>(current: T): SerovalNode;
32
+ }
33
+ /** Parse context for `parse.async`: like sync, but child parses await. */
34
+ export interface AsyncParsePluginContext {
35
+ parse<T>(current: T): Promise<SerovalNode>;
36
+ }
37
+ /**
38
+ * Parse context for `parse.stream`: sync parsing plus the streaming
39
+ * lifecycle (pending-state tracking, late node emission, cleanup).
40
+ */
41
+ export interface StreamParsePluginContext {
42
+ parse<T>(current: T): SerovalNode;
43
+ parseWithError<T>(current: T): SerovalNode | undefined;
44
+ isAlive(): boolean;
45
+ pushPendingState(): void;
46
+ popPendingState(): void;
47
+ onParse(node: SerovalNode): void;
48
+ onError(error: unknown): void;
49
+ addCleanup(callback: () => void): void;
50
+ }
51
+ /** Serialize context: renders child nodes to JS source. */
52
+ export interface SerializePluginContext {
53
+ serialize(node: SerovalNode): string;
54
+ }
55
+ /** Deserialize context: revives child nodes to runtime values. */
56
+ export interface DeserializePluginContext {
57
+ deserialize<T>(node: SerovalNode): T;
58
+ }
59
+ /**
60
+ * A Seroval plugin usable with the web serializers — teaches the codec how
61
+ * to encode/decode a custom value type (`Value` is the value it matches,
62
+ * `Info` its parsed payload). Supply matching plugins on both peers of a
63
+ * transport. Bare `SerializerPlugin` (both parameters defaulted to `any`)
64
+ * is the list-element type every `plugins` option accepts.
65
+ *
66
+ * Integration-facing; may change (see the entry banner).
67
+ */
68
+ export interface SerializerPlugin<Value = any, Info extends PluginInfo = any> {
69
+ /** A unique string identifying the plugin — namespace it (`"app/Thing"`). */
70
+ tag: string;
71
+ /** Dependency plugins, resolved ahead of this one. */
72
+ extends?: SerializerPlugin[];
73
+ /** Whether `value` is this plugin's to encode. */
74
+ test(value: unknown): boolean;
75
+ /** Parsing modes — provide the ones the transports you target use. */
76
+ parse: {
77
+ sync?: (value: Value, ctx: SyncParsePluginContext, data: PluginData) => Info;
78
+ async?: (value: Value, ctx: AsyncParsePluginContext, data: PluginData) => Promise<Info>;
79
+ stream?: (value: Value, ctx: StreamParsePluginContext, data: PluginData) => Info;
80
+ };
81
+ /** Renders the parsed payload as JS source (script-injection form). */
82
+ serialize(node: Info, ctx: SerializePluginContext, data: PluginData): string;
83
+ /** Revives the parsed payload back into the runtime value. */
84
+ deserialize(node: Info, ctx: DeserializePluginContext, data: PluginData): Value;
85
+ }
86
+ /**
87
+ * Options shared by both halves of the JSON codec. All of them must match
88
+ * on the serializing and deserializing peer or payloads will not
89
+ * round-trip — for server functions, set them once through the
90
+ * client/server `codec` config option.
91
+ *
92
+ * Integration-facing; may change (see the entry banner).
93
+ */
94
+ export interface JSONCodecOptions {
95
+ /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
96
+ plugins?: SerializerPlugin[];
97
+ /**
98
+ * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
99
+ * (payloads may come from an untrusted peer). Must match on both peers.
100
+ * Outside development, the encoding side additionally strips
101
+ * `Error.prototype.stack` on top of any override — serialized stacks leak
102
+ * server paths to the client. Decoding stays permissive, so payloads from
103
+ * a development peer still round-trip.
104
+ */
105
+ disabledFeatures?: number;
106
+ /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
107
+ depthLimit?: number;
108
+ /**
109
+ * Whether serialized `Error`s carry their `.stack` — server file paths,
110
+ * internal function names, the shape of the deployment — to the peer.
111
+ * Defaults to `NODE_ENV === "development"`, but that signal describes the
112
+ * PROCESS, not the artifact: a production build running with
113
+ * `NODE_ENV=development` (a base image, a stray dotenv) ships stacks to
114
+ * the wire — including for errors marked safe with `markSafeError`, whose
115
+ * stacks traverse application code (#3152). Set `false` to pin production
116
+ * disclosure regardless of the ambient variable. Encode-side only; the
117
+ * decode side is always permissive, so it need not match peers.
118
+ */
119
+ serializeErrorStacks?: boolean;
120
+ }
121
+ /**
122
+ * A resident, response-scoped decode table over the keyed JSON codec: apply
123
+ * each frame `data` chunk with `apply`, resolve `{ $ref }` slot args with
124
+ * `resolve`. The frames client host wires one per response
125
+ * (`applyData: c => table.apply(c)`).
126
+ *
127
+ * Integration-facing; may change (see the entry banner). This serialization
128
+ * entry is the single home of the data table — the frames client consumes
129
+ * it internally rather than re-exporting it.
130
+ */
131
+ export interface JSONDataTable {
132
+ apply(chunk: {
133
+ key?: string;
134
+ node?: unknown;
135
+ initial?: boolean;
136
+ }): void;
137
+ resolve<T = unknown>(ref: {
138
+ $ref: string;
139
+ }): T;
140
+ }
141
+ /**
142
+ * Baseline plugin set for serializing web-platform values. Shared by the
143
+ * hydration serializer and any consumer building its own serializer (e.g.
144
+ * server function transports). Plugin objects carry both their serialize
145
+ * and deserialize halves, so the set lives on the decode side and the
146
+ * encode module composes over it.
147
+ */
148
+ export declare const DEFAULT_WEB_PLUGINS: readonly ({
149
+ tag: string;
150
+ test(value: any): boolean;
151
+ parse: {
152
+ sync(): never;
153
+ async(value: any, ctx: any): Promise<{
154
+ a: number;
155
+ i: any;
156
+ }>;
157
+ stream: (value: any, ctx: any) => {
158
+ a: number;
159
+ i: any;
160
+ };
161
+ };
162
+ serialize(node: any, ctx: any): string;
163
+ deserialize(node: any, ctx: any): any;
164
+ } | import("seroval").Plugin<AbortSignal, {
165
+ reason?: import("seroval").SerovalNode;
166
+ controller?: import("seroval").SerovalNode;
167
+ factory?: import("seroval").SerovalNode;
168
+ }> | import("seroval").Plugin<CustomEvent<any>, {
169
+ type: import("seroval").SerovalNode;
170
+ options: import("seroval").SerovalNode;
171
+ }> | import("seroval").Plugin<DOMException, {
172
+ name: import("seroval").SerovalNode;
173
+ message: import("seroval").SerovalNode;
174
+ }> | import("seroval").Plugin<Event, {
175
+ type: import("seroval").SerovalNode;
176
+ options: import("seroval").SerovalNode;
177
+ }> | import("seroval").Plugin<FormData, {
178
+ factory: import("seroval").SerovalNode;
179
+ entries: import("seroval").SerovalNode;
180
+ }> | import("seroval").Plugin<Headers, {
181
+ value: import("seroval").SerovalNode;
182
+ }> | import("seroval").Plugin<ReadableStream<any>, {
183
+ factory: import("seroval").SerovalNode;
184
+ stream: import("seroval").SerovalNode;
185
+ }> | import("seroval").Plugin<Request, {
186
+ url: import("seroval").SerovalNode;
187
+ options: import("seroval").SerovalNode;
188
+ }> | import("seroval").Plugin<Response, {
189
+ body: import("seroval").SerovalNode;
190
+ options: import("seroval").SerovalNode;
191
+ }> | import("seroval").Plugin<URLSearchParams, {
192
+ value: import("seroval").SerovalNode;
193
+ }> | import("seroval").Plugin<URL, {
194
+ value: import("seroval").SerovalNode;
195
+ }>)[]; /**
196
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
197
+ * first so they can shadow a default for values both would match. Returns a
198
+ * fresh array; the defaults are never mutated. Useful when handing a full
199
+ * plugin list to another serialization layer.
200
+ *
201
+ * Integration-facing; may change (see the entry banner).
202
+ */
203
+ export declare function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
204
+ export declare function resolveCodecOptions({ plugins, disabledFeatures, depthLimit, serializeErrorStacks }?: JSONCodecOptions): {
205
+ plugins: SerializerPlugin<any, any>[];
206
+ disabledFeatures: number;
207
+ depthLimit: number;
208
+ serializeErrorStacks: boolean;
209
+ }; /**
210
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
211
+ * between chunks resolve through state shared across calls, so all chunks
212
+ * from one stream must go through the same deserializer instance. The first
213
+ * chunk's return value is the decoded source value; feeding later chunks
214
+ * settles the async values referenced inside it.
215
+ *
216
+ * Integration-facing; may change (see the entry banner).
217
+ */
218
+ export declare function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;
219
+ export declare function createJSONDataTable(options?: JSONCodecOptions): JSONDataTable;