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

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.
@@ -16,20 +16,60 @@ function isDeferredBody(value) {
16
16
  if (typeof v[Symbol.asyncIterator] === "function") return true;
17
17
  return typeof v[Symbol.iterator] === "function" && !Array.isArray(value) && !(value instanceof Map) && !(value instanceof Set) && !ArrayBuffer.isView(value);
18
18
  }
19
- function observeCall(id, method, args) {
19
+ function observeCall(id, method, args, name) {
20
20
  const channel = records();
21
- if (channel === undefined || !channel.observed("call")) return undefined;
21
+ if (channel === undefined) return undefined;
22
+ const observedCall = channel.observed("call");
23
+ const observedRequest = channel.observed("request");
24
+ if (!observedCall && !observedRequest) return undefined;
22
25
  const at = performance.now();
26
+ const bodies = channel.observed("call", "bodies");
27
+ const requestBodies = bodies || channel.observed("request", "bodies");
23
28
  const origin = currentOrigin();
29
+ const live = {
30
+ args
31
+ };
24
32
  let response;
33
+ let clone;
25
34
  let settled = false;
26
35
  return {
36
+ request(url, init) {
37
+ const at = observedRequest ? performance.now() : 0;
38
+ if (requestBodies) {
39
+ const request = reconstructRequest(url, init);
40
+ if (request !== undefined) live.request = request;
41
+ }
42
+ if (!observedRequest) return;
43
+ const event = {
44
+ side: "client",
45
+ id,
46
+ at,
47
+ method
48
+ };
49
+ if (name !== undefined) event.name = name;
50
+ if (origin !== undefined) event.origin = origin;
51
+ channel.emit("request", event, live);
52
+ },
27
53
  response(r) {
28
54
  response = r;
55
+ if (!bodies) return;
56
+ const type = r.headers.get("content-type");
57
+ if (type !== null && type.startsWith("text/event-stream")) return;
58
+ try {
59
+ clone = r.clone();
60
+ } catch {}
29
61
  },
30
62
  settle(outcome, value) {
31
63
  if (settled) return;
32
64
  settled = true;
65
+ const deferred = outcome === "ok" && isDeferredBody(value);
66
+ if (outcome === "ok") live.result = value;else live.error = value;
67
+ if (deferred && clone !== undefined) {
68
+ cancelBody(clone);
69
+ clone = undefined;
70
+ }
71
+ if (clone !== undefined) live.response = clone;else if (response !== undefined) live.response = response;
72
+ if (!observedCall) return;
33
73
  const event = {
34
74
  id,
35
75
  at,
@@ -37,20 +77,35 @@ function observeCall(id, method, args) {
37
77
  method,
38
78
  outcome
39
79
  };
80
+ if (name !== undefined) event.name = name;
40
81
  if (response !== undefined) event.status = response.status;
41
82
  if (origin !== undefined) event.origin = origin;
42
- const live = {
43
- args
44
- };
45
- if (response !== undefined) live.response = response;
46
- if (outcome === "ok") {
47
- live.result = value;
48
- if (isDeferredBody(value)) event.deferred = true;
49
- } else live.error = value;
83
+ if (deferred) event.deferred = true;
50
84
  channel.emit("call", event, live);
51
85
  }
52
86
  };
53
87
  }
88
+ function reconstructRequest(url, init) {
89
+ try {
90
+ return new Request(new URL(url, globalThis.location?.href), {
91
+ ...init,
92
+ body: reconstructableBody(init.body)
93
+ });
94
+ } catch {
95
+ return undefined;
96
+ }
97
+ }
98
+ function reconstructableBody(body) {
99
+ if (body == null || typeof body === "string") return body;
100
+ if (body instanceof URLSearchParams || typeof FormData !== "undefined" && body instanceof FormData || typeof Blob !== "undefined" && body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return body;
101
+ return undefined;
102
+ }
103
+ function cancelBody(response) {
104
+ try {
105
+ const body = response.body;
106
+ if (body !== null) body.cancel().catch(() => {});
107
+ } catch {}
108
+ }
54
109
 
55
110
  const SERVER_FUNCTION_METADATA = Symbol.for("solid.ServerFunctionMetadata");
56
111
  function getServerFunctionMetadata(fn) {
@@ -751,6 +806,7 @@ async function decodeResponsePayload(response, codecOptions) {
751
806
  };
752
807
  }
753
808
 
809
+ const CALL_OBSERVATION = Symbol("solid.CallObservation");
754
810
  const config = {
755
811
  endpoint: "/_server",
756
812
  fetch: undefined,
@@ -843,6 +899,13 @@ async function createRequest(base, id, options, meta) {
843
899
  if (wire.position !== undefined) headers[LAST_EVENT_ID_HEADER] = wire.position;
844
900
  if (wire.headers) Object.assign(headers, wire.headers);
845
901
  }
902
+ const observation = options[CALL_OBSERVATION] ;
903
+ if (observation) {
904
+ options = {
905
+ ...options
906
+ };
907
+ delete options[CALL_OBSERVATION];
908
+ }
846
909
  const flightSources = getFlightDataSourceIds();
847
910
  if (flightSources.length > 0 && !isReadCall(options)) {
848
911
  headers[SINGLE_FLIGHT_HEADER] = flightSources.join(",");
@@ -867,6 +930,7 @@ async function createRequest(base, id, options, meta) {
867
930
  }
868
931
  init = prepared || init;
869
932
  }
933
+ if (observation) observation.request(base, init);
870
934
  const send = config.fetch || fetch;
871
935
  return send(base, init);
872
936
  }
@@ -931,7 +995,7 @@ async function initializeResponse(base, id, options, args, meta) {
931
995
  }, meta);
932
996
  }
933
997
  async function observedFetch(base, id, options, args, meta, callArgs = args) {
934
- const observation = observeCall(id, options.method && options.method.toUpperCase() === "GET" ? "GET" : "POST", callArgs);
998
+ const observation = observeCall(id, options.method && options.method.toUpperCase() === "GET" ? "GET" : "POST", callArgs, meta && meta.name);
935
999
  if (!observation) return dispatchServerFunction(base, id, options, args, meta, callArgs);
936
1000
  let result;
937
1001
  try {
@@ -955,6 +1019,10 @@ async function dispatchServerFunction(base, id, options, args, meta, callArgs =
955
1019
  ...options,
956
1020
  signal: controller.signal
957
1021
  };
1022
+ if (observation) options = {
1023
+ ...options,
1024
+ [CALL_OBSERVATION]: observation
1025
+ };
958
1026
  const response = await initializeResponse(base, id, options, args, meta);
959
1027
  if (observation) observation.response(response);
960
1028
  if (handler) {
@@ -1,5 +1,5 @@
1
- import { OBSERVE, sharedConfig, getOwner, DEV as DEV$1 } from 'solid-js';
2
- import { reportServerError } from 'solid-js/internal';
1
+ import { OBSERVE, getOwner, DEV as DEV$1 } from 'solid-js';
2
+ import { sharedConfig, reportServerError } from 'solid-js/internal';
3
3
 
4
4
  const COMPOSED_BODY_FRAMING = /*#__PURE__*/new Set(["content-length", "content-encoding", "transfer-encoding"]);
5
5
  function isHttpNavigationTarget(target) {
@@ -23,6 +23,15 @@ const REVALIDATE_HEADER = "X-Revalidate";
23
23
  const RESPONSE_HEADER_VALUE_LIMIT = 4096;
24
24
  const NULL_BODY_STATUSES = new Set([204, 205, 304]);
25
25
 
26
+ const REQUEST_ERROR_HOOK = Symbol.for("solid-js/server/request-error-hook");
27
+ function hooks() {
28
+ const g = globalThis;
29
+ return g[REQUEST_ERROR_HOOK] || (g[REQUEST_ERROR_HOOK] = new WeakMap());
30
+ }
31
+ function requestErrorHook(event) {
32
+ return event === undefined ? undefined : hooks().get(event);
33
+ }
34
+
26
35
  const PROVIDER = Symbol.for("solid-js/observe/server/provider");
27
36
  function currentProvider() {
28
37
  if (OBSERVE === undefined) return undefined;
@@ -940,7 +949,21 @@ function errorText(error) {
940
949
  typeof setImmediate === "function" ? setImmediate : fn => setTimeout(fn, 0);
941
950
  const RequestContext = Symbol.for("solid.RequestContext");
942
951
  function getRequestEvent() {
943
- return globalThis[RequestContext] ? globalThis[RequestContext].getStore() || sharedConfig.context && sharedConfig.context.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.") : undefined;
952
+ const store = globalThis[RequestContext];
953
+ if (!store) return undefined;
954
+ const event = store.getStore();
955
+ if (event) return event;
956
+ const ctx = renderContextOf(getOwner());
957
+ return ctx && ctx.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.");
958
+ }
959
+ const RENDER_ROOTS = Symbol.for("@solidjs/web/render-roots");
960
+ function renderContextOf(owner) {
961
+ const roots = globalThis[RENDER_ROOTS];
962
+ if (!roots) return undefined;
963
+ for (; owner; owner = owner._parent) {
964
+ const context = roots.get(owner);
965
+ if (context) return context;
966
+ }
944
967
  }
945
968
  function peekRequestEvent() {
946
969
  const store = globalThis[RequestContext];
@@ -1564,6 +1587,7 @@ function createServerReference({
1564
1587
  evt.serverOnly = true;
1565
1588
  const scope = run => provideEvent(evt, run);
1566
1589
  const wrap = resolveWrapInvocation(config.wrapInvocation);
1590
+ const hook = requestErrorHook(ogEvt);
1567
1591
  let result = provideEventOnce(provideEvent, evt, () => {
1568
1592
  const run = () => fn.apply(thisArg, args);
1569
1593
  return observeInvocation({
@@ -1576,7 +1600,7 @@ function createServerReference({
1576
1600
  args,
1577
1601
  event: evt,
1578
1602
  direct: true
1579
- }) : run(), id));
1603
+ }) : run(), id, hook));
1580
1604
  });
1581
1605
  result = scopeDeferredResult(result, scope);
1582
1606
  const transform = config.transformDirectResult;
@@ -2546,14 +2570,14 @@ function currentEvent() {
2546
2570
  const store = globalThis[RequestContext];
2547
2571
  return store ? store.getStore() : undefined;
2548
2572
  }
2549
- function reportDirectFailure(run, id) {
2573
+ function reportDirectFailure(run, id, hook) {
2550
2574
  const report = error => {
2551
2575
  reportServerError(error, {
2552
2576
  kind: "server-function",
2553
2577
  handling: "thrown",
2554
2578
  functionId: id,
2555
2579
  direct: true
2556
- }, null);
2580
+ }, null, hook);
2557
2581
  throw error;
2558
2582
  };
2559
2583
  let result;
@@ -1,5 +1,5 @@
1
- import { sharedConfig } from 'solid-js';
2
- import { reportServerError } from 'solid-js/internal';
1
+ import { getOwner } from 'solid-js';
2
+ import { sharedConfig, reportServerError } from 'solid-js/internal';
3
3
 
4
4
  const COMPOSED_BODY_FRAMING = /*#__PURE__*/new Set(["content-length", "content-encoding", "transfer-encoding"]);
5
5
  function isHttpNavigationTarget(target) {
@@ -23,6 +23,15 @@ const REVALIDATE_HEADER = "X-Revalidate";
23
23
  const RESPONSE_HEADER_VALUE_LIMIT = 4096;
24
24
  const NULL_BODY_STATUSES = new Set([204, 205, 304]);
25
25
 
26
+ const REQUEST_ERROR_HOOK = Symbol.for("solid-js/server/request-error-hook");
27
+ function hooks() {
28
+ const g = globalThis;
29
+ return g[REQUEST_ERROR_HOOK] || (g[REQUEST_ERROR_HOOK] = new WeakMap());
30
+ }
31
+ function requestErrorHook(event) {
32
+ return event === undefined ? undefined : hooks().get(event);
33
+ }
34
+
26
35
  const TRACEPARENT = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})(-.*)?$/;
27
36
  const ZERO_TRACE = "00000000000000000000000000000000";
28
37
  const ZERO_SPAN = "0000000000000000";
@@ -876,7 +885,21 @@ async function decodeResponsePayload(response, codecOptions) {
876
885
  typeof setImmediate === "function" ? setImmediate : fn => setTimeout(fn, 0);
877
886
  const RequestContext = Symbol.for("solid.RequestContext");
878
887
  function getRequestEvent() {
879
- return globalThis[RequestContext] ? globalThis[RequestContext].getStore() || sharedConfig.context && sharedConfig.context.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.") : undefined;
888
+ const store = globalThis[RequestContext];
889
+ if (!store) return undefined;
890
+ const event = store.getStore();
891
+ if (event) return event;
892
+ const ctx = renderContextOf(getOwner());
893
+ return ctx && ctx.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.");
894
+ }
895
+ const RENDER_ROOTS = Symbol.for("@solidjs/web/render-roots");
896
+ function renderContextOf(owner) {
897
+ const roots = globalThis[RENDER_ROOTS];
898
+ if (!roots) return undefined;
899
+ for (; owner; owner = owner._parent) {
900
+ const context = roots.get(owner);
901
+ if (context) return context;
902
+ }
880
903
  }
881
904
  function peekRequestEvent() {
882
905
  const store = globalThis[RequestContext];
@@ -1482,6 +1505,7 @@ function createServerReference({
1482
1505
  evt.serverOnly = true;
1483
1506
  const scope = run => provideEvent(evt, run);
1484
1507
  const wrap = resolveWrapInvocation(config.wrapInvocation);
1508
+ const hook = requestErrorHook(ogEvt);
1485
1509
  let result = provideEventOnce(provideEvent, evt, () => {
1486
1510
  const run = () => fn.apply(thisArg, args);
1487
1511
  return observeInvocation({
@@ -1494,7 +1518,7 @@ function createServerReference({
1494
1518
  args,
1495
1519
  event: evt,
1496
1520
  direct: true
1497
- }) : run(), id));
1521
+ }) : run(), id, hook));
1498
1522
  });
1499
1523
  result = scopeDeferredResult(result, scope);
1500
1524
  const transform = config.transformDirectResult;
@@ -2464,14 +2488,14 @@ function currentEvent() {
2464
2488
  const store = globalThis[RequestContext];
2465
2489
  return store ? store.getStore() : undefined;
2466
2490
  }
2467
- function reportDirectFailure(run, id) {
2491
+ function reportDirectFailure(run, id, hook) {
2468
2492
  const report = error => {
2469
2493
  reportServerError(error, {
2470
2494
  kind: "server-function",
2471
2495
  handling: "thrown",
2472
2496
  functionId: id,
2473
2497
  direct: true
2474
- }, null);
2498
+ }, null, hook);
2475
2499
  throw error;
2476
2500
  };
2477
2501
  let result;
@@ -1,5 +1,5 @@
1
- import { OBSERVE, sharedConfig, getOwner } from 'solid-js';
2
- import { reportServerError } from 'solid-js/internal';
1
+ import { OBSERVE, getOwner } from 'solid-js';
2
+ import { sharedConfig, reportServerError } from 'solid-js/internal';
3
3
 
4
4
  const COMPOSED_BODY_FRAMING = /*#__PURE__*/new Set(["content-length", "content-encoding", "transfer-encoding"]);
5
5
  function isHttpNavigationTarget(target) {
@@ -23,6 +23,15 @@ const REVALIDATE_HEADER = "X-Revalidate";
23
23
  const RESPONSE_HEADER_VALUE_LIMIT = 4096;
24
24
  const NULL_BODY_STATUSES = new Set([204, 205, 304]);
25
25
 
26
+ const REQUEST_ERROR_HOOK = Symbol.for("solid-js/server/request-error-hook");
27
+ function hooks() {
28
+ const g = globalThis;
29
+ return g[REQUEST_ERROR_HOOK] || (g[REQUEST_ERROR_HOOK] = new WeakMap());
30
+ }
31
+ function requestErrorHook(event) {
32
+ return event === undefined ? undefined : hooks().get(event);
33
+ }
34
+
26
35
  const PROVIDER = Symbol.for("solid-js/observe/server/provider");
27
36
  function currentProvider() {
28
37
  if (OBSERVE === undefined) return undefined;
@@ -918,7 +927,21 @@ function errorText(error) {
918
927
  typeof setImmediate === "function" ? setImmediate : fn => setTimeout(fn, 0);
919
928
  const RequestContext = Symbol.for("solid.RequestContext");
920
929
  function getRequestEvent() {
921
- return globalThis[RequestContext] ? globalThis[RequestContext].getStore() || sharedConfig.context && sharedConfig.context.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.") : undefined;
930
+ const store = globalThis[RequestContext];
931
+ if (!store) return undefined;
932
+ const event = store.getStore();
933
+ if (event) return event;
934
+ const ctx = renderContextOf(getOwner());
935
+ return ctx && ctx.event || console.warn("RequestEvent is missing. This is most likely due to accessing `getRequestEvent` non-managed async scope in a partially polyfilled environment. Try moving it above all `await` calls.");
936
+ }
937
+ const RENDER_ROOTS = Symbol.for("@solidjs/web/render-roots");
938
+ function renderContextOf(owner) {
939
+ const roots = globalThis[RENDER_ROOTS];
940
+ if (!roots) return undefined;
941
+ for (; owner; owner = owner._parent) {
942
+ const context = roots.get(owner);
943
+ if (context) return context;
944
+ }
922
945
  }
923
946
  function peekRequestEvent() {
924
947
  const store = globalThis[RequestContext];
@@ -1534,6 +1557,7 @@ function createServerReference({
1534
1557
  evt.serverOnly = true;
1535
1558
  const scope = run => provideEvent(evt, run);
1536
1559
  const wrap = resolveWrapInvocation(config.wrapInvocation);
1560
+ const hook = requestErrorHook(ogEvt);
1537
1561
  let result = provideEventOnce(provideEvent, evt, () => {
1538
1562
  const run = () => fn.apply(thisArg, args);
1539
1563
  return observeInvocation({
@@ -1546,7 +1570,7 @@ function createServerReference({
1546
1570
  args,
1547
1571
  event: evt,
1548
1572
  direct: true
1549
- }) : run(), id));
1573
+ }) : run(), id, hook));
1550
1574
  });
1551
1575
  result = scopeDeferredResult(result, scope);
1552
1576
  const transform = config.transformDirectResult;
@@ -2516,14 +2540,14 @@ function currentEvent() {
2516
2540
  const store = globalThis[RequestContext];
2517
2541
  return store ? store.getStore() : undefined;
2518
2542
  }
2519
- function reportDirectFailure(run, id) {
2543
+ function reportDirectFailure(run, id, hook) {
2520
2544
  const report = error => {
2521
2545
  reportServerError(error, {
2522
2546
  kind: "server-function",
2523
2547
  handling: "thrown",
2524
2548
  functionId: id,
2525
2549
  direct: true
2526
- }, null);
2550
+ }, null, hook);
2527
2551
  throw error;
2528
2552
  };
2529
2553
  let result;
@@ -0,0 +1,206 @@
1
+ # Writing Solid server components with slots
2
+
3
+ A Solid server component is a `"use server"` function that returns a
4
+ 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
+
11
+ ## Where things go
12
+
13
+ > **An element lives where the data that creates it lives.**
14
+
15
+ - 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 an **attribute 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 **markup slot**.
23
+
24
+ When the client confirms an optimistic entity and the server renders it, the
25
+ row _becomes_ server markup; `$key` on the element reconciles the two.
26
+
27
+ ## The two kinds of slot
28
+
29
+ ```tsx
30
+ import type { AttributeSlot, Slot } from "@solidjs/web/frames";
31
+
32
+ interface TodosProps {
33
+ pending: Slot; // markup: the client returns JSX
34
+ row: AttributeSlot<{ id: string; completed: boolean }, RowBehavior>; // attributes: the client returns an object
35
+ filters: AttributeSlot<{}, FilterBehavior>; // no args: called bare
36
+ }
37
+ ```
38
+
39
+ A **markup slot** is placed as an element: `<props.pending />`. The client
40
+ owns those nodes.
41
+
42
+ An **attribute slot** is _called_ once per data context and its properties
43
+ are _bound_ at positions of the server's own template:
44
+
45
+ ```tsx
46
+ export async function todoList() {
47
+ "use server";
48
+ 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
+ };
69
+ }
70
+ ```
71
+
72
+ The client passes the fill — a function of the args that returns the object:
73
+
74
+ ```tsx
75
+ <Todos row={rowFor} filters={() => ({ all: filter() === "all", … })} pending={() => <For each={adds}>{…}</For>} />
76
+ ```
77
+
78
+ ## The one rule for attribute slots
79
+
80
+ > **A slot property is a JSX attribute value, whole, and nothing else.**
81
+
82
+ Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
83
+ `title={row.error}`), a class name inside object form
84
+ (`class={{ completed: row.done }}`), the whole `class`/`style`
85
+ (`class={row.rowClass}`), a style property (`style={{ opacity: row.fade }}`),
86
+ an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element
87
+ with a spread too (`<button {...rest} onClick={row.go} />` — the last
88
+ source that has the key wins, `undefined` included, as the client's
89
+ spread reads it). Not a `prop:*`
90
+ property, not a text child, not inside another slot call's args (nested in
91
+ plain objects and arrays included). Reserved keys the fill must not use:
92
+ keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`,
93
+ `constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map`
94
+ included) is a plain property.
95
+
96
+ The server **does not have the value** — on the stream face a property read
97
+ is a stand-in with no value, on the document face only the initial one — so
98
+ nothing can be computed from it on the server. Every one of these is wrong:
99
+
100
+ | Wrong | Why | Write instead |
101
+ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
102
+ | ``class={`todo ${row.done}`}`` | stringified: not the whole value | `class={{ todo: true, completed: row.done }}` or return `rowClass` from the fill |
103
+ | `row.count > 3 ? "a" : "b"` | comparison on a stand-in | decide in the fill; return the decided value |
104
+ | `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 markup slot |
105
+ | `<strong>{row.count}</strong>` | text is not a bindable position yet | a markup slot for the text |
106
+ | `format(row.title)` (a server helper) | the helper receives a stand-in | do the formatting in the fill |
107
+ | `<li {...row}>` | spread: the template must show what the client owns | name each position |
108
+ | `onClick={() => …}` on a server element | a server function can never run in the browser | bind a slot property or a form `action` |
109
+
110
+ Every case except truthiness is a dev finding (`ATTRIBUTE_SLOT_POSITION`)
111
+ and renders **nothing on either face**, so it shows on the first render.
112
+ Truthiness has no runtime hook: if a retry button appears on every row, this
113
+ is why.
114
+
115
+ ## Writing the fill
116
+
117
+ - **Values as getters, handlers as plain closures** when a shared client
118
+ component also consumes the object (the usual case):
119
+
120
+ ```tsx
121
+ const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({
122
+ get rowClass() {
123
+ return { todo: true, completed: done(p.id, p.completed), pending: !!intent.byId[p.id] };
124
+ },
125
+ get done() {
126
+ return done(p.id, p.completed);
127
+ },
128
+ get removed() {
129
+ return removed(p.id);
130
+ },
131
+ onToggle: e => actions.toggle(p.id, e.currentTarget.checked),
132
+ onRemove: () => actions.remove(p.id)
133
+ });
134
+ ```
135
+
136
+ A client `<TodoRow row={rowFor(todo)} />` reads `props.row.onToggle` once,
137
+ untracked, in its body; a plain-value fill would do its reactive reads
138
+ there and never update (`STRICT_READ_UNTRACKED` names it). Getters move
139
+ each read to the position that binds it. Plain values are fine when only
140
+ the server template reads the object.
141
+
142
+ - **Name it like a props interface**, because it is one (a shared component
143
+ takes it as a prop). Handlers are `on` + intent — `onToggle`, `onRemove`,
144
+ `onCopy`, `onClearCompleted`; the position names the DOM event, the key
145
+ names the meaning, as a component's `onSelect` does. Values are nouns or
146
+ adjectives (`done`, `rowClass`, `error`, `busy`); a ref is `ref`. The
147
+ runtime reads nothing into the prefix — the position decides what a
148
+ property is — but a reader can tell a handler from a value without
149
+ opening the type.
150
+ - The fill runs once per occurrence (one call); each bound position tracks
151
+ its own reads; handlers dispatch to the fill's _current_ handler; a ref
152
+ fires once per element.
153
+ - **`$key` is optional.** A call repeated within a render (a component
154
+ prop re-evaluates it per position) is one occurrence either way. Add
155
+ `$key: t.id` when the fill holds its own state (an edit draft, a signal
156
+ created inside) that must follow the entity across refetches and
157
+ reorders. Values never depend on it.
158
+ - Reserved keys in the returned object: anything beginning with `$`, the
159
+ node keys `t` `h` `p` `then`, and `Object`/`Array` prototype member names
160
+ (`length`, `map`, …).
161
+
162
+ ## Shared components
163
+
164
+ One component can render on both sides: on the server its `row` prop is
165
+ the attribute slot's return, on the client it is the fill's result. It
166
+ cannot tell and need not. Put `$key={props.id}` on the element it renders
167
+ (morph identity) — the slot call's own `$key` is a different key for a
168
+ different job. Do not read `document`/`window` during render; that is the
169
+ ordinary isomorphic rule.
170
+
171
+ ## Compiling
172
+
173
+ Server components need the SSR compile with the `serverComponents` compiler
174
+ option. With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions:
175
+ { components: true } })` is the turnkey setup (the examples under
176
+ `examples/todos-server`, `examples/notes`, `examples/chat`); a hand-rolled
177
+ build passes `serverComponents: true` to `@solidjs/compiler` or
178
+ `@solidjs/babel-plugin` for the SSR side. Without it a dynamic
179
+ `class`/`style` compiles inside the template's quotes, where a slot value
180
+ cannot be marked — the `inline` finding below.
181
+
182
+ ## Diagnostics
183
+
184
+ `ATTRIBUTE_SLOT_POSITION` (`data.reason`):
185
+
186
+ | reason | severity | what happened | fix |
187
+ | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
188
+ | `spread` | error (throws) | a slot's return was spread onto an element | name each position |
189
+ | `stringified` | warn | template literal / concatenation | whole value at one position |
190
+ | `coerced` | warn | comparison, arithmetic, `==` | decide in the fill |
191
+ | `text` | warn | placed as a text child | markup slot |
192
+ | `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` |
193
+ | `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot |
194
+ | `server-local` | warn | a server function at `on*`/`ref` | bind a slot property |
195
+ | `reserved-key` | warn | the fill used a reserved key | rename it |
196
+ | `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 |
197
+ | `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 |
198
+ | `fill-shape` | warn (client) | the fill returned a non-object (`null`, array, DOM node, primitive), or the prop read as data is not a function | return a plain object from a function prop |
199
+ | `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 |
200
+
201
+ Every reason but `fill-shape` and `orphan` comes from the server render.
202
+ `orphan` is the one failure this model cannot otherwise show you: the
203
+ element is inert — a handler that never fires, a class that never updates —
204
+ with no error.
205
+
206
+ `STRICT_READ_UNTRACKED` inside a fill: use getters (above).
package/types/client.d.ts CHANGED
@@ -2,7 +2,7 @@ import { getOwner, createComponent, untrack, merge as mergeProps } from "solid-j
2
2
  import type { ClientErrorHook } from "solid-js";
3
3
  import { effect, memo } from "./render.js";
4
4
  import { JSX } from "./jsx.js";
5
- import type { RequestEventLocals } from "./server.js";
5
+ import type { RequestEventLocals, HydrationWriter, HydrationValue } from "./server.js";
6
6
  import type { TraceContext } from "./trace.js";
7
7
  type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
8
8
  /**
@@ -74,12 +74,13 @@ 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
78
  export interface RequestEvent {
78
79
  request: Request;
79
80
  locals: RequestEventLocals;
80
81
  }
81
82
  export type { CookieOptions } from "./cookies.js";
82
- export type { CallEvent, CallListener, CallLive, FrameAppliedEvent, FrameEvent, FrameListener, FrameLive, FrameProducedEvent, InvocationEvent, InvocationListener, InvocationLive, RenderEvent, RenderListener, RenderLive } from "./observe.js";
83
+ export type { CallEvent, CallListener, CallLive, CallRequestEvent, CallRequestListener, FrameAppliedEvent, FrameEvent, FrameListener, FrameLive, FrameProducedEvent, InvocationEvent, InvocationListener, InvocationLive, RenderEvent, RenderListener, RenderLive, RenderRoute } from "./observe.js";
83
84
  export type { TraceContext, TraceProvider } from "./trace.js";
84
85
  export type { ServerFunction, ServerFunctionMetadata, ServerFunctionRPC } from "./server-functions/shared.js";
85
86
  export declare const waitAsset: (promise: Promise<unknown>) => void;
@@ -103,6 +104,20 @@ export { effect, memo, untrack, getOwner, createComponent };
103
104
  */
104
105
  export { mergeProps };
105
106
  export declare const getRequestEvent: () => RequestEvent | undefined;
107
+ /** Client stub — values are written by the server render. See the server entry. */
108
+ export declare const getHydrationWriter: () => HydrationWriter | undefined;
109
+ /**
110
+ * Removes and returns the value the server render wrote under `key` with
111
+ * `getHydrationWriter().write(key, value)`, or `undefined` when the page
112
+ * carries none (or it was already taken). A written promise arrives as
113
+ * `"pending"` until its settlement streams in, then as `"resolved"` or
114
+ * `"rejected"`. Readable before `hydrate()` runs and after hydration has
115
+ * ended. Server: `undefined`.
116
+ *
117
+ * The page's values live on `globalThis._$HY.r`; a test seeds them with
118
+ * `globalThis._$HY = { r: { "sq:key": value } }`.
119
+ */
120
+ export declare function takeHydrationValue<T = unknown>(key: string): HydrationValue<T> | undefined;
106
121
  /**
107
122
  * Client stub — the trace a request belongs to is a server-side reading
108
123
  * (the incoming `traceparent`, the render's origination); the browser SDK
@@ -1,6 +1,6 @@
1
1
  export { createFrame, createFrameHost, createFrameElement, FRAME_APPLIED_EVENT } from "./frame-client.js";
2
2
  export { FRAME_STREAM_HEADER, FRAME_HAVE_HEADER, FRAME_HAVE_BUDGET, applyFrameResponse, isFrameStreamResponse, createServerComponentHandler } from "./frame-transport.js";
3
- export type { Slot } from "./server.js";
3
+ export type { Slot, AttributeSlot } from "./server.js";
4
4
  /**
5
5
  * Client-condition twin of the server face's `asyncArg` (DR-2 value tier):
6
6
  * the identity that types an async value crossing the slot border as its