@solidjs/web 2.0.0-rc.14 → 2.0.0-rc.16

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 (58) hide show
  1. package/README.md +1 -1
  2. package/dist/server.dev.js +475 -591
  3. package/dist/server.js +459 -489
  4. package/dist/server.observe.js +459 -498
  5. package/dist/web.dev.js +206 -220
  6. package/dist/web.js +196 -208
  7. package/dist/web.observe.js +206 -213
  8. package/frames/dist/client.dev.js +664 -643
  9. package/frames/dist/client.js +593 -582
  10. package/frames/dist/client.observe.js +624 -589
  11. package/frames/dist/regions.js +43 -2
  12. package/frames/dist/server.dev.js +578 -450
  13. package/frames/dist/server.js +578 -397
  14. package/frames/dist/server.observe.js +578 -397
  15. package/frames/dist/trace.js +4 -1
  16. package/frames/dist/wire.js +371 -6
  17. package/package.json +13 -13
  18. package/serialization/dist/decode.js +11 -9
  19. package/serialization/dist/serialization.js +11 -9
  20. package/serialization/types/serializer-decode.d.ts +2 -2
  21. package/server-functions/dist/client.dev.js +5 -2
  22. package/server-functions/dist/client.js +3 -2
  23. package/server-functions/dist/client.observe.js +5 -2
  24. package/server-functions/dist/rich-args.js +33 -1
  25. package/server-functions/dist/server.dev.js +218 -35
  26. package/server-functions/dist/server.js +218 -35
  27. package/server-functions/dist/server.observe.js +218 -35
  28. package/skills/server-components/SKILL.md +74 -185
  29. package/types/client.d.ts +112 -10
  30. package/types/constants.d.ts +2 -1
  31. package/types/frames/assets-tier.d.ts +2 -2
  32. package/types/frames/client.d.ts +8 -3
  33. package/types/frames/frame-client.d.ts +121 -157
  34. package/types/frames/frame-morph.d.ts +28 -0
  35. package/types/frames/frame-sink.d.ts +13 -9
  36. package/types/frames/frame-transport.d.ts +30 -1
  37. package/types/frames/regions-tier.d.ts +15 -0
  38. package/types/frames/serializer-decode.d.ts +2 -2
  39. package/types/frames/server.d.ts +1 -53
  40. package/types/frames/wire-tier.d.ts +54 -1
  41. package/types/head.d.ts +1 -0
  42. package/types/index.d.ts +57 -50
  43. package/types/index.server.d.ts +3 -27
  44. package/types/jsx.d.ts +14 -17
  45. package/types/observe.d.ts +14 -7
  46. package/types/render.d.ts +3 -1
  47. package/types/response.d.ts +31 -8
  48. package/types/serializer-decode.d.ts +2 -2
  49. package/types/server-functions/argument-codec.d.ts +21 -0
  50. package/types/server-functions/client.d.ts +18 -5
  51. package/types/server-functions/server.d.ts +6 -2
  52. package/types/server-functions/shared.d.ts +19 -0
  53. package/types/server-mock.d.ts +9 -2
  54. package/types/server-observe.d.ts +3 -2
  55. package/types/server.d.ts +124 -67
  56. package/frames/dist/bind.dev.js +0 -326
  57. package/frames/dist/bind.js +0 -295
  58. package/types/frames/bind-tier.d.ts +0 -60
@@ -1,228 +1,117 @@
1
+ ---
2
+ name: server-components
3
+ description: Rules for writing Solid 2.0 server components ("use server" functions that return a template) and their slots with @solidjs/web. Use when writing or reviewing a server component, deciding what lives on the server versus the client, or wiring a slot.
4
+ ---
5
+
1
6
  # Writing Solid server components with slots
2
7
 
3
8
  A Solid server component is a `"use server"` function that returns a
4
9
  template; the browser receives its markup and never its code. Anything the
5
- client contributes goes through a **slot** on the component's props. This
6
- guide is the set of rules an author — a person or an agent — needs to write
7
- one correctly the first time. The design record is
8
- `documentation/server-components/server-components-principles.md` §9.2.3;
9
- this file is the operative subset.
10
+ client contributes goes through a **slot** on the component's props: a
11
+ client component the client places at a position in the server's markup.
12
+ This guide is the set of rules an author — a person or an agent — needs to
13
+ write one correctly the first time. The design record is
14
+ `documentation/server-components/server-components-principles.md`; this
15
+ file is the operative subset.
10
16
 
11
17
  ## Where things go
12
18
 
13
19
  > **An element lives where the data that creates it lives.**
14
20
 
15
21
  - Exists because of **server data** (a todo row, a nav link, a search
16
- form the server renders)? It is **server markup**. Client behavior or a
17
- client-driven value on it is a **binding slot** — bind, never wrap.
18
- Do not wrap a server-rendered element in a client component to give it a
19
- handler or a class.
20
- - Exists because of **client state alone** (an optimistic add, a modal, a
21
- drag ghost, an editor open over a field)? It is a **client component**
22
- placed through a **template slot**.
22
+ form the server renders)? It is **server markup**. A mutation on it is a
23
+ form `action` — it works without JavaScript, and the router marks a
24
+ submission in flight (`aria-busy`) so CSS can show the intent.
25
+ - Needs **client behavior or client state** (a handler, an optimistic add,
26
+ a modal, a drag ghost, an editor open over a field)? It is a **client
27
+ component** placed through a **slot**.
23
28
 
24
29
  When the client confirms an optimistic entity and the server renders it, the
25
30
  row _becomes_ server markup; `$key` on the element reconciles the two.
26
31
 
27
- ## The two kinds of slot
32
+ ## Slots
28
33
 
29
34
  ```tsx
30
- import type { BindingSlot, Slot } from "@solidjs/web/frames";
35
+ import type { Slot } from "@solidjs/web/frames";
31
36
 
32
37
  interface TodosProps {
33
- pending: Slot; // template: the client returns JSX
34
- row: BindingSlot<{ id: string; completed: boolean }, RowBehavior>; // bindings: the client returns an object
35
- filters: BindingSlot<{}, FilterBehavior>; // no args: called bare
38
+ pending: Slot; // no props
39
+ editor: Slot<{ id: string; title: string }>; // props from the server
36
40
  }
37
41
  ```
38
42
 
39
- A **template slot** is placed as an element: `<props.pending />`. The client
40
- owns those nodes.
41
-
42
- A **binding slot** is _called_ once per data context and its properties
43
- are _bound_ at positions of the server's own template:
43
+ A slot is placed as an element: `<props.pending />`,
44
+ `<props.editor id={t.id} title={t.title} />`. The client owns the nodes
45
+ between the slot's markers; the server's markup around them stays the
46
+ server's.
44
47
 
45
48
  ```tsx
46
49
  export async function todoList() {
47
50
  "use server";
48
51
  const todos = await db.list();
49
- return (props: TodosProps) => {
50
- const filters = props.filters();
51
- return (
52
- <>
53
- <ul>
54
- {todos.map(t => (
55
- <TodoRow
56
- id={t.id}
57
- title={t.title}
58
- row={props.row({ id: t.id, completed: t.completed })}
59
- />
60
- ))}
61
- <props.pending />
62
- </ul>
63
- <a href="#/" class={{ selected: filters.all }}>
64
- All
65
- </a>
66
- </>
67
- );
68
- };
52
+ return (props: TodosProps) => (
53
+ <ul>
54
+ {todos.map(t => (
55
+ <li $key={t.id}>
56
+ {t.title}
57
+ <props.editor $key={t.id} id={t.id} title={t.title} />
58
+ </li>
59
+ ))}
60
+ <props.pending />
61
+ </ul>
62
+ );
69
63
  }
70
64
  ```
71
65
 
72
- The client passes the fill — a function of the args that returns the object:
66
+ The client passes the fill — a component of the slot's props:
73
67
 
74
68
  ```tsx
75
- <Todos row={rowFor} filters={() => ({ get all() { return filter() === "all"; }, … })} pending={() => <For each={adds}>{…}</For>} />
69
+ <Todos editor={p => <Editor id={p.id} title={p.title} />} pending={() => <For each={adds}>{…}</For>} />
76
70
  ```
77
71
 
78
- The fill must return a plain object. An array, a DOM node, a function or
79
- an async value is a type error on both sides (`BindingSlot`'s return is
80
- `SlotOutput<J>`, a branded `SlotError` naming the reason) and a
81
- `fill-shape` finding at runtime.
82
-
83
- ## The one rule for binding slots
84
-
85
- > **A slot property is a JSX attribute value or a text child, whole, and nothing else.**
86
-
87
- Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
88
- `title={row.error}`), a class name inside object form
89
- (`class={{ completed: row.done }}`), the whole `class`/`style`
90
- (`class={row.rowClass}`), a style property (`style={{ opacity: row.fade }}`),
91
- an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element
92
- with a spread too (`<button {...rest} onClick={row.go} />` — the last
93
- source that has the key wins, `undefined` included, as the client's
94
- spread reads it) — and a text child (`<strong>{list.remaining}</strong> items
95
- left`): a string or number renders, nullish and booleans render empty, and
96
- the client owns the text between a `<!--_s:t=…-->` marker pair. Never the
97
- content of `<textarea>`, `<title>`, `<style>` or `<script>`, where the
98
- markers would be literal text — bind `value=` or a style property there.
99
- Not a `prop:*` property, not inside another slot call's args (nested in
100
- plain objects and arrays included). Reserved keys the fill must not use:
101
- keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`,
102
- `constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map`
103
- included) is a plain property.
104
-
105
- The server **does not have the value** — on the stream face a property read
106
- is a stand-in with no value, on the document face only the initial one — so
107
- nothing can be computed from it on the server. Every one of these is wrong:
108
-
109
- | Wrong | Why | Write instead |
110
- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
111
- | ``class={`todo ${row.done}`}`` | stringified: not the whole value | `class={{ todo: true, completed: row.done }}` or return `rowClass` from the fill |
112
- | `row.count > 3 ? "a" : "b"` | comparison on a stand-in | decide in the fill; return the decided value |
113
- | `if (row.error) …`, `row.error && <button/>`, `<Show when={row.done}>` | truthiness: a stand-in is an object and **always truthy** — the branch always renders | presence → `hidden={…}` or a class; a node that exists because of client state → a template slot |
114
- | `<strong>{row.label}</strong>` where the fill returns JSX for `label` | a text position renders a string or number | a template slot for markup |
115
- | `<textarea>{row.draft}</textarea>` | raw-text content: the markers land in the text | `value={row.draft}` |
116
- | `format(row.title)` (a server helper) | the helper receives a stand-in | do the formatting in the fill |
117
- | `<li {...row}>` | spread: the template must show what the client owns | name each position |
118
- | `onClick={() => …}` on a server element | a server function can never run in the browser | bind a slot property or a form `action` |
119
- | `onKeyDown={[row.key, 1]}` | a tuple: a marker names keys, never data | return `onKeyDown: [handler, data]` from the fill; bind `onKeyDown={row.onKeyDown}` |
120
-
121
- Every case except truthiness and raw-text content is a dev finding
122
- (`BINDING_SLOT_POSITION`) and renders **nothing on either face**, so it
123
- shows on the first render. Truthiness has no runtime hook: if a retry button
124
- appears on every row, this is why. Raw-text content has none either; in
125
- `<textarea>` and `<title>` the markers show as text.
126
-
127
- ## Writing the fill
128
-
129
72
  - **The fill runs once per occurrence, as a component body does.** It runs
130
- untracked, under the occurrence's owner, with live args. State it
73
+ untracked, under the occurrence's owner, with live props. State it
131
74
  creates (a signal, a memo, an `onCleanup`) lives as long as the
132
75
  occurrence. A top-level read is read once, and `STRICT_READ_UNTRACKED`
133
- names it.
134
- - **Values as getters, handlers as plain closures.** A getter is the
135
- reactive form, as on a component's props object; a plain value never
136
- updates:
137
-
138
- ```tsx
139
- const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({
140
- get rowClass() {
141
- return { todo: true, completed: done(p.id, p.completed), pending: !!intent.byId[p.id] };
142
- },
143
- get done() {
144
- return done(p.id, p.completed);
145
- },
146
- get removed() {
147
- return removed(p.id);
148
- },
149
- onToggle: e => actions.toggle(p.id, e.currentTarget.checked),
150
- onRemove: () => actions.remove(p.id)
151
- });
152
- ```
153
-
154
- Each getter is read where its position binds, so a change moves the
155
- positions that read it. The same object serves a client
156
- `<TodoRow row={rowFor(todo)} />`, whose body reads it the same way. A
157
- plain value is right only for what never changes (a constant handler,
158
- a fixed class).
159
-
160
- - **Name it like a props interface**, because it is one (a shared component
161
- takes it as a prop). Handlers are `on` + intent — `onToggle`, `onRemove`,
162
- `onCopy`, `onClearCompleted`; the position names the DOM event, the key
163
- names the meaning, as a component's `onSelect` does. Values are nouns or
164
- adjectives (`done`, `rowClass`, `error`, `busy`); a ref is `ref`. The
165
- runtime reads nothing into the prefix — the position decides what a
166
- property is — but a reader can tell a handler from a value without
167
- opening the type.
168
- - Handlers and refs are read once, when an element binds, and bind as in
169
- client JSX: delegated events delegate, a `[handler, data]` tuple returned
170
- from the fill binds as a tuple, a ref fires once per element. A handler
171
- behind a getter is read once, as `onClick={cond() ? a : b}` is.
172
- - **`$key` is optional.** A call repeated within a render (a component
173
- prop re-evaluates it per position) is one occurrence either way. Add
174
- `$key: t.id` when the fill holds its own state (an edit draft, a signal
175
- created inside) that must follow the entity across refetches and
176
- reorders. Values never depend on it.
177
- - Reserved keys in the returned object: anything beginning with `$`, the
178
- node keys `t` `h` `p` `then`, and `Object`/`Array` prototype member names
179
- (`length`, `map`, …).
76
+ names it ("the \`editor\` template-slot fill").
77
+ - **Place slots as JSX, not calls.** The compiler wraps each prop in a
78
+ getter so the read defers to the slot border; a call form
79
+ (`props.status({ … })`) evaluates its args eagerly in the server
80
+ component's body.
81
+ - **`$key` is optional.** Add it when the fill holds its own state (an edit
82
+ draft, a signal created inside) that must follow the entity across
83
+ refetches and reorders.
84
+ - **An async value crosses with `asyncArg`.**
85
+ `<props.status progress={asyncArg(gen.progress)} />` ships the promise or
86
+ async iterable; the fill's read settles (suspends until the first value).
87
+
88
+ ## Behavior on server markup
89
+
90
+ A handler on a server-rendered element cannot come from the server: a
91
+ server function never runs in the browser. Pick one:
92
+
93
+ - **A form.** A mutation is `<form action={…}>`; it works before
94
+ JavaScript and needs no client code.
95
+ - **A client component that owns the element.** Move the control into a
96
+ slot's fill (`<props.toggle id={t.id} done={t.completed} />`, rendering
97
+ the checkbox on the client).
98
+ - **One delegated listener.** For many identical controls inside server
99
+ markup (a copy button on every code block), place one slot occurrence
100
+ whose component registers a single document listener in `onSettled` and
101
+ finds its target from the event (`closest("button.copy-code")`). Inside a
102
+ live hole this is the shape that keeps the hole streaming: a slot placed
103
+ inside a live hole latches it (`SSR_LIVE_HOLE_LATCHED`, `data.cause`
104
+ `"records"`). `examples/chat`'s Copy button is this shape.
180
105
 
181
106
  ## Shared components
182
107
 
183
- One component can render on both sides: on the server its `row` prop is
184
- the binding slot's return, on the client it is the fill's result. It
185
- cannot tell and need not. Put `$key={props.id}` on the element it renders
186
- (morph identity) — the slot call's own `$key` is a different key for a
187
- different job. Do not read `document`/`window` during render; that is the
188
- ordinary isomorphic rule.
108
+ One component can render on both sides. Put `$key={props.id}` on the
109
+ element it renders (morph identity) — the slot's own `$key` is a different
110
+ key for a different job. Do not read `document`/`window` during render;
111
+ that is the ordinary isomorphic rule.
189
112
 
190
113
  ## Compiling
191
114
 
192
- Server components need the SSR compile with the `serverComponents` compiler
193
- option. With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
115
+ With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
194
116
  { components: true } })` is the turnkey setup (the examples under
195
- `examples/todos-server`, `examples/notes`, `examples/chat`); a hand-rolled
196
- build passes `serverComponents: true` to `@solidjs/compiler` or
197
- `@solidjs/babel-plugin` for the SSR side. Without it a dynamic
198
- `class`/`style` compiles inside the template's quotes, where a slot value
199
- cannot be marked — the `inline` finding below.
200
-
201
- ## Diagnostics
202
-
203
- `BINDING_SLOT_POSITION` (`data.reason`):
204
-
205
- | reason | severity | what happened | fix |
206
- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207
- | `spread` | error (throws) | a slot's return was spread onto an element | name each position |
208
- | `stringified` | warn | template literal / concatenation | whole value at one position |
209
- | `coerced` | warn | comparison, arithmetic, `==` | decide in the fill |
210
- | `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` |
211
- | `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot |
212
- | `server-local` | warn | a server function at `on*`/`ref` | bind a slot property |
213
- | `tuple` | warn | an array at an `on*` position | return the tuple from the fill |
214
- | `reserved-key` | warn | the fill used a reserved key | rename it |
215
- | `arg` | warn | a slot property passed in another slot call's argument (nested in plain objects/arrays; `data.path`) | pass the server's own value, or read it in the fill from client state |
216
- | `prop` | warn | a slot property at a `prop:*` key of a spread | bind the attribute form, or set the property in the fill's ref |
217
- | `fill-shape` | warn (client) | the fill returned a non-object (`null`, array, DOM node, async value, primitive), or the prop read as data is not a function | return a plain object from a function prop |
218
- | `text-shape` | warn (client) | a text position received a non-primitive (object, array, DOM node, function, async value — `data.key`, `data.shape`) | return a string or number; markup goes in a template slot |
219
- | `orphan` | warn (client) | markers for an occurrence that can never bind: `data.why` `"fill"` — no fill for the prop; `"record"` — a called occurrence with no args record | `fill`: pass the prop / match the name on both sides. `record`: not the fill — rebuild client and server together (stale prebundle, cached asset), else report it |
220
-
221
- Every reason but `fill-shape`, `text-shape` and `orphan` comes from the server render.
222
- `orphan` is the one failure this model cannot otherwise show you: the
223
- element is inert — a handler that never fires, a class that never updates —
224
- with no error.
225
-
226
- `STRICT_READ_UNTRACKED` naming a fill ("the \`row\` binding-slot fill",
227
- "the \`comment\` template-slot fill"): a top-level read in its body; use
228
- getters (above).
117
+ `examples/todos-server`, `examples/notes`, `examples/chat`).
package/types/client.d.ts CHANGED
@@ -1,8 +1,8 @@
1
1
  import { getOwner, createComponent, untrack, merge as mergeProps } from "solid-js";
2
- import type { ClientErrorHook } from "solid-js";
2
+ import type { ClientErrorHook, Owner } from "solid-js";
3
3
  import { effect, memo } from "./render.js";
4
4
  import { JSX } from "./jsx.js";
5
- import type { RequestEventLocals, HydrationWriter, HydrationValue } from "./server.js";
5
+ import type { RequestEventLocals, HydrationWriter, HydrationValue, LinkClaimHandler } from "./server.js";
6
6
  import type { TraceContext } from "./trace.js";
7
7
  type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
8
8
  /**
@@ -74,7 +74,7 @@ export interface ResponseStub {
74
74
  * `locals`, whichever entry typed the event.
75
75
  */
76
76
  export { RequestEventLocals } from "./server.js";
77
- export type { HydrationWriter, HydrationValue } from "./server.js";
77
+ export type { HydrationWriter, HydrationValue, LinkClaimHandler } from "./server.js";
78
78
  export interface RequestEvent {
79
79
  request: Request;
80
80
  locals: RequestEventLocals;
@@ -85,14 +85,18 @@ export type { TraceContext, TraceProvider } from "./trace.js";
85
85
  export type { ServerFunction, ServerFunctionMetadata, ServerFunctionRPC } from "./server-functions/shared.js";
86
86
  export declare const waitAsset: (promise: Promise<unknown>) => void;
87
87
  export { DOMWithState, ChildProperties, DOMElements, SVGElements, MathMLElements, VoidElements, RawTextElements, Namespaces, DelegatedEvents } from "./constants.js";
88
+ type CSPNonce = string | {
89
+ script: string | false;
90
+ style: string | false;
91
+ };
88
92
  /** Client stub — hydration bootstrap is a server-only emit. */
89
93
  export declare function generateHydrationScript(_options?: {
90
94
  eventNames?: string[];
91
- nonce?: string;
95
+ nonce?: CSPNonce;
92
96
  }): string;
93
97
  /** Client stub — valid JSX component, renders nothing. */
94
98
  export declare function HydrationScript(_props?: {
95
- nonce?: string;
99
+ nonce?: CSPNonce;
96
100
  eventNames?: string[];
97
101
  }): null;
98
102
  export { effect, memo, untrack, getOwner, createComponent };
@@ -118,6 +122,24 @@ export declare const getHydrationWriter: () => HydrationWriter | undefined;
118
122
  * `globalThis._$HY = { r: { "sq:key": value } }`.
119
123
  */
120
124
  export declare function takeHydrationValue<T = unknown>(key: string): HydrationValue<T> | undefined;
125
+ /**
126
+ * Client stub — a render's link handler is set during server rendering
127
+ * (see the server entry's `setLinkClaim`). Always `false` here, so a router
128
+ * can call it unguarded from isomorphic setup code.
129
+ * @internal
130
+ */
131
+ export declare function setLinkClaim(_handler: LinkClaimHandler | undefined): boolean;
132
+ /**
133
+ * Whether the server render that produced this document ran a link handler
134
+ * (`setLinkClaim`), so its anchors carry the server's link state
135
+ * (`aria-current="page"`, `data-active`) in the HTML. Reads the `links`
136
+ * hydration record the render wrote once; non-destructive, readable before
137
+ * and after hydration. `false` on a page rendered without the router — the
138
+ * absence of link state on an anchor then means nothing, and a link
139
+ * consumer must resolve it itself. Server: `false`.
140
+ * @internal
141
+ */
142
+ export declare function hasServerLinkState(): boolean;
121
143
  /**
122
144
  * Client stub — the trace a request belongs to is a server-side reading
123
145
  * (the incoming `traceparent`, the render's origination); the browser SDK
@@ -181,9 +203,40 @@ export declare function unregisterDelegatedContainer(container: MountableElement
181
203
  export declare function dispatchAsInteraction<T>(e: Event, fn: () => T): T;
182
204
  export declare function getDelegatedRoot(node: MountableElement): MountableElement | undefined;
183
205
  export declare function setProperty(node: Element, name: string, value: any): void;
184
- export declare function registerElementClaim(handler: (element: Element) => void): () => void;
206
+ /**
207
+ * Options for `registerElementClaim`.
208
+ * @internal
209
+ */
210
+ export type ElementClaimOptions = {
211
+ /**
212
+ * Attribute names whose compiler-owned writes re-claim an already claimed
213
+ * element, as plain names: `href` covers the `href` attribute, the
214
+ * `prop:href` property path and the `xlink:href` namespaced path alike.
215
+ * Defaults to `["href", "action"]`. The write sites consult the union of
216
+ * every registered consumer's set.
217
+ */
218
+ attributes?: readonly string[];
219
+ }; /**
220
+ * Register a consumer for compiler-emitted element claims. Compiled DOM
221
+ * output claims navigation-relevant elements (`a[href]`, `form[action]`)
222
+ * once at mount, after their initial attributes are applied — so a handler
223
+ * sees the element's final initial attributes and is told about one mount
224
+ * exactly once. Afterwards compiler-owned writes to an attribute in the
225
+ * consumer's declared set (`options.attributes`, default `href`/`action`;
226
+ * `prop:href` and `xlink:href` map to `href`) re-invoke the handlers — so
227
+ * handlers must be idempotent and must check the element's relevance
228
+ * themselves. Handlers run under the reactive owner the element was created
229
+ * with; scope per-element state and cleanup through your own reactive
230
+ * system. Dormant until registered — without a handler the emitted claims
231
+ * are null checks. Returns an unregister function.
232
+ *
233
+ * Integration plumbing (routers register the consumer); not meant for
234
+ * application code.
235
+ * @internal
236
+ */
237
+ export declare function registerElementClaim(handler: (element: Element) => void, options?: ElementClaimOptions): () => void;
185
238
  export declare function claimElementTree<T extends Node>(root: T): T;
186
- export declare function claimElement<T extends Element>(node: T): T;
239
+ export declare function claimElement<T extends Element>(node: T, owner?: Owner | null): T;
187
240
  export declare function setAttribute(node: Element, name: string, value: string): void;
188
241
  export declare function setAttributeNS(node: Element, namespace: string, name: string, value: string): void;
189
242
  export declare function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
@@ -208,12 +261,22 @@ export declare function style(node: Element, value: {
208
261
  * literal is already the compute's own); a proxy is copied with ONE
209
262
  * `ownKeys` trap (its own trap keeps the key set tracked) plus one tracked
210
263
  * read per key; a clsx-style class array is re-mapped element-wise (className
211
- * allocates for an array anyway; measured at parity). */
264
+ * allocates for an array anyway; measured at parity).
265
+ *
266
+ * The proxy's keys are read with `Reflect.ownKeys` directly — what
267
+ * `sourceKeys(value, SOURCE_PROXY)` resolves to by definition (`leafOf` is
268
+ * the identity for a proxy kind; `leafKeys` answers a proxy with one
269
+ * `ownKeys` trap) — rather than through `sourceKeys`, whose kind argument is
270
+ * a runtime value: calling it here retained the merge/omit view walkers
271
+ * (`collectKeys`, `mergeKeysOf`, `hiddenByAny`, …, ≈ 1.1 KB minified) on
272
+ * every compiled page with a dynamic `class`/`style`, reached by nothing
273
+ * (hydration-split-measured.md, candidate (e)). `spread()` still reads its
274
+ * sources through `sourceKeys`, so a page with an element spread keeps them. */
212
275
  export declare function readShallow(value: unknown): unknown;
213
276
  /** Compiler-emitted primitive; not for hand-written code. @internal */
214
277
  export declare function setStyleProperty(node: Element, name: string, value: any): void;
215
- export declare function spread(node: Element, sources: unknown[], skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string): void;
216
- export declare function spread<T>(node: Element, accessor: T, skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string): void;
278
+ export declare function spread(node: Element, sources: unknown[], skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string, loc?: string): void;
279
+ export declare function spread<T>(node: Element, accessor: T, skipChildren?: Boolean, skip?: (key: string) => boolean, name?: string, loc?: string): void;
217
280
  export declare function dynamicProperty(props: unknown, key: string): unknown;
218
281
  export declare function applyRef<T extends Element = Element>(r: ((element: NoInfer<T>) => void) | ((element: NoInfer<T>) => void)[], element: T): void;
219
282
  export declare function ref(fn: () => ((element: Element) => void) | ((element: Element) => void)[], element: Element): void;
@@ -240,6 +303,13 @@ export declare function insert<T>(parent: MountableElement, accessor: (() => T)
240
303
  * observe runtimes carry it on the node; production ignores it.
241
304
  */
242
305
  name?: string;
306
+ /**
307
+ * Source location of the hole (`src/App.tsx:14:7`, root-relative
308
+ * `file:line:col`) — the compiler's `sourceNames` `locations` kind. Dev
309
+ * and observe runtimes carry it on the node for console reports and
310
+ * diagnostic events; production ignores it.
311
+ */
312
+ loc?: string;
243
313
  }): JSX.Element;
244
314
  export declare function assign(node: Element, props: any, skipChildren?: Boolean, prevProps?: any, skipRef?: Boolean): void;
245
315
  export declare function warmAsset(descriptor: AssetDescriptor): AssetEntry | undefined;
@@ -273,5 +343,37 @@ export declare function getNextMarker(start: Node): [Node, Array<Node>];
273
343
  export declare function getFirstChild(node: any, expectedTag: any): any;
274
344
  export declare function getNextSibling(node: any, expectedTag: any): any;
275
345
  export declare function runHydrationEvents(): void;
346
+ /**
347
+ * Installs the server-component half of hydration — solid's
348
+ * (`enableServerComponentHydration`: the hold, the claim window, fragment
349
+ * ownership, the ledger's published answer) and this runtime's two terms of
350
+ * the claim walk:
351
+ *
352
+ * - `sharedConfig.claimRoots` (ruling 95): a claimed tree isn't always IN
353
+ * the document — a frame adoption whose slot fill resolved async claims
354
+ * its server-rendered range after a pending boundary displaced it
355
+ * (re-inserted on reveal). Such claim scopes declare their roots, and
356
+ * descent from one is as claimed as being connected; fresh clones
357
+ * descend from neither.
358
+ * - The root sweep's frame exclusion (ruling 97): frame regions
359
+ * (`data-fid` — the frame runtime's element brand, an importless
360
+ * duplicate like FRAME_ID_ATTR in frame-client/frame-sink) are another
361
+ * layer's property. Their fills claim through their own windows on their
362
+ * own schedule (a lazy route module may adopt long after the root
363
+ * completes), so collecting them in the ambient sweep only sets up the
364
+ * completion sweep to report legitimately-late claims as unclaimed.
365
+ * Whether the root has frames is one question about the page, not one
366
+ * per keyed node: found once per sweep, containment-tested against the
367
+ * list rather than `closest("[data-fid]")` from every node.
368
+ *
369
+ * The same shape as `hydrate()` — solid's half, then this runtime's — one
370
+ * call for the integration. Before `hydrate()` runs its root sweep (the
371
+ * frames client calls it from `installServerComponents()`, which precedes
372
+ * `hydrate()` in every entry) and again wherever it re-attempts its reveal
373
+ * hook; idempotent. Cross-package wiring; not for application code.
374
+ *
375
+ * @internal
376
+ */
377
+ export declare function installServerComponentHydration(): void;
276
378
  export declare function getHydrationKey(): string | undefined;
277
379
  export declare const RequestContext: unique symbol;
@@ -6,6 +6,7 @@
6
6
  */
7
7
  declare const DOMWithState: Record<string, Record<string, 1 | 2>>;
8
8
  declare const ChildProperties: Set<string>;
9
+ declare const LinkAttributes: Set<string>;
9
10
  declare const $$SLOT: unique symbol;
10
11
  declare const $$HOST: unique symbol;
11
12
  declare const DelegatedEvents: Set<string>;
@@ -18,4 +19,4 @@ declare const DOMElements: Set<string>;
18
19
  declare const COMPOSED_BODY_FRAMING: ReadonlySet<string>;
19
20
  declare function isHttpNavigationTarget(target: string): boolean;
20
21
  declare function isEventName(name: string): boolean;
21
- export { DOMWithState, ChildProperties, DelegatedEvents, SVGElements, MathMLElements, VoidElements, RawTextElements, Namespaces, DOMElements, $$SLOT, $$HOST, COMPOSED_BODY_FRAMING, isHttpNavigationTarget, isEventName };
22
+ export { DOMWithState, ChildProperties, LinkAttributes, DelegatedEvents, SVGElements, MathMLElements, VoidElements, RawTextElements, Namespaces, DOMElements, $$SLOT, $$HOST, COMPOSED_BODY_FRAMING, isHttpNavigationTarget, isEventName };
@@ -10,8 +10,8 @@
10
10
  * `applyInlineStyles`, `findHeadElement`'s attribute-compared lookup and
11
11
  * head.ts's `qualifierValue`), the per-frame flush a pending stylesheet
12
12
  * wakes, and the assets pass over a record (modules, typed preloads, inline
13
- * styles). The eager client keeps the record itself (`chunkToRecords`'
14
- * `assets` case, the host's `seg::assets` accumulate), the pass's walk over
13
+ * styles). The eager client keeps the record itself (the wire's
14
+ * `seg:<k>:assets` record, the host's `seg::assets` accumulate), the pass's walk over
15
15
  * the store, and the reveal's READINESS TERM: a segment whose assets record
16
16
  * carries stylesheets or inline styles while this tier is not resident is
17
17
  * not ready — the server's `<Loading>` fallback stays on screen; the reveal
@@ -1,10 +1,8 @@
1
1
  import { type TierModule } from "./frame-client.js";
2
2
  export { createFrame, createFrameHost, createFrameElement, FRAME_APPLIED_EVENT } from "./frame-client.js";
3
3
  export type { TierModule } from "./frame-client.js";
4
- /** @internal */
5
- export { isAsyncValue } from "./frame-client.js";
6
4
  export { FRAME_STREAM_HEADER, applyFrameResponse, isFrameStreamResponse, createServerComponentHandler } from "./frame-transport.js";
7
- export type { Slot, BindingSlot, SlotOutput, SlotError } from "./server.js";
5
+ export type { Slot } from "./server.js";
8
6
  /**
9
7
  * Client-condition twin of the server face's `asyncArg` (DR-2 value tier):
10
8
  * the identity that types an async value crossing the slot border as its
@@ -20,6 +18,13 @@ export declare function asyncArg<T>(value: PromiseLike<T> | AsyncIterable<T>): T
20
18
  * @experimental
21
19
  */
22
20
  export declare function getFrameHost(): any;
21
+ /**
22
+ * Turn deferred hydration off (or back on) for the frames this client
23
+ * adopts from now on: off, an adopted occurrence mounts in the adoption
24
+ * pass. A test seam for the specs that pin adoption-time ordering.
25
+ * @internal
26
+ */
27
+ export declare function setDeferredHydration(on: boolean): void;
23
28
  /**
24
29
  * Options for `installServerComponents`.
25
30
  * @experimental