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

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 (59) hide show
  1. package/dist/server.dev.js +317 -185
  2. package/dist/server.js +298 -161
  3. package/dist/server.observe.js +299 -171
  4. package/dist/web.dev.js +207 -189
  5. package/dist/web.js +180 -178
  6. package/dist/web.observe.js +180 -180
  7. package/frames/dist/assets.js +92 -0
  8. package/frames/dist/bind.dev.js +326 -0
  9. package/frames/dist/bind.js +295 -0
  10. package/frames/dist/client.dev.js +665 -1114
  11. package/frames/dist/client.js +630 -1087
  12. package/frames/dist/client.observe.js +629 -1087
  13. package/frames/dist/regions.js +130 -0
  14. package/frames/dist/server.dev.js +400 -201
  15. package/frames/dist/server.js +397 -198
  16. package/frames/dist/server.observe.js +397 -198
  17. package/frames/dist/trace.js +45 -0
  18. package/frames/dist/wire.js +133 -0
  19. package/package.json +30 -4
  20. package/performance-tracks/dist/performance-tracks.dev.js +2 -1
  21. package/performance-tracks/dist/performance-tracks.observe.js +2 -1
  22. package/performance-tracks/types/index.d.ts +8 -6
  23. package/serialization/dist/decode.js +38 -9
  24. package/serialization/dist/serialization.js +40 -11
  25. package/serialization/types/serializer-decode.d.ts +24 -2
  26. package/server-functions/dist/client.dev.js +101 -62
  27. package/server-functions/dist/client.js +101 -62
  28. package/server-functions/dist/client.observe.js +101 -62
  29. package/server-functions/dist/server.dev.js +178 -67
  30. package/server-functions/dist/server.js +178 -67
  31. package/server-functions/dist/server.observe.js +178 -67
  32. package/skills/server-components/SKILL.md +65 -43
  33. package/types/client.d.ts +120 -8
  34. package/types/constants.d.ts +3 -1
  35. package/types/diagnostics.d.ts +8 -0
  36. package/types/frames/assets-tier.d.ts +78 -0
  37. package/types/frames/bind-tier.d.ts +60 -0
  38. package/types/frames/client.d.ts +37 -3
  39. package/types/frames/frame-client.d.ts +249 -78
  40. package/types/frames/frame-container-plugin.d.ts +2 -2
  41. package/types/frames/frame-sink.d.ts +33 -0
  42. package/types/frames/frame-transport.d.ts +66 -18
  43. package/types/frames/regions-tier.d.ts +45 -0
  44. package/types/frames/serializer-decode.d.ts +24 -2
  45. package/types/frames/server.d.ts +33 -9
  46. package/types/frames/trace-tier.d.ts +2 -0
  47. package/types/frames/wire-tier.d.ts +116 -0
  48. package/types/head.d.ts +1 -0
  49. package/types/index.d.ts +61 -16
  50. package/types/index.server.d.ts +3 -18
  51. package/types/jsx.d.ts +4 -13
  52. package/types/observe.d.ts +4 -2
  53. package/types/response.d.ts +26 -4
  54. package/types/serializer-decode.d.ts +24 -2
  55. package/types/server-functions/client.d.ts +30 -0
  56. package/types/server-functions/registry.d.ts +4 -1
  57. package/types/server-functions/shared.d.ts +12 -8
  58. package/types/server-mock.d.ts +22 -3
  59. package/types/server.d.ts +119 -17
@@ -372,7 +372,7 @@ function serializeCookie(name, value, options = {}) {
372
372
  return cookie;
373
373
  }
374
374
  const FLASH_COOKIE = "flash";
375
- const FLASH_MATCHER = new RegExp(`(?:^|;\\s*)${FLASH_COOKIE}=([^;]+)`);
375
+ const FLASH_MATCHER = /(?:^|;\s*)flash=([^;]+)/;
376
376
  function hasFlashCookie(cookieHeader) {
377
377
  return !!cookieHeader && FLASH_MATCHER.test(cookieHeader);
378
378
  }
@@ -690,7 +690,7 @@ async function extractBody(source, codecOptions, wire) {
690
690
  const format = source.headers.get(BODY_FORMAT_HEADER);
691
691
  switch (true) {
692
692
  case format === BodyFormat.Serialized:
693
- return await deserializeStream(source, codecOptions);
693
+ return await deserializeStream(source, codecOptions, wire);
694
694
  case format === BodyFormat.Json:
695
695
  return JSON.parse(await source.text());
696
696
  case format === BodyFormat.String:
@@ -716,26 +716,42 @@ async function extractBody(source, codecOptions, wire) {
716
716
  return undefined;
717
717
  }
718
718
  function createChunk(data) {
719
- const encoder = new TextEncoder();
720
- const encodeData = encoder.encode(data);
719
+ const encodeData = CHUNK_ENCODER.encode(data);
721
720
  const bytes = encodeData.length;
721
+ if (bytes > MAX_CHUNK_BYTES) {
722
+ throw new RangeError("Server function chunk is too large to frame.");
723
+ }
722
724
  const chunk = new Uint8Array(12 + bytes);
723
- chunk.set(encoder.encode(`;0x${bytes.toString(16).padStart(8, "0")};`));
725
+ chunk.set(CHUNK_ENCODER.encode(`;0x${bytes.toString(16).padStart(8, "0")};`));
724
726
  chunk.set(encodeData, 12);
725
727
  return chunk;
726
728
  }
729
+ const CHUNK_ENCODER = /* @__PURE__ */new TextEncoder();
730
+ const CHUNK_DECODER = /* @__PURE__ */new TextDecoder("utf-8", {
731
+ fatal: true
732
+ });
733
+ const MAX_CHUNK_BYTES = 0xffffffff;
734
+ const RETAINED_STORE_BYTES = 64 * 1024;
735
+ const DONE = {
736
+ done: true,
737
+ value: undefined
738
+ };
739
+ function malformedStream() {
740
+ return new Error("Malformed server function stream.");
741
+ }
727
742
  class ChunkReader {
728
743
  constructor(stream) {
729
744
  this.reader = stream.getReader();
730
745
  this.store = new Uint8Array(0);
731
746
  this.buffer = this.store;
732
747
  this.done = false;
748
+ this.cancelled = false;
733
749
  }
734
750
  async readChunk() {
735
751
  const chunk = await this.reader.read();
736
752
  if (chunk.done) {
737
753
  this.done = true;
738
- return;
754
+ return this.cancelled;
739
755
  }
740
756
  const incoming = chunk.value;
741
757
  const store = this.store;
@@ -756,55 +772,66 @@ class ChunkReader {
756
772
  this.store = grown;
757
773
  this.buffer = grown.subarray(0, needed);
758
774
  }
775
+ return this.cancelled;
759
776
  }
760
777
  async next() {
778
+ if (this.cancelled) return DONE;
761
779
  while (this.buffer.length < 12) {
762
780
  if (this.done) {
763
- if (this.buffer.length === 0) return {
764
- done: true,
765
- value: undefined
766
- };
767
- throw new Error("Malformed server function stream.");
781
+ if (this.buffer.length === 0) return DONE;
782
+ throw malformedStream();
768
783
  }
769
- await this.readChunk();
770
- }
771
- const decoder = new TextDecoder();
772
- const bytes = Number.parseInt(decoder.decode(this.buffer.subarray(1, 11)), 16);
773
- if (Number.isNaN(bytes)) {
774
- throw new Error("Malformed server function stream.");
784
+ if (await this.readChunk()) return DONE;
775
785
  }
786
+ const header = String.fromCharCode(...this.buffer.subarray(0, 12));
787
+ if (!/^;0x[\dA-Fa-f]{8};$/.test(header)) throw malformedStream();
788
+ const bytes = parseInt(header.slice(3, 11), 16);
776
789
  while (bytes > this.buffer.length - 12) {
777
790
  if (this.done) {
778
- throw new Error("Malformed server function stream.");
791
+ throw malformedStream();
779
792
  }
780
- await this.readChunk();
793
+ if (await this.readChunk()) return DONE;
794
+ }
795
+ let partial;
796
+ try {
797
+ partial = CHUNK_DECODER.decode(this.buffer.subarray(12, 12 + bytes));
798
+ } catch {
799
+ throw malformedStream();
781
800
  }
782
- const partial = decoder.decode(this.buffer.subarray(12, 12 + bytes));
783
801
  this.buffer = this.buffer.subarray(12 + bytes);
802
+ if (this.store.length > RETAINED_STORE_BYTES && this.buffer.length <= RETAINED_STORE_BYTES) {
803
+ this.store = this.buffer = this.buffer.slice();
804
+ }
784
805
  return {
785
806
  done: false,
786
807
  value: partial
787
808
  };
788
809
  }
789
810
  async drain(interpret) {
790
- while (true) {
791
- const result = await this.next();
792
- if (result.done) {
793
- break;
811
+ try {
812
+ while (true) {
813
+ const result = await this.next();
814
+ if (result.done) {
815
+ break;
816
+ }
817
+ interpret(result.value);
794
818
  }
795
- interpret(result.value);
819
+ } catch (error) {
820
+ this.cancel(error).catch(() => {});
821
+ throw error;
796
822
  }
797
823
  }
798
824
  cancel(reason) {
825
+ this.cancelled = true;
799
826
  return this.reader.cancel(reason);
800
827
  }
801
828
  }
802
829
  function createEventChunk(data, id) {
803
830
  let event = id !== undefined && !id.includes("\0") ? `id: ${id}\n` : "";
804
831
  for (const line of data.split(/\r\n|\r|\n/)) event += `data: ${line}\n`;
805
- return new TextEncoder().encode(event + "\n");
832
+ return CHUNK_ENCODER.encode(event + "\n");
806
833
  }
807
- const EVENT_STREAM_HEARTBEAT = new TextEncoder().encode(":\n\n");
834
+ const EVENT_STREAM_HEARTBEAT = /* @__PURE__ */new TextEncoder().encode(":\n\n");
808
835
  function positionDigest(value) {
809
836
  if (value === undefined || !isJSONSafe(value)) return undefined;
810
837
  const text = JSON.stringify(value);
@@ -868,29 +895,36 @@ async function deserializeStream(source, codecOptions, wire) {
868
895
  throw new Error("missing body");
869
896
  }
870
897
  const reader = new ChunkReader(source.body);
871
- const result = await reader.next();
872
- if (!result.done) {
873
- if (result.value.startsWith(ERROR_TRAILER_PREFIX)) {
874
- throw errorFromTrailer(result.value);
875
- }
876
- const {
877
- createJSONDeserializer
878
- } = await import('@solidjs/web/serialization/decode');
879
- const deserializeChunk = createJSONDeserializer(codecOptions);
880
- function interpretChunk(chunk) {
881
- if (chunk.startsWith(ERROR_TRAILER_PREFIX)) {
882
- throw errorFromTrailer(chunk);
898
+ try {
899
+ const result = await reader.next();
900
+ if (!result.done) {
901
+ if (result.value.startsWith(ERROR_TRAILER_PREFIX)) {
902
+ throw errorFromTrailer(result.value);
903
+ }
904
+ const {
905
+ createJSONDeserializer
906
+ } = await import('@solidjs/web/serialization/decode');
907
+ const deserializeChunk = createJSONDeserializer(codecOptions);
908
+ function interpretChunk(chunk) {
909
+ if (chunk.startsWith(ERROR_TRAILER_PREFIX)) {
910
+ throw errorFromTrailer(chunk);
911
+ }
912
+ return deserializeChunk(JSON.parse(chunk));
883
913
  }
884
- return deserializeChunk(JSON.parse(chunk));
914
+ const connection = wire && wire.connection;
915
+ let endConnection;
916
+ if (connection) ;
917
+ const end = error => {
918
+ const sweep = () => deserializeChunk.abort(error);
919
+ if (connection) ; else sweep();
920
+ };
921
+ reader.drain(interpretChunk).then(() => end(new Error("Server function stream ended unexpectedly.")), error => end(error));
922
+ return interpretChunk(result.value);
885
923
  }
886
- const end = error => {
887
- const sweep = () => deserializeChunk.abort(error);
888
- sweep();
889
- };
890
- reader.drain(interpretChunk).then(() => end(new Error("Server function stream ended unexpectedly.")), error => end(error));
891
- return interpretChunk(result.value);
924
+ } catch (error) {
925
+ reader.cancel(error).catch(() => {});
926
+ throw error;
892
927
  }
893
- return undefined;
894
928
  }
895
929
  async function deserializeString(text, codecOptions) {
896
930
  return await deserializeStream(new Response(text), codecOptions);
@@ -1000,10 +1034,13 @@ function copyInitHeaders(init) {
1000
1034
  for (const cookie of init.getSetCookie()) headers.append("Set-Cookie", cookie);
1001
1035
  return headers;
1002
1036
  }
1003
- const STUB_GAP_FILL_EXCLUDED = /*#__PURE__*/new Set([ERROR_HEADER, BODY_FORMAT_HEADER, SINGLE_FLIGHT_HEADER, REVALIDATE_HEADER, REDIRECT_HEADER, "Location",
1004
- ...COMPOSED_BODY_FRAMING].map(header => header.toLowerCase()));
1037
+ let stubGapFillExcluded;
1038
+ function isStubGapFillExcluded(key) {
1039
+ return (stubGapFillExcluded ||= new Set([ERROR_HEADER, BODY_FORMAT_HEADER, SINGLE_FLIGHT_HEADER, REVALIDATE_HEADER, REDIRECT_HEADER, "Location",
1040
+ ...COMPOSED_BODY_FRAMING].map(header => header.toLowerCase()))).has(key);
1041
+ }
1005
1042
  function fillsStubGap(key, headers, response) {
1006
- if (key === "set-cookie" || STUB_GAP_FILL_EXCLUDED.has(key)) return false;
1043
+ if (key === "set-cookie" || isStubGapFillExcluded(key)) return false;
1007
1044
  if (response.body === null && (key === "content-type" || key === "content-length")) return false;
1008
1045
  return !headers.has(key);
1009
1046
  }
@@ -1558,20 +1595,28 @@ function createServerReference({
1558
1595
  const scope = run => provideEvent(evt, run);
1559
1596
  const wrap = resolveWrapInvocation(config.wrapInvocation);
1560
1597
  const hook = requestErrorHook(ogEvt);
1561
- let result = provideEventOnce(provideEvent, evt, () => {
1562
- const run = () => fn.apply(thisArg, args);
1563
- return observeInvocation({
1564
- id,
1565
- direct: true,
1566
- event: evt,
1567
- args
1568
- }, () => reportDirectFailure(() => wrap ? wrap(run, {
1569
- id,
1570
- args,
1571
- event: evt,
1572
- direct: true
1573
- }) : run(), id, hook));
1574
- });
1598
+ let result;
1599
+ try {
1600
+ result = provideEventOnce(provideEvent, evt, () => {
1601
+ const run = () => fn.apply(thisArg, args);
1602
+ return observeInvocation({
1603
+ id,
1604
+ direct: true,
1605
+ event: evt,
1606
+ args
1607
+ }, () => reportDirectFailure(() => wrap ? wrap(run, {
1608
+ id,
1609
+ args,
1610
+ event: evt,
1611
+ direct: true
1612
+ }) : run(), id, hook));
1613
+ });
1614
+ } catch (error) {
1615
+ throw directEnvelopeValue(error, evt);
1616
+ }
1617
+ result = result && typeof result.then === "function" ? result.then(value => directEnvelopeValue(value, evt), error => {
1618
+ throw directEnvelopeValue(error, evt);
1619
+ }) : directEnvelopeValue(result, evt);
1575
1620
  result = scopeDeferredResult(result, scope);
1576
1621
  const transform = config.transformDirectResult;
1577
1622
  if (transform && result && typeof result.then === "function") {
@@ -2455,7 +2500,7 @@ function encodeLiveResult(value, headers, status, codec, request, scope) {
2455
2500
  function encodeResult(value, headers, status, codec, signal, scope) {
2456
2501
  if (NULL_BODY_STATUSES.has(status)) {
2457
2502
  if (value === undefined || value === null) {
2458
- headers.set(BODY_FORMAT_HEADER, BodyFormat.Void);
2503
+ if (status !== 304) headers.set(BODY_FORMAT_HEADER, BodyFormat.Void);
2459
2504
  return new Response(null, {
2460
2505
  status,
2461
2506
  headers
@@ -2542,6 +2587,7 @@ function currentEvent() {
2542
2587
  }
2543
2588
  function reportDirectFailure(run, id, hook) {
2544
2589
  const report = error => {
2590
+ if (error instanceof Response || isResponseEnvelope(error)) throw error;
2545
2591
  reportServerError(error, {
2546
2592
  kind: "server-function",
2547
2593
  handling: "thrown",
@@ -2558,6 +2604,20 @@ function reportDirectFailure(run, id, hook) {
2558
2604
  }
2559
2605
  return result && typeof result.then === "function" ? result.then(undefined, report) : result;
2560
2606
  }
2607
+ function directEnvelopeValue(result, event) {
2608
+ if (!isResponseEnvelope(result)) return result;
2609
+ const {
2610
+ response,
2611
+ value
2612
+ } = result;
2613
+ const stub = event.response;
2614
+ if (response && stub && stub.headers && response.headers.getSetCookie) {
2615
+ for (const cookie of response.headers.getSetCookie()) {
2616
+ stub.headers.append("Set-Cookie", cookie);
2617
+ }
2618
+ }
2619
+ return value;
2620
+ }
2561
2621
  function sanitizeServerError(value) {
2562
2622
  if (DEV) return value;
2563
2623
  if (isSafeError(value)) return value;
@@ -2806,8 +2866,14 @@ async function handleServerFunctionRequest(request, options = {}) {
2806
2866
  });
2807
2867
  return finish(protectsRequest ? withCSRFVary(response) : response);
2808
2868
  }
2869
+ const commitResponse = raw => {
2870
+ if ((method === "GET" || method === "HEAD") && (sharedCacheMayStore(departingHeader(raw, event, "Cache-Control")) || cdnMayStore(departingHeader(raw, event, "CDN-Cache-Control")))) {
2871
+ withholdTrace(event);
2872
+ }
2873
+ return commitEventResponse(raw, event);
2874
+ };
2809
2875
  const refuseCommitted = raw => {
2810
- const response = commitEventResponse(raw, event);
2876
+ const response = commitResponse(raw);
2811
2877
  return finish(protectsRequest ? withCSRFVary(response) : response);
2812
2878
  };
2813
2879
  const provide = options.provideEvent || provideEvent;
@@ -3025,9 +3091,54 @@ async function handleServerFunctionRequest(request, options = {}) {
3025
3091
  return respondThrown(x);
3026
3092
  }
3027
3093
  };
3028
- const response = commitEventResponse(enforceComposedHeaderInvariants(ownResponse(await dispatch())), event);
3094
+ const response = commitResponse(enforceComposedHeaderInvariants(ownResponse(await dispatch())));
3029
3095
  return finish(protectsRequest ? withCSRFVary(response) : response);
3030
3096
  }
3097
+ function departingHeader(response, event, name) {
3098
+ const own = response.headers.get(name);
3099
+ if (own !== null) return own;
3100
+ const stub = event.response;
3101
+ return stub && stub.headers && !stub.committed ? stub.headers.get(name) : null;
3102
+ }
3103
+ function cdnMayStore(cdnCacheControl) {
3104
+ return cdnCacheControl !== null && !forbidsStoring(cdnCacheControl);
3105
+ }
3106
+ function sharedCacheMayStore(cacheControl) {
3107
+ let shared = false;
3108
+ return !!cacheControl && !eachDirective(cacheControl, name => {
3109
+ if (name === "public" || name === "s-maxage") shared = true;
3110
+ }) && shared;
3111
+ }
3112
+ function forbidsStoring(value) {
3113
+ return eachDirective(value, () => {});
3114
+ }
3115
+ function eachDirective(value, visit) {
3116
+ let start = 0;
3117
+ let quoted = false;
3118
+ for (let i = 0; i <= value.length; i++) {
3119
+ const c = value[i];
3120
+ if (quoted) {
3121
+ if (c === "\\") i++;else if (c === '"') quoted = false;
3122
+ continue;
3123
+ }
3124
+ if (c === '"') {
3125
+ quoted = true;
3126
+ continue;
3127
+ }
3128
+ if (c !== "," && i < value.length) continue;
3129
+ const directive = value.slice(start, i);
3130
+ start = i + 1;
3131
+ const eq = directive.indexOf("=");
3132
+ const name = (eq === -1 ? directive : directive.slice(0, eq)).trim().toLowerCase();
3133
+ if (name === "no-store" || name === "private" && eq === -1) return true;
3134
+ visit(name);
3135
+ }
3136
+ return false;
3137
+ }
3138
+ function withholdTrace(event) {
3139
+ if (event.response && event.response.committed) return;
3140
+ traceForEvent(event).emit = false;
3141
+ }
3031
3142
  function ownResponse(response) {
3032
3143
  try {
3033
3144
  return new Response(response.body, response);
@@ -14,12 +14,12 @@ this file is the operative subset.
14
14
 
15
15
  - Exists because of **server data** (a todo row, a nav link, a search
16
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.
17
+ client-driven value on it is a **binding slot** — bind, never wrap.
18
18
  Do not wrap a server-rendered element in a client component to give it a
19
19
  handler or a class.
20
20
  - Exists because of **client state alone** (an optimistic add, a modal, a
21
21
  drag ghost, an editor open over a field)? It is a **client component**
22
- placed through a **markup slot**.
22
+ placed through a **template slot**.
23
23
 
24
24
  When the client confirms an optimistic entity and the server renders it, the
25
25
  row _becomes_ server markup; `$key` on the element reconciles the two.
@@ -27,19 +27,19 @@ row _becomes_ server markup; `$key` on the element reconciles the two.
27
27
  ## The two kinds of slot
28
28
 
29
29
  ```tsx
30
- import type { AttributeSlot, Slot } from "@solidjs/web/frames";
30
+ import type { BindingSlot, Slot } from "@solidjs/web/frames";
31
31
 
32
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
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
36
36
  }
37
37
  ```
38
38
 
39
- A **markup slot** is placed as an element: `<props.pending />`. The client
39
+ A **template slot** is placed as an element: `<props.pending />`. The client
40
40
  owns those nodes.
41
41
 
42
- An **attribute slot** is _called_ once per data context and its properties
42
+ A **binding slot** is _called_ once per data context and its properties
43
43
  are _bound_ at positions of the server's own template:
44
44
 
45
45
  ```tsx
@@ -72,12 +72,17 @@ export async function todoList() {
72
72
  The client passes the fill — a function of the args that returns the object:
73
73
 
74
74
  ```tsx
75
- <Todos row={rowFor} filters={() => ({ all: filter() === "all", … })} pending={() => <For each={adds}>{…}</For>} />
75
+ <Todos row={rowFor} filters={() => ({ get all() { return filter() === "all"; }, … })} pending={() => <For each={adds}>{…}</For>} />
76
76
  ```
77
77
 
78
- ## The one rule for attribute slots
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.
79
82
 
80
- > **A slot property is a JSX attribute value, whole, and nothing else.**
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.**
81
86
 
82
87
  Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
83
88
  `title={row.error}`), a class name inside object form
@@ -86,8 +91,12 @@ Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`,
86
91
  an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element
87
92
  with a spread too (`<button {...rest} onClick={row.go} />` — the last
88
93
  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
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
91
100
  plain objects and arrays included). Reserved keys the fill must not use:
92
101
  keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`,
93
102
  `constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map`
@@ -97,25 +106,34 @@ The server **does not have the value** — on the stream face a property read
97
106
  is a stand-in with no value, on the document face only the initial one — so
98
107
  nothing can be computed from it on the server. Every one of these is wrong:
99
108
 
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.
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.
114
126
 
115
127
  ## Writing the fill
116
128
 
117
- - **Values as getters, handlers as plain closures** when a shared client
118
- component also consumes the object (the usual case):
129
+ - **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
131
+ creates (a signal, a memo, an `onCleanup`) lives as long as the
132
+ 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:
119
137
 
120
138
  ```tsx
121
139
  const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({
@@ -133,11 +151,11 @@ is why.
133
151
  });
134
152
  ```
135
153
 
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.
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).
141
159
 
142
160
  - **Name it like a props interface**, because it is one (a shared component
143
161
  takes it as a prop). Handlers are `on` + intent — `onToggle`, `onRemove`,
@@ -147,9 +165,10 @@ is why.
147
165
  runtime reads nothing into the prefix — the position decides what a
148
166
  property is — but a reader can tell a handler from a value without
149
167
  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.
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.
153
172
  - **`$key` is optional.** A call repeated within a render (a component
154
173
  prop re-evaluates it per position) is one occurrence either way. Add
155
174
  `$key: t.id` when the fill holds its own state (an edit draft, a signal
@@ -162,7 +181,7 @@ is why.
162
181
  ## Shared components
163
182
 
164
183
  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
184
+ the binding slot's return, on the client it is the fill's result. It
166
185
  cannot tell and need not. Put `$key={props.id}` on the element it renders
167
186
  (morph identity) — the slot call's own `$key` is a different key for a
168
187
  different job. Do not read `document`/`window` during render; that is the
@@ -181,26 +200,29 @@ cannot be marked — the `inline` finding below.
181
200
 
182
201
  ## Diagnostics
183
202
 
184
- `ATTRIBUTE_SLOT_POSITION` (`data.reason`):
203
+ `BINDING_SLOT_POSITION` (`data.reason`):
185
204
 
186
205
  | reason | severity | what happened | fix |
187
206
  | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
188
207
  | `spread` | error (throws) | a slot's return was spread onto an element | name each position |
189
208
  | `stringified` | warn | template literal / concatenation | whole value at one position |
190
209
  | `coerced` | warn | comparison, arithmetic, `==` | decide in the fill |
191
- | `text` | warn | placed as a text child | markup slot |
192
210
  | `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` |
193
211
  | `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot |
194
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 |
195
214
  | `reserved-key` | warn | the fill used a reserved key | rename it |
196
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 |
197
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 |
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 |
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 |
199
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 |
200
220
 
201
- Every reason but `fill-shape` and `orphan` comes from the server render.
221
+ Every reason but `fill-shape`, `text-shape` and `orphan` comes from the server render.
202
222
  `orphan` is the one failure this model cannot otherwise show you: the
203
223
  element is inert — a handler that never fires, a class that never updates —
204
224
  with no error.
205
225
 
206
- `STRICT_READ_UNTRACKED` inside a fill: use getters (above).
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).