-
+
- + + {/* server content, never data */} + + + )}
`
+widens accordingly) and one marker attribute on server elements
+(`_slot`, the `_hk` family — the build record below says why it is
+not a `_bnd` position kind), plus two dev diagnostic codes
+(`ATTRIBUTE_SLOT_FILL`, `ATTRIBUTE_SLOT_CONFLICT`). No compiler
+option, no transform. Everything the client writes is
+`createOptimistic*`, already public.
+
+**Acceptance gate — Server Component TodoMVC (restated for the third
+time; the gate itself does not move).** Port `examples/todos` beside
+itself, preserving its delays, ~33% write failure, per-item retry,
+bulk actions, filters, and overlapping transitions. Pass condition:
+**every optimistic behavior is a derivation over slot args and
+`createOptimistic*` state inside an attribute fill, or client JSX in
+a pre-placed content slot — zero imperative DOM writes, zero
+selector coupling, zero new client vocabulary.** Toggle, remove,
+pending/disabled/error markup are attribute fills; add is a content
+slot; counters and filter state are data-shaped. Do not call the
+shape settled until add/remove/toggle success and failure, checkbox
+correction, concurrent and bulk mutations, retry/error markup,
+state retention across reordering morphs (focus, typed values), and
+clean hydration are all shown in the port, under both mutation
+shapes. The simplicity-parity
+criterion stands, and is now pointed at the one place it can fail:
+if the hand-written layering in the fills is heavier than the
+store's projection in the SPA, that is the finding.
+
+**Machinery ledger.** No net-new engine, no compiler change.
+Touched, all existing and all runtime: `ssrElement` (recognize the
+branded source among a spread's sources; emit the marker + slot
+record; at t = 0 run the fill and serialize its output), the claim
+engine (a scope per marked element receiving reactive args), client
+`spread` (unchanged), the morph (skip client-owned keys on matched
+elements — the same class of exception as foreign ranges). The optimistic engine is
+`@solidjs/signals`' existing `createOptimistic`/`createOptimisticStore`,
+imported by the app that uses them.
+
+**Consequences for the roadmap.** Stage 7 is "attribute slots," not
+"predictions." It is shallower than Stage 6 was — runtime only, no
+compiler round, the claim engine plus `ssrElement`; no transaction
+machinery, no solid-core changes — and independent of Stage 8 in
+both directions.
+The size-harness "hydrating + stores" row stops being Stage 7's
+floor: a frames page carries the optimistic engine only if the app
+imports it.
+
+**Build record (2026-09-27, same night; runtime as shipped).** The
+shape above is in `packages/web` behind three test files
+(`test/server/frame-attribute-slots.spec.tsx`,
+`test/frames-attribute-slots.spec.tsx`,
+`test/hydration/attribute-slot-adoption.spec.tsx`). Where the build
+departed from the text above, the build is right and the text is
+amended here:
+
+- *The marker is `_slot`, not a `_bnd` position kind.*
+ `_slot=" ` returns `Element`, which TypeScript will not spread — the
+attribute-object return type this called for is superseded by the
+next amendment, which is also where the gate's *finding* is
+recorded: the fill table came out heavier than the SPA's store
+projection, which is the one failure the simplicity-parity
+criterion was pointed at.
+
+#### 9.2.3 Amendment — attribute slots, second form: one per data context, bound per position (2026-09-28)
+
+Recorded from the design conversation the morning after the
+acceptance gate ran. The gate passed its behaviors and failed its
+criterion: `examples/todos-server` needed eleven slot props and a
+ten-entry fill table on the client for a row the SPA writes once.
+Asking why led to the row's real question — *wrap it in a client
+component, or attribute-slot it?* — and both answers worked, which
+meant the design had left the choice to taste. Re-deriving from the
+question instead of the mechanism found one answer, and a shape in
+which the attribute-slot *spread* of 9.2.2 is a special case done
+wrong. **The 09-27 spread shape — one slot per element, its return
+spread onto that element, the client deciding what it owns — is
+retired.** The idea it carried is not: the client still contributes
+*attribute values* to server markup, and that is what this form is
+named for. The 09-27 text and its build record stay as the record
+of how the shape was found; nothing in them ships. Where this
+amendment and 9.2.2 disagree, this amendment is right.
+
+**The reframe: a slot is a client render, and it renders one of two
+things.** A markup slot's client function returns JSX; the server
+places it as a region, and the client owns those nodes. An
+*attribute* slot's client function returns a plain object; the
+server *consumes* it — binds its properties into named positions
+of the server's own template, one call serving every element of
+one data context — and the client owns exactly those values. What
+the object holds is anything that is not markup: an attribute
+value, a class name's condition, a style property, a handler, a
+ref — every derived thing a client would compute for an element
+the server rendered. (The build called this form "data slots" for
+a day, after what the fill returns; it was renamed the same day
+because the name misled — the values are attributes of server
+elements, the object is only how they travel.) The client renders
+JSON, the server renders markup. Both run at t = 0 on the document
+face (the server invokes the client function and serializes what
+came back into place), both are live afterward through the same
+occurrence machinery, and both obey one ownership rule: whoever
+produced the output owns it — the markup owner owns the nodes, the
+attribute owner owns the properties the template read.
+
+That reframe carries the placement principle §9.2 should have led
+with, because it is what the gate was missing:
+
+> **An element lives where the data that creates it lives.** An
+> element that exists because of server data is server markup;
+> client behavior or client-driven values on it are an attribute slot —
+> you never wrap a server-rendered thing to add behavior, you bind.
+> An element that exists because of client state alone (an
+> optimistic add, a modal, a drag ghost, an editor open over a
+> field the server rendered as text) is a client component in a
+> markup slot. The boundary moves with the data's ownership, not
+> with where the author wanted to write code.
+
+Under it the TodoMVC row is not a choice: the row exists because
+the server has a todo, so it is server markup with an attribute slot; the
+pending row exists because the client has an intent the server has
+not seen, so it is a client component; when the server confirms it,
+it *becomes* server markup, and `$key` reconciles the transition.
+Every case that was a judgment call resolves the same way — a
+`selected` class on a server nav link binds; a search input in
+server markup binds; a live-typing filter the client owns entirely
+is a client component; a server table's client-side sort indicators
+bind.
+
+**The shape.** One attribute slot per *data context* — one call, one
+client scope, consumed by any element in the template:
+
+```tsx
+// ── todo-row.tsx — no directive, no side ────────────────────
+export interface RowBehavior {
+ rowClass: Record
+
+
+
+
+
+
+ {todos.map(t => (
+
+ );
+}
+
+// ── client ──────────────────────────────────────────────────
+const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({
+ rowClass: { todo: true, completed: done(p), pending: !!intent.byId[p.id], errored: !!errors[p.id] },
+ removed: removed(p.id),
+ done: done(p),
+ onToggle: e => toggleTodo(p.id, e.currentTarget.checked),
+ onRemove: () => removeTodo(p.id, p.completed),
+ onRetry: () => retryTodo(p.id),
+ error: errors[p.id]?.message
+});
+
+
{segmentsOf(closePartial(text())).map(segment =>
segment.code ? (
- // Behavior from the client on a server element (Stage 6):
- // `props.copy` is the client-passed handler; this position
- // compiles to a `_bnd` claim marker that rides every hole
- // re-emission, so the button works mid-stream and keeps
- // working after each morph. The handler reads its code from
- // the DOM at dispatch — delegation, not per-block wiring.
+ // Behavior from the client on a server element: `block.onCopy`
+ // is an attribute-slot read at an event position, so this button
+ // carries a marker that rides every hole re-emission — the
+ // client binds it mid-stream and rebinds after each morph.
+ // The handler reads its code from the DOM at dispatch.
+
+
+All
+```
+
+`TodoRow` ([src/todo-row.tsx](./src/todo-row.tsx)) is the shared component:
+it binds `row.rowClass`, `row.removed`, `row.done`, `row.onToggle`,
+`row.onRemove`, `row.onRetry`, `row.error` at attribute, class, event and
+handler positions and cannot tell — does not need to — whether `row` is an
+attribute slot's value (server) or the fill's result passed directly (client).
+
+The object is a props interface — `TodoRow` takes it as a prop on the client
+path — so it is named like one: handlers are `on` + intent (`onToggle`,
+`onRemove`; the position names the DOM event, the key names the meaning),
+values are nouns (`done`, `rowClass`, `error`), a ref is `ref`. The
+runtime reads nothing into the prefix — the position decides what a
+property is — but a reader can tell a handler from a value without the type.
+
+One rule: a slot property is a JSX attribute value, whole, and nothing else.
+`class={row.rowClass}` binds; ``class={`todo ${row.rowClass}`}``,
+`{row.title}` as text, or `if (row.done)` in the server component do not —
+the server has no value to compute with, so the decision belongs in the
+fill, which returns the decided value.
+
+The client's fill receives the args as reactive props and returns the
+**object** the template reads ([src/app.tsx](./src/app.tsx)):
+
+```tsx
+const rowFor = (p: Entity): RowBehavior => ({
+ get rowClass() { return { todo: true, completed: done(p.id, p.completed), pending: …, errored: … }; },
+ get done() { return done(p.id, p.completed); },
+ get removed() { return removed(p.id) || !visible(done(p.id, p.completed)); },
+ get error() { return errors[p.id] ? `Retry ${errors[p.id].type}` : undefined; },
+ onToggle: e => actions.toggleTodo(p.id, e.currentTarget.checked),
+ onRemove: () => actions.removeTodo(p.id, p.completed),
+ onRetry: () => actions.retryTodo(p.id)
+});
+
+ ({ all: filter === "all", … })} pending={…} count={…} />
+```
+
+The values are getters because the same `rowFor` result is a client
+component's prop for the pending rows: a handler position (`onInput={props.row.onToggle}`)
+is read once in the component body, and a getter-shaped object reads no
+reactive state there. On the server each read at a position marks the
+element (`_s:class="row#0001:rowClass"`, `_s:on:input="row#0001:onToggle"`);
+the client binds exactly those positions, writes the values that change,
+dispatches events to the current handler, and a response morphing the list
+skips the positions a fill owns. At document SSR the fill runs inline, so
+`checked` and `class="todo completed"` are in the HTML before JavaScript; on
+hydration the fill binds to the same nodes.
+
+## What the client holds
+
+The SPA kept the todo array on the client. This app never has it — the rows
+are markup. What it holds is **intent** (what it asked the server to do and
+has not heard back about) in a `createOptimisticStore`, and the errors it
+heard back in a plain store ([src/todos.ts](./src/todos.ts)). Fills combine
+those with each call's args:
+
+- toggle: `intent.byId[id]?.completed ?? p.completed`
+- remove: `hidden` on the server's ``; the morph drops the row when the
+ refetch lands (or `hidden` reverts when the save fails)
+- add: the one thing the client cannot decorate is a row the server has not
+ rendered, so `Solid 2.0 Todos (server components)
+ ();
+
+function Header() {
+ const { actions } = useContext(TodosContext);
+ return (
+
+
+ );
+}
+
+function TodoList(props: { filter: Filter }) {
+ const state = useContext(TodosContext);
+ const { intent, errors, done, removed, extraRows, counts, actions } = state;
+ const Todos = dynamic(() => state.todos());
+
+ const visible = (completed: boolean) =>
+ props.filter === "all" || (props.filter === "active") !== completed;
+
+ // A row's behavior, from the server's view of it (`completed` as of the
+ // last response) and the client's (intent over it, errors beside it).
+ // Same function for a server row (through the `row` attribute slot) and a
+ // pending one (passed to directly). Values are getters and
+ // handlers are plain closures: building the object reads nothing, so the
+ // reads happen where the template binds each property — a tracking scope
+ // for a value, event time for a handler — and each position updates on
+ // its own.
+ const rowFor = (p: Entity): RowBehavior => ({
+ get rowClass() {
+ return {
+ todo: true,
+ completed: done(p.id, p.completed),
+ pending: !!intent.byId[p.id] || intent.adds.some(t => t.id === p.id),
+ errored: !!errors[p.id]
+ };
+ },
+ get done() {
+ return done(p.id, p.completed);
+ },
+ get removed() {
+ return removed(p.id) || !visible(done(p.id, p.completed));
+ },
+ get error() {
+ return errors[p.id] ? `Retry ${errors[p.id]!.type}` : undefined;
+ },
+ onToggle: e => actions.toggleTodo(p.id, e.currentTarget.checked),
+ onRemove: () => actions.removeTodo(p.id, p.completed),
+ onRetry: () => actions.retryTodo(p.id)
+ });
+
+ // The ids whose client-side `completed` is the given value, from the
+ // server's two lists (an entity's intent may have moved it across).
+ const idsWhere = (p: { active: string[]; completed: string[] }, completed: boolean) => [
+ ...p.active.filter(id => !removed(id) && done(id, false) === completed),
+ ...p.completed.filter(id => !removed(id) && done(id, true) === completed)
+ ];
+ const listFor = (p: { total: number; active: string[]; completed: string[] }) => {
+ const active = () => idsWhere(p, false);
+ const completed = () => idsWhere(p, true);
+ const allDone = () => active().length === 0 && completed().length > 0;
+ return {
+ get empty() {
+ return counts({ remaining: 0, total: p.total }).total === 0;
+ },
+ get allDone() {
+ return allDone();
+ },
+ get noneDone() {
+ return completed().length === 0;
+ },
+ onToggleAll: () =>
+ allDone() ? actions.toggleAll(completed(), false) : actions.toggleAll(active(), true),
+ onClearCompleted: () => actions.clearCompleted(completed())
+ };
+ };
+
+ return (
+ (
+
+ {todo =>
+ )}
+ count={p => {
+ const remaining = () => counts(p).remaining;
+ return (
+ <>
+ {remaining()} {remaining() === 1 ? "item" : "items"} left
+
+ );
+ }}
+ filters={() => ({
+ all: props.filter === "all",
+ active: props.filter === "active",
+ completed: props.filter === "completed"
+ })}
+ />
+ );
+}
+
+export default function App() {
+ const filter = createHashFilter();
+ return (
+ (
+
+
+ Loading…}>
+
+
+
+
+ );
+}
diff --git a/examples/todos-server/src/filter.ts b/examples/todos-server/src/filter.ts
new file mode 100644
index 000000000..e80aca0c7
--- /dev/null
+++ b/examples/todos-server/src/filter.ts
@@ -0,0 +1,29 @@
+import { createSignal, onSettled } from "solid-js";
+
+export type Filter = "all" | "active" | "completed";
+
+function parseHash(hash: string): Filter {
+ if (hash === "#/active") return "active";
+ if (hash === "#/completed") return "completed";
+ return "all";
+}
+
+/**
+ * View-state primitive that mirrors the URL hash into a reactive filter.
+ *
+ * The SPA twin reads `location.hash` at creation. Here the app is
+ * server-rendered and the server cannot see the hash, so the signal starts
+ * at "all" on both faces (the hydrated HTML matches what the client's first
+ * pass computes) and takes the real hash once the initial activity settles —
+ * at the same moment the `hashchange` listener attaches.
+ */
+export function createHashFilter(): () => Filter {
+ const [filter, setFilter] = createSignal("all");
+ onSettled(() => {
+ const onChange = () => setFilter(parseHash(location.hash));
+ onChange();
+ window.addEventListener("hashchange", onChange);
+ return () => window.removeEventListener("hashchange", onChange);
+ });
+ return filter;
+}
diff --git a/examples/todos-server/src/lib/db.ts b/examples/todos-server/src/lib/db.ts
new file mode 100644
index 000000000..66b11d66b
--- /dev/null
+++ b/examples/todos-server/src/lib/db.ts
@@ -0,0 +1,81 @@
+// The todo store, server-only: this module is only imported by "use server"
+// modules, so unstorage never reaches the client build. It is the SPA twin's
+// mock API (../../../todos/src/api.ts) moved behind the server boundary with
+// the same shape and the same deliberate unreliability: every save waits
+// 400 ms and ~33% of them fail, so the optimistic UI, the per-item errors
+// and the retry affordances get exercised. Todos reset on server restart
+// (memory driver); swap the driver for a durable store in a deployment.
+import { createStorage } from "unstorage";
+import memoryDriver from "unstorage/drivers/memory";
+
+export interface Todo {
+ id: string;
+ title: string;
+ completed: boolean;
+}
+
+const storage = createStorage({ driver: memoryDriver() });
+
+const SEED: Todo[] = [
+ { id: "0001", title: "Read the server-components principles", completed: true },
+ { id: "0002", title: "Port TodoMVC to a server component", completed: false },
+ { id: "0003", title: "Break the network and watch it recover", completed: false }
+];
+
+export async function getTodos(): Promise {
+ const todos = (await storage.getItem("todos")) as Todo[] | null;
+ if (todos) return todos;
+ await storage.setItem("todos", SEED);
+ return SEED;
+}
+
+async function saveTodos(todos: Todo[]) {
+ if (Math.random() < 0.33) return reject(400);
+ await storage.setItem("todos", todos);
+ return delay(undefined, 400);
+}
+
+export async function addTodo(todo: Todo) {
+ const newTodo = { ...todo };
+ const todos = await getTodos();
+ if (todos.some(t => t.id === newTodo.id)) return newTodo;
+ const index = todos.findIndex(t => t.id > newTodo.id);
+ if (index > -1) todos.splice(index, 0, newTodo);
+ else todos.push(newTodo);
+ await saveTodos(todos);
+ return newTodo;
+}
+
+export async function removeTodo(todoId: string) {
+ return saveTodos((await getTodos()).filter(t => t.id !== todoId));
+}
+
+export async function toggleTodo(todoId: string, completed: boolean) {
+ let found: Todo | undefined;
+ const todos = (await getTodos()).map(t => {
+ if (t.id !== todoId) return t;
+ return (found = { ...t, completed });
+ });
+ if (!found) return reject(400);
+ await saveTodos(todos);
+ return found;
+}
+
+export async function toggleAll(ids: string[], completed: boolean) {
+ const set = new Set(ids);
+ const todos = (await getTodos()).map(t => (set.has(t.id) ? { ...t, completed } : t));
+ return saveTodos(todos);
+}
+
+export async function clearCompleted(ids: string[]) {
+ const set = new Set(ids);
+ return saveTodos((await getTodos()).filter(t => !set.has(t.id)));
+}
+
+function delay(payload: T, time: number) {
+ return new Promise(res => setTimeout(res, time, payload));
+}
+
+function reject(time: number) {
+ return new Promise((_, rej) => setTimeout(rej, time, new Error("Failed to save")));
+}
diff --git a/examples/todos-server/src/server/todos.tsx b/examples/todos-server/src/server/todos.tsx
new file mode 100644
index 000000000..19d9b64d0
--- /dev/null
+++ b/examples/todos-server/src/server/todos.tsx
@@ -0,0 +1,130 @@
+"use server";
+// TodoMVC's list as a server component. Compare with the SPA twin's
+// app.tsx: the markup is the same, but this side renders DATA only — titles,
+// counts, ids, the server's `completed` — and never a pending row, an error
+// class or a retry button. Those belong to the client, and the client puts
+// them on the server's own elements through ATTRIBUTE SLOTS: a slot CALLED with
+// the element's data context and READ as an object, its properties bound
+// at positions of the template. The fill on the other side receives the
+// args as reactive props and returns the values; the runtime writes each
+// bound position, re-runs the fill when the args change (a refetch) or the
+// client's state does (an optimistic write), and morphs around the
+// positions so a new response never clobbers a client-owned value.
+//
+// One call per data context: `props.row(entity)` is the row's whole client
+// behavior, consumed by the row's , its checkbox and its buttons
+// (../todo-row.tsx); `props.list(...)` is the list-level behavior consumed
+// by the section, the toggle-all box, the footer and the clear button.
+//
+// The one thing the client cannot bind is a row the server has not
+// rendered — an optimistic add — so `;
+ pending: Slot;
+ count: Slot<{ remaining: number; total: number }>;
+ filters: AttributeSlot<{}, FilterBehavior>;
+}
+
+export async function todoListView() {
+ const todos = await db.getTodos();
+ const active = todos.filter(t => !t.completed).map(t => t.id);
+ const completed = todos.filter(t => t.completed).map(t => t.id);
+ return (props: TodoListProps) => {
+ const list = props.list({ total: todos.length, active, completed });
+ const filters = props.filters();
+ return (
+ <>
+
+
+
+
+
+
+ );
+ };
+}
+
+// The mutations. Plain server functions: the client calls them from inside
+// its actions and follows each with a refetch of `todoListView` (see
+// ../todos.ts) — the "typical multi-flight" shape, where the write and the
+// re-read are separate requests and the action's transaction spans both.
+export async function addTodo(todo: db.Todo) {
+ return db.addTodo(todo);
+}
+export async function removeTodo(id: string) {
+ return db.removeTodo(id);
+}
+export async function toggleTodo(id: string, completed: boolean) {
+ return db.toggleTodo(id, completed);
+}
+export async function toggleAll(ids: string[], completed: boolean) {
+ return db.toggleAll(ids, completed);
+}
+export async function clearCompleted(ids: string[]) {
+ return db.clearCompleted(ids);
+}
diff --git a/examples/todos-server/src/todo-row.tsx b/examples/todos-server/src/todo-row.tsx
new file mode 100644
index 000000000..6e25bf77a
--- /dev/null
+++ b/examples/todos-server/src/todo-row.tsx
@@ -0,0 +1,43 @@
+// The row. One component, no directive, no side: the server renders it for
+// every todo it has, the client renders it for every todo the server does
+// not have yet (an add in flight, or one that failed). What differs is what
+// `row` IS at the call site — on the server an ATTRIBUTE SLOT (server/todos.tsx:
+// `props.row({ id, completed })`), whose properties are stand-ins the
+// positions below bind and the client owns; on the client the fill's result
+// itself (app.tsx: `rowFor(todo)`), so the same positions are ordinary
+// bindings. The component cannot tell and does not need to.
+//
+// Keys are semantic, positions are structural: nothing in `RowBehavior` says
+// attribute, class or handler — where each property is bound below does.
+
+/** What the client decides about a row: the values and behavior it owns. */
+export interface RowBehavior {
+ rowClass: Record;
+ removed: boolean;
+ done: boolean;
+ onToggle: (e: InputEvent & { currentTarget: HTMLInputElement }) => void;
+ onRemove: () => void;
+ onRetry: () => void;
+ error: string | undefined;
+}
+
+export function TodoRow(props: { id: string; title: string; row: RowBehavior }) {
+ // `$key` is the 's MORPH identity (server markup: a response keeps the
+ // node for the same todo); a DOM compile strips it. The `row` call's own
+ // `$key` is the occurrence's identity — two keys, two jobs.
+ return (
+
+
+ );
+}
diff --git a/examples/todos-server/src/todos.ts b/examples/todos-server/src/todos.ts
new file mode 100644
index 000000000..eb73a8f35
--- /dev/null
+++ b/examples/todos-server/src/todos.ts
@@ -0,0 +1,220 @@
+// The client's half of the list. Compare with ../../todos/src/todos.ts: the
+// SPA keeps the whole todo array on the client and layers optimistic writes
+// and errors over it. Here the array is server markup that the client never
+// holds — what it holds is INTENT (what it has asked the server to do and
+// not yet heard back about) and the errors it heard back. Both are keyed by
+// entity id, and the fills in app.tsx combine them with the args each server
+// element carries.
+//
+// Same three lifetime layers as the SPA, same order, without the array:
+//
+// 3. Optimistic (transition-scoped) ── `intent`, a `createOptimisticStore`
+// written inside `action` generators;
+// auto-reverts when the action settles,
+// which is when the server's answer
+// has APPLIED (see the actions).
+// 2. Ephemeral (UI-scoped) ── `errors`, a plain store written after
+// the call fails. Survives the revert
+// because it is not optimistic.
+// 1. Persistent (durable) ── the server's rows: `p.completed` in
+// a fill's props is truth as of the
+// last response.
+//
+// Every fill reads (3) over (1) and shows (2) beside it.
+//
+// Pending rows are not inert (parity with the SPA): a toggle or remove on a
+// todo whose add is still in flight writes its intent immediately and then
+// waits for the add to settle before talking to the server — the server
+// has no such id until then. A todo whose add FAILED exists only here, so
+// those actions edit the failed record instead (the retry carries the
+// change).
+
+import { action, createMemo, createOptimisticStore, createStore, refresh } from "solid-js";
+import type { Todo } from "~/lib/db";
+import * as server from "~/server/todos";
+
+export type { Todo };
+
+export type TodoError = {
+ type: "addTodo" | "removeTodo" | "toggleTodo";
+ args: any[];
+};
+
+export interface Intent {
+ /** The server's `completed` when the intent was written (for the counts). */
+ from: boolean;
+ completed?: boolean;
+ removed?: boolean;
+}
+
+export function createTodos() {
+ // The source the boundary shows and the actions refetch. `refresh(todos)`
+ // re-runs the memo, which re-calls the server component; the transaction
+ // holds until the refetched markup and args have applied.
+ const todos = createMemo(() => server.todoListView());
+
+ const [intent, setIntent] = createOptimisticStore<{
+ byId: Record;
+ adds: Todo[];
+ }>({ byId: {}, adds: [] });
+
+ const [errors, setErrors] = createStore>({});
+
+ /** Adds in flight, by id: what a toggle/remove on a pending row waits on. */
+ const inflight = new Map>();
+ /** The failed add a todo exists in, if that is the only place it exists. */
+ const failedAdd = (id: string) => (errors[id]?.type === "addTodo" ? errors[id] : undefined);
+
+ /** The client's view of one entity's `completed`: intent over the server. */
+ const done = (id: string, completed: boolean) => intent.byId[id]?.completed ?? completed;
+ const removed = (id: string) => !!intent.byId[id]?.removed;
+
+ /** Todos the server does not have: in-flight adds, then adds that failed.
+ * The store's own objects, not copies: their identity is stable across
+ * reads, so a `` over them keeps each row's node while the list
+ * around it changes. */
+ const extraRows = (): Todo[] => {
+ const rows: Todo[] = [...intent.adds];
+ for (const id in errors) {
+ const error = errors[id];
+ if (error?.type === "addTodo" && !rows.some(r => r.id === id)) rows.push(error.args[0]);
+ }
+ return rows.sort((a, b) => (a.id > b.id ? 1 : -1));
+ };
+
+ /** Counts as the client sees them: the server's, adjusted by intent. */
+ const counts = (p: { remaining: number; total: number }) => {
+ let remaining = p.remaining;
+ let total = p.total;
+ const extra = extraRows();
+ for (const id in intent.byId) {
+ // Intent over a row the server has; a pending row's intent is read
+ // with the row below.
+ if (extra.some(t => t.id === id)) continue;
+ const i = intent.byId[id];
+ if (i.removed) {
+ total--;
+ if (!i.from) remaining--;
+ } else if (i.completed !== undefined && i.completed !== i.from) {
+ remaining += i.completed ? -1 : 1;
+ }
+ }
+ for (const t of extra) {
+ if (removed(t.id)) continue;
+ total++;
+ if (!done(t.id, t.completed)) remaining++;
+ }
+ return { remaining, total };
+ };
+
+ function fail(id: string, error: TodoError) {
+ setErrors(e => {
+ e[id] ||= error;
+ });
+ }
+ function ok(id: string) {
+ setErrors(e => {
+ delete e[id];
+ });
+ }
+
+ const add = action(function* (todo: Todo) {
+ setIntent(s => {
+ if (!s.adds.some(t => t.id === todo.id)) s.adds.push(todo);
+ });
+ try {
+ yield server.addTodo(todo);
+ ok(todo.id);
+ } catch {
+ fail(todo.id, { type: "addTodo", args: [todo] });
+ }
+ yield refresh(todos);
+ });
+
+ const actions = {
+ addTodo(todo: Todo): Promise {
+ const p = add(todo).finally(() => {
+ if (inflight.get(todo.id) === p) inflight.delete(todo.id);
+ });
+ inflight.set(todo.id, p);
+ return p;
+ },
+ removeTodo: action(function* (id: string, completed: boolean) {
+ setIntent(s => {
+ s.byId[id] = { from: completed, removed: true };
+ });
+ // Sequenced behind the add the server has not answered yet.
+ const pending = inflight.get(id);
+ if (pending) yield pending;
+ if (failedAdd(id)) {
+ // The todo never reached the server: removing it is forgetting it.
+ ok(id);
+ return;
+ }
+ try {
+ yield server.removeTodo(id);
+ ok(id);
+ } catch {
+ fail(id, { type: "removeTodo", args: [id, completed] });
+ }
+ yield refresh(todos);
+ }),
+ toggleTodo: action(function* (id: string, completed: boolean) {
+ setIntent(s => {
+ s.byId[id] = { from: !completed, completed };
+ });
+ const pending = inflight.get(id);
+ if (pending) yield pending;
+ const failed = failedAdd(id);
+ if (failed) {
+ // The todo exists only in its failed add: the retry adds it toggled.
+ setErrors(e => {
+ (e[id]!.args[0] as Todo).completed = completed;
+ });
+ return;
+ }
+ try {
+ yield server.toggleTodo(id, completed);
+ ok(id);
+ } catch {
+ fail(id, { type: "toggleTodo", args: [id, completed] });
+ }
+ yield refresh(todos);
+ }),
+ toggleAll: action(function* (ids: string[], completed: boolean) {
+ setIntent(s => {
+ for (const id of ids) s.byId[id] = { from: !completed, completed };
+ });
+ try {
+ yield server.toggleAll(ids, completed);
+ ids.forEach(ok);
+ } catch {
+ // Bulk failed — fan the error out to per-item entries so each
+ // failed item gets its own retry affordance via `retryTodo`.
+ ids.forEach(id => fail(id, { type: "toggleTodo", args: [id, completed] }));
+ }
+ yield refresh(todos);
+ }),
+ clearCompleted: action(function* (ids: string[]) {
+ setIntent(s => {
+ for (const id of ids) s.byId[id] = { from: true, removed: true };
+ });
+ try {
+ yield server.clearCompleted(ids);
+ ids.forEach(ok);
+ } catch {
+ ids.forEach(id => fail(id, { type: "removeTodo", args: [id, true] }));
+ }
+ yield refresh(todos);
+ }),
+ retryTodo(id: string): Promise {
+ const error = errors[id];
+ if (!error) return Promise.resolve();
+ return (actions[error.type] as (...args: any[]) => Promise)(...error.args);
+ }
+ };
+
+ return { todos, intent, errors, done, removed, extraRows, counts, actions };
+}
+
+export type Todos = ReturnType;
diff --git a/examples/todos-server/src/vite-env.d.ts b/examples/todos-server/src/vite-env.d.ts
new file mode 100644
index 000000000..11f02fe2a
--- /dev/null
+++ b/examples/todos-server/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// 0,
attributes = normalizeAttributes(path);
let children: babelTypes.JSXExpressionContainer | undefined;
- // Server-components claims: ref/on* positions on server-rendered
- // intrinsics collect here and emit as one guarded whole-attribute hole
- // (` _bnd="..."` or "") after the loop. Evaluation is gated on the render
- // context's claims flag so plain SSR never runs the expressions.
+ // Server-components handler positions: ref/on* expressions on
+ // server-rendered intrinsics collect here and emit as one guarded
+ // whole-attribute hole after the loop, where `ssrClaim` turns attribute-slot
+ // reads into `_s:on:*` / `_s:ref` markers (and drops server-local
+ // functions). Evaluation is gated on the render context's claims flag so
+ // plain SSR never runs the expressions.
const claims: [string, babelTypes.Expression][] = [];
attributes.forEach(attribute => {
@@ -588,11 +590,10 @@ function transformAttributes(
}
if (key.startsWith("prop:")) return;
if (key.startsWith("on")) {
- // Capture-phase variants can't ride delegation; v1 drops them as
- // before. `on:x` keeps the raw name, `onXxx` lowercases — the same
- // event-name derivation as the client runtime.
- if (info.serverComponents && !key.startsWith("oncapture:")) {
- const pos = key.startsWith("on:") ? key.slice(3) : key.slice(2).toLowerCase();
+ // `onXxx` lowercases to the event name — the client runtime's own
+ // derivation (`onClick` -> `click`); the position is bound under it.
+ if (info.serverComponents) {
+ const pos = key.slice(2).toLowerCase();
if (pos) claims.push([pos, value.expression as babelTypes.Expression]);
}
return;
@@ -628,6 +629,30 @@ function transformAttributes(
checkMember: true,
checkTags: true
});
+ // Server components (principles §9.2.3): a dynamic `class`/`style`
+ // is the one attribute shape the plain SSR output serializes INSIDE
+ // template quotes (`class="${ssrClassName(x)}"`), where an attribute-slot
+ // value read at that position — the whole value, or a name's
+ // condition in object form — would be stringified instead of
+ // bound. Under the option the whole attribute is a runtime hole,
+ // `ssrElementAttribute("class", x)`, whose helper emits the same
+ // bytes for a plain value and the position marker for a stand-in.
+ // Object literals stay objects (no inlining) for the same reason.
+ if (info.serverComponents && (key === "class" || key === "style")) {
+ const attr = t.callExpression(registerImportMethod(path, "ssrElementAttribute"), [
+ t.stringLiteral(key),
+ value.expression as babelTypes.Expression
+ ]);
+ results.template.push("");
+ results.templateValues.push(
+ isDynamicValue
+ ? hoistExpression(path, results, t.arrowFunctionExpression([], attr), {
+ group: true
+ })
+ : attr
+ );
+ return;
+ }
let doEscape = true;
let isBoolean =
t.isBooleanLiteral(value) ||
@@ -771,23 +796,7 @@ function transformAttributes(
}
});
if (claims.length) {
- // Duplicate event keys were already last-wins-stripped above; `ref` is
- // exempt from that pass (client semantics fire every ref), so multiple
- // refs merge into an array value.
- const byPos = new Map();
- for (const [pos, expr] of claims) {
- let list = byPos.get(pos);
- if (!list) byPos.set(pos, (list = []));
- list.push(expr);
- }
- const map = t.objectExpression(
- [...byPos].map(([pos, exprs]) =>
- t.objectProperty(
- t.stringLiteral(pos),
- exprs.length === 1 ? exprs[0] : t.arrayExpression(exprs)
- )
- )
- );
+ const map = claimMap(claims);
// `_$sharedConfig.context && _$sharedConfig.context.claims
// ? _$ssrClaim({...}) : ""`
// — the claims flag is only set inside a server component's render
@@ -933,7 +942,7 @@ function transformChildren(
function createElement(
path: BabelPath & { doNotEscape?: boolean },
- { topLevel, hydratable }: SSRTransformInfo
+ { topLevel, hydratable, serverComponents }: SSRTransformInfo
): SSRSpreadTransformResult {
const tagName = getTagName(path.node),
config = getConfig(path),
@@ -986,6 +995,21 @@ function createElement(
const node = attribute.node;
return !(t.isJSXAttribute(node) && t.isJSXIdentifier(node.name) && node.name.name === "ref");
});
+ // Server components (principles §9.2.3): the named `ref`/`on*` attributes
+ // of a spread element are handler positions like a template element's,
+ // and compile to the same claim map — `{ click: expr, ref: [a, b] }`,
+ // duplicate refs merged, a duplicate handler last-wins as the template
+ // path strips it — keyed by the index of the source each attribute sits
+ // before (`` → `{ 1: { click: go } }`, the
+ // spreads being sources 0 and 2), and handed to `ssrElement` as a thunk
+ // it reads only inside a server component's render (the gate the template
+ // path's `ssrClaim` guard reads), so plain SSR never evaluates the
+ // expressions. The runtime settles each handler position in source order,
+ // as the client's `spread(el, [a, { onClick: go }, b])` does — a spread at
+ // that index or later that HAS the key owns it — and merges every ref.
+ // Plain SSR output is unchanged (dropped, as a server element has no
+ // handlers to run).
+ const claims: [number, string, babelTypes.Expression][] = [];
let props: babelTypes.Expression[];
// Attributes written AFTER the last spread are markup, not a source: no
@@ -1006,7 +1030,13 @@ function createElement(
// keys.
const tail: Array = [];
const skipKeys: string[] = [];
- if (propAttributes.length === 1 && t.isJSXSpreadAttribute(propAttributes[0].node)) {
+ if (
+ propAttributes.length === 1 &&
+ t.isJSXSpreadAttribute(propAttributes[0].node) &&
+ // A `ref` beside the lone spread is a claim under `serverComponents`;
+ // the loop below places it.
+ !(serverComponents && attributes.length > 1)
+ ) {
props = [propAttributes[0].node.argument];
} else {
props = [];
@@ -1052,8 +1082,30 @@ function createElement(
: node.name.name;
if (hasChildren && key === "children") return;
- if (key === "ref") return;
- if (key.startsWith("prop:") || key.startsWith("on")) return;
+ if (key === "ref" || key.startsWith("on")) {
+ if (serverComponents && t.isJSXExpressionContainer(value)) {
+ const expression = value.expression;
+ const pos = key === "ref" ? "ref" : key.slice(2).toLowerCase();
+ if (
+ pos &&
+ !(
+ t.isJSXEmptyExpression(expression) ||
+ t.isStringLiteral(expression) ||
+ t.isNumericLiteral(expression) ||
+ t.isBooleanLiteral(expression)
+ )
+ ) {
+ // The index of the source this attribute sits before: the
+ // sources pushed so far, plus the running literal if it will
+ // be pushed ahead of the next spread. The literal never
+ // carries a handler key, so a spread's index is either below
+ // this or at/after it — never ambiguous.
+ claims.push([props.length + (runningObject.length ? 1 : 0), pos, expression]);
+ }
+ }
+ return;
+ }
+ if (key.startsWith("prop:")) return;
if (i > lastSpread) {
const part = tailAttribute(path, tagName, key, node);
if (part !== undefined) {
@@ -1130,10 +1182,65 @@ function createElement(
}
args.push(registerSkip(path, skipKeys), markup);
}
+ if (claims.length) {
+ if (!skipKeys.length) args.push(t.identifier("undefined"), t.identifier("undefined"));
+ args.push(t.arrowFunctionExpression([], claimSegments(claims)));
+ }
const exprs = [t.callExpression(registerImportMethod(path, "ssrElement"), args)];
return { exprs, template: "", declarations: [], dynamics: [], spreadElement: true };
}
+/**
+ * A spread element's claim map by source index (`createElement`): `{ 1: {
+ * click: go }, 3: { ref: el } }`. A handler position keeps its LAST named
+ * attribute only — the template path's duplicate strip, applied here to the
+ * claims (a later attribute wins whatever sits between, so the earlier one
+ * is never read on either side); refs merge within a segment as `claimMap`
+ * merges them, and across segments at the runtime.
+ */
+function claimSegments(
+ claims: [number, string, babelTypes.Expression][]
+): babelTypes.ObjectExpression {
+ const lastHandler = new Map();
+ claims.forEach(([, pos], i) => {
+ if (pos !== "ref") lastHandler.set(pos, i);
+ });
+ const segments = new Map();
+ claims.forEach(([index, pos, expr], i) => {
+ if (pos !== "ref" && lastHandler.get(pos) !== i) return;
+ let list = segments.get(index);
+ if (!list) segments.set(index, (list = []));
+ list.push([pos, expr]);
+ });
+ return t.objectExpression(
+ [...segments].map(([index, list]) => t.objectProperty(t.numericLiteral(index), claimMap(list)))
+ );
+}
+
+/**
+ * The compiled claim map of an element's handler positions, `{ click: expr,
+ * ref: [a, b] }`: duplicate event keys were last-wins-stripped by the
+ * template path's duplicate strip (or `claimSegments`); `ref` is exempt from
+ * that pass (client semantics fire every ref), so multiple refs merge into
+ * an array value.
+ */
+function claimMap(claims: [string, babelTypes.Expression][]): babelTypes.ObjectExpression {
+ const byPos = new Map();
+ for (const [pos, expr] of claims) {
+ let list = byPos.get(pos);
+ if (!list) byPos.set(pos, (list = []));
+ list.push(expr);
+ }
+ return t.objectExpression(
+ [...byPos].map(([pos, exprs]) =>
+ t.objectProperty(
+ t.stringLiteral(pos),
+ exprs.length === 1 ? exprs[0] : t.arrayExpression(exprs)
+ )
+ )
+ );
+}
+
/**
* What an attribute after an element's last spread contributes to
* `ssrElement`'s attribute string. A static is written as the template path
diff --git a/packages/babel-plugin/test/__dom_fixtures__/keyedElements/code.js b/packages/babel-plugin/test/__dom_fixtures__/keyedElements/code.js
index 7c3d2df7b..bf9ded58b 100644
--- a/packages/babel-plugin/test/__dom_fixtures__/keyedElements/code.js
+++ b/packages/babel-plugin/test/__dom_fixtures__/keyedElements/code.js
@@ -18,3 +18,14 @@ const dynamicKey = (
);
const componentKey = |
;
+
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = (
+ |
;
+
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = (
+ |
;
+
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = (
+ "];
+ _tmpl$2 = [" "],
+ _tmpl$3 = ["
+ {label()}
+
+);
+
+const objects = (
+
+
+ {label()}
+
+);
diff --git a/packages/babel-plugin/test/__ssr_server_components_fixtures__/attributeSlots/output.js b/packages/babel-plugin/test/__ssr_server_components_fixtures__/attributeSlots/output.js
new file mode 100644
index 000000000..120267788
--- /dev/null
+++ b/packages/babel-plugin/test/__ssr_server_components_fixtures__/attributeSlots/output.js
@@ -0,0 +1,161 @@
+import { ssrAttribute as _$ssrAttribute } from "r-server";
+import { ssrGroup as _$ssrGroup } from "r-server";
+import { escape as _$escape } from "r-server";
+import { ssrElementAttribute as _$ssrElementAttribute } from "r-server";
+import { ssrElement as _$ssrElement } from "r-server";
+import { ssr as _$ssr } from "r-server";
+import { ssrClaim as _$ssrClaim } from "r-server";
+import { sharedConfig as _$sharedConfig } from "r-server";
+var _tmpl$ = [
+ 'warns at render when the gate is openmultiple refs merge to an array ", ""],
+ _tmpl$3 = [
+ "',
+ ""
+ ];
+var _sk$ = k => k === "class";
+var _v$ =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ click: props.onCopy,
+ ref: props.btn
+ })
+ : "",
+ _v$2 =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ input: props.onType,
+ keydown: props.onKey
+ })
+ : "",
+ _v$3 =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ click: localHandler
+ })
+ : "",
+ _v$4 =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ ref: [first, second]
+ })
+ : "";
+// Attribute slots (principles §9.2.3). Ref/event positions on server intrinsics
+// compile to one guarded whole-attribute claim hole per element, gated on
+// the render context's claims flag so plain SSR never evaluates the
+// expressions.
+const template = _$ssr(_tmpl$, _v$, _v$2, _v$3, _v$4);
+
+// A spread element's named `ref`/`on*` compile to the same claim map a
+// template element's do — duplicate refs merged, a tuple kept whole, a
+// duplicate handler last-wins — keyed by the index of the source each
+// attribute sits before, handed to `ssrElement` as a thunk it reads only
+// inside a server component's render, wherever the attributes sit relative
+// to the spreads (before, between, after): the runtime settles a handler
+// position in source order, as the client's spread does. Plain SSR
+// drops them; the tail after the last spread still bakes its statics; the
+// spread's own handler keys are the runtime's to bind.
+const spread = _$ssrElement(
+ "button",
+ rest,
+ [
+ _$ssrElement("span", [more, last], undefined, false, undefined, undefined, () => ({
+ 0: {
+ input: row.type
+ },
+ 1: {
+ keydown: [row.key, 1]
+ }
+ })),
+ _$ssrElement("i", last, undefined, false, undefined, undefined, () => ({
+ 0: {
+ ref: [[row.a, row.b], row.c]
+ },
+ 1: {
+ click: localHandler
+ }
+ })),
+ _$ssrElement(
+ "em",
+ [
+ rest,
+ {
+ title: "t"
+ },
+ last
+ ],
+ undefined,
+ false,
+ undefined,
+ undefined,
+ () => ({
+ 2: {
+ click: row.third
+ }
+ })
+ ),
+ _$ssrElement("u", rest, undefined, false, undefined, undefined, () => ({
+ 1: {
+ ref: row.el
+ }
+ }))
+ ],
+ false,
+ _sk$,
+ ' class="static"',
+ () => ({
+ 1: {
+ click: row.go,
+ ref: row.el
+ }
+ })
+);
+
+// A dynamic `class`/`style` is a whole-attribute element-attribute hole
+// rather than a value inside template quotes, so a slot value read at the
+// position — whole, or as a name's condition in object form — binds instead
+// of stringifying. Object literals stay objects. Static strings stay static.
+var _g$ = _$ssrGroup(
+ () => [_$ssrElementAttribute("class", status()), _$ssrElementAttribute("style", row.style)],
+ 2
+ ),
+ _v$7 =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ click: props.onPick
+ })
+ : "",
+ _v$8 = () => _$escape(label());
+const dynamicToo = _$ssr(_tmpl$2, _g$, _g$, _v$7, _v$8);
+var _g$2 = _$ssrGroup(
+ () => [
+ _$ssrElementAttribute("class", {
+ completed: row.done,
+ editing: row.editing
+ }),
+ _$ssrElementAttribute("style", {
+ color: row.color
+ })
+ ],
+ 2
+ ),
+ _v$10 = () => _$ssrAttribute("hidden", _$escape(row.removed, true)),
+ _v$11 =
+ _$sharedConfig.context && _$sharedConfig.context.claims
+ ? _$ssrClaim({
+ input: row.toggle
+ })
+ : "",
+ _v$12 = () => _$escape(label()),
+ _v$1 = () => _$ssrAttribute("checked", _$escape(row.done, true));
+const objects = _$ssr(_tmpl$3, _g$2, _g$2, _v$1, _v$10, _v$11, _v$12);
diff --git a/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/code.js b/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/code.js
deleted file mode 100644
index 87a5dc2db..000000000
--- a/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/code.js
+++ /dev/null
@@ -1,22 +0,0 @@
-// Ref/event positions on server intrinsics compile to one guarded
-// whole-attribute claim hole per element (`_bnd`), gated on the render
-// context's claims flag so plain SSR never evaluates the expressions.
-const template = (
-
- {label()}
-
-);
diff --git a/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/output.js b/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/output.js
deleted file mode 100644
index 23d4d31de..000000000
--- a/packages/babel-plugin/test/__ssr_server_components_fixtures__/behaviorClaims/output.js
+++ /dev/null
@@ -1,52 +0,0 @@
-import { escape as _$escape } from "r-server";
-import { ssrClassName as _$ssrClassName } from "r-server";
-import { ssr as _$ssr } from "r-server";
-import { ssrClaim as _$ssrClaim } from "r-server";
-import { sharedConfig as _$sharedConfig } from "r-server";
-var _tmpl$ = [
- 'warns at render when the gate is openmultiple refs merge to an arraycapture variants stay dropped ", " "];
-var _v$ =
- _$sharedConfig.context && _$sharedConfig.context.claims
- ? _$ssrClaim({
- click: props.onCopy,
- ref: props.btn
- })
- : "",
- _v$2 =
- _$sharedConfig.context && _$sharedConfig.context.claims
- ? _$ssrClaim({
- input: props.onType,
- "custom-thing": props.onCustom
- })
- : "",
- _v$3 =
- _$sharedConfig.context && _$sharedConfig.context.claims
- ? _$ssrClaim({
- click: localHandler
- })
- : "",
- _v$4 =
- _$sharedConfig.context && _$sharedConfig.context.claims
- ? _$ssrClaim({
- ref: [first, second]
- })
- : "";
-// Ref/event positions on server intrinsics compile to one guarded
-// whole-attribute claim hole per element (`_bnd`), gated on the render
-// context's claims flag so plain SSR never evaluates the expressions.
-const template = _$ssr(_tmpl$, _v$, _v$2, _v$3, _v$4);
-var _v$5 = () => _$ssrClassName(status()),
- _v$6 =
- _$sharedConfig.context && _$sharedConfig.context.claims
- ? _$ssrClaim({
- click: props.onPick
- })
- : "",
- _v$7 = () => _$escape(label());
-const dynamicToo = _$ssr(_tmpl$2, _v$5, _v$6, _v$7);
diff --git a/packages/compiler/__tests__/fixtures/dom-hydratable/keyedElements/output.js b/packages/compiler/__tests__/fixtures/dom-hydratable/keyedElements/output.js
index 89a1c85da..619f399ff 100644
--- a/packages/compiler/__tests__/fixtures/dom-hydratable/keyedElements/output.js
+++ b/packages/compiler/__tests__/fixtures/dom-hydratable/keyedElements/output.js
@@ -3,9 +3,11 @@ import { getNextElement as _$getNextElement } from "r-dom";
import { insert as _$insert } from "r-dom";
import { scope as _$scope } from "r-dom";
import { createComponent as _$createComponent } from "r-dom";
+import { spread as _$spread } from "r-dom";
import { readShallow as _$readShallow } from "r-dom";
import { className as _$className } from "r-dom";
import { effect as _$effect } from "r-dom";
+import { runHydrationEvents as _$runHydrationEvents } from "r-dom";
var _tmpl$ = /* @__PURE__ */ _$template(`
-
}>
-
-
-
- 
-
- Solid Notes
+ }) => {
+ const search = props.search();
+ return (
+ {props.children}
+
+ );
+ };
}
diff --git a/examples/todos-server/README.md b/examples/todos-server/README.md
new file mode 100644
index 000000000..c458e060b
--- /dev/null
+++ b/examples/todos-server/README.md
@@ -0,0 +1,119 @@
+# Todos — TodoMVC as a Solid Server Component
+
+The [../todos](../todos) example, with the list moved to the server. The
+markup that the SPA's `MainSection`, `TodoItem` and `Footer` produced is now
+returned by one `"use server"` component and arrives as HTML; the browser
+keeps the header, the optimistic state, and — the point of this example —
+every behavior those components had, bound to the server's own elements
+through **attribute slots**. The row is one component, `TodoRow`, that both
+sides render.
+
+Same deliberately unreliable API as the SPA (400 ms saves, ~33% of them
+fail), so the optimistic UI, the per-item errors and the retry affordances
+get exercised.
+
+```sh
+pnpm dev # http://localhost:3010
+pnpm build && pnpm start # http://localhost:3010
+```
+
+## Attribute slots
+
+A slot renders one of two things: markup (placed as `
-
- Solid Notes
+ }) => {
+ const search = props.search();
+ return (
+
+
+
+
+
+
+ Solid Notes
+
+
+
-
-
-
- {props.children}
-
- );
+
+
+ Solid Notes
+ -
+ {todos.map(t => (
+
todos
+ { + if (e.key !== "Enter") return; + const title = e.currentTarget.value.trim(); + if (!title) return; + const id = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`; + actions.addTodo({ id, title, completed: false }); + e.currentTarget.value = ""; + }} + /> +
+
+ )}
+ >
+ Something went wrong: {String(err())}
+ +-
+ {todos.map(t => (
+
+
+
+
+
+
+ -
+
- + {item.text} + +
-
+
- + {item.text} + +
-
+
- + {item.text} + +
- Apple
- ", "
+
+
+ warns at render when the gate is open
+
+ multiple refs merge to an array
+
+
+);
+
+// A spread element's named `ref`/`on*` compile to the same claim map a
+// template element's do — duplicate refs merged, a tuple kept whole, a
+// duplicate handler last-wins — keyed by the index of the source each
+// attribute sits before, handed to `ssrElement` as a thunk it reads only
+// inside a server component's render, wherever the attributes sit relative
+// to the spreads (before, between, after): the runtime settles a handler
+// position in source order, as the client's spread does. Plain SSR
+// drops them; the tail after the last spread still bakes its statics; the
+// spread's own handler keys are the runtime's to bind.
+const spread = (
+
+);
+
+// A dynamic `class`/`style` is a whole-attribute element-attribute hole
+// rather than a value inside template quotes, so a slot value read at the
+// position — whole, or as a name's condition in object form — binds instead
+// of stringifying. Object literals stay objects. Static strings stay static.
+const dynamicToo = (
+
-
-
- warns at render when the gate is open
-
- multiple refs merge to an array
-
- capture variants stay dropped
-
-);
-
-const dynamicToo = (
- - Apple`);
var _tmpl$2 = /* @__PURE__ */ _$template(`
- `);
// `$key` is server markup identity (SSR-only): a DOM compile strips it from
@@ -31,3 +33,16 @@ const componentKey = _$createComponent(Row, {
return item.text;
}
});
+var _el$4 = _$getNextElement(_tmpl$2);
+var _el$5 = _el$4.firstChild;
+_$spread(_el$5, [{ class: "todo" }, () => {
+ return item.attrs;
+}], true);
+_$insert(_el$5, _$scope(() => {
+ return item.text;
+}));
+_$runHydrationEvents();
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = _el$4;
diff --git a/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js b/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
index 59b570c4b..dded0ad8c 100644
--- a/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
+++ b/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
@@ -1,6 +1,7 @@
import { template as _$template } from "r-dom";
import { insert as _$insert } from "r-dom";
import { createComponent as _$createComponent } from "r-dom";
+import { spread as _$spread } from "r-dom";
import { readShallow as _$readShallow } from "r-dom";
import { className as _$className } from "r-dom";
import { effect as _$effect } from "r-dom";
@@ -29,3 +30,15 @@ const componentKey = _$createComponent(Row, {
return item.text;
}
});
+var _el$4 = _tmpl$2();
+var _el$5 = _el$4.firstChild;
+_$spread(_el$5, [{ class: "todo" }, () => {
+ return item.attrs;
+}], true);
+_$insert(_el$5, () => {
+ return item.text;
+});
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = _el$4;
diff --git a/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js b/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js
new file mode 100644
index 000000000..9e24b682a
--- /dev/null
+++ b/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js
@@ -0,0 +1,95 @@
+import { escape as _$escape } from "r-server";
+import { ssr as _$ssr } from "r-server";
+import { ssrAttribute as _$ssrAttribute } from "r-server";
+import { ssrGroup as _$ssrGroup } from "r-server";
+import { ssrElement as _$ssrElement } from "r-server";
+import { ssrElementAttribute as _$ssrElementAttribute } from "r-server";
+import { ssrClaim as _$ssrClaim } from "r-server";
+import { sharedConfig as _$sharedConfig } from "r-server";
+var _tmpl$ = [
+ "" +]; +var _tmpl$2 = [ + " "
+];
+var _tmpl$3 = [
+ "
"
+];
+var _sk$ = (k) => k === "class";
+var _v$ = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({
+ click: props.onCopy,
+ ref: props.btn
+}) : "", _v$2 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({
+ input: props.onType,
+ keydown: props.onKey
+}) : "", _v$3 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ click: localHandler }) : "", _v$4 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ ref: [first, second] }) : "";
+// Attribute slots (principles §9.2.3). Ref/event positions on server intrinsics
+// compile to one guarded whole-attribute claim hole per element, gated on
+// the render context's claims flag so plain SSR never evaluates the
+// expressions.
+const template = _$ssr(_tmpl$, _v$, _v$2, _v$3, _v$4);
+// A spread element's named `ref`/`on*` compile to the same claim map a
+// template element's do — duplicate refs merged, a tuple kept whole, a
+// duplicate handler last-wins — keyed by the index of the source each
+// attribute sits before, handed to `ssrElement` as a thunk it reads only
+// inside a server component's render, wherever the attributes sit relative
+// to the spreads (before, between, after): the runtime settles a handler
+// position in source order, as the client's spread does. Plain SSR
+// drops them; the tail after the last spread still bakes its statics; the
+// spread's own handler keys are the runtime's to bind.
+const spread = _$ssrElement("button", rest, [
+ _$ssrElement("span", [more, last], undefined, false, undefined, undefined, () => ({
+ 0: { input: row.type },
+ 1: { keydown: [row.key, 1] }
+ })),
+ _$ssrElement("i", last, undefined, false, undefined, undefined, () => ({
+ 0: { ref: [[row.a, row.b], row.c] },
+ 1: { click: localHandler }
+ })),
+ _$ssrElement("em", [
+ rest,
+ { title: "t" },
+ last
+ ], undefined, false, undefined, undefined, () => ({ 2: { click: row.third } })),
+ _$ssrElement("u", rest, undefined, false, undefined, undefined, () => ({ 1: { ref: row.el } }))
+], false, _sk$, " class=\"static\"", () => ({ 1: {
+ click: row.go,
+ ref: row.el
+} }));
+var _g$ = _$ssrGroup(() => {
+ return [_$ssrElementAttribute("class", status()), _$ssrElementAttribute("style", row.style)];
+}, 2), _v$7 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ click: props.onPick }) : "", _v$8 = () => {
+ return _$escape(label());
+};
+// A dynamic `class`/`style` is a whole-attribute element-attribute hole
+// rather than a value inside template quotes, so a slot value read at the
+// position — whole, or as a name's condition in object form — binds instead
+// of stringifying. Object literals stay objects. Static strings stay static.
+const dynamicToo = _$ssr(_tmpl$2, _g$, _g$, _v$7, _v$8);
+var _g$2 = _$ssrGroup(() => {
+ return [_$ssrElementAttribute("class", {
+ completed: row.done,
+ editing: row.editing
+ }), _$ssrElementAttribute("style", { color: row.color })];
+}, 2), _v$12 = () => {
+ return _$ssrAttribute("hidden", _$escape(row.removed, true));
+}, _v$13 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ input: row.toggle }) : "", _v$14 = () => {
+ return _$escape(label());
+}, _v$11 = () => {
+ return _$ssrAttribute("checked", _$escape(row.done, true));
+};
+const objects = _$ssr(_tmpl$3, _g$2, _g$2, _v$11, _v$12, _v$13, _v$14);
diff --git a/packages/compiler/__tests__/fixtures/ssr-server-components/behaviorClaims/output.js b/packages/compiler/__tests__/fixtures/ssr-server-components/behaviorClaims/output.js
deleted file mode 100644
index 3d214ebbf..000000000
--- a/packages/compiler/__tests__/fixtures/ssr-server-components/behaviorClaims/output.js
+++ /dev/null
@@ -1,35 +0,0 @@
-import { escape as _$escape } from "r-server";
-import { ssr as _$ssr } from "r-server";
-import { ssrClassName as _$ssrClassName } from "r-server";
-import { ssrClaim as _$ssrClaim } from "r-server";
-import { sharedConfig as _$sharedConfig } from "r-server";
-var _tmpl$ = [
- " - `);
// `$key` is server markup identity (SSR-only): a DOM compile strips it from
@@ -31,3 +33,16 @@ const componentKey = _$createComponent(Row, {
return item.text;
}
});
+var _el$4 = _$getNextElement(_tmpl$2);
+var _el$5 = _el$4.firstChild;
+_$spread(_el$5, [{ class: "todo" }, () => {
+ return item.attrs;
+}], true);
+_$insert(_el$5, _$scope(() => {
+ return item.text;
+}));
+_$runHydrationEvents();
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = _el$4;
diff --git a/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js b/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
index 59b570c4b..dded0ad8c 100644
--- a/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
+++ b/packages/compiler/__tests__/fixtures/dom/keyedElements/output.js
@@ -1,6 +1,7 @@
import { template as _$template } from "r-dom";
import { insert as _$insert } from "r-dom";
import { createComponent as _$createComponent } from "r-dom";
+import { spread as _$spread } from "r-dom";
import { readShallow as _$readShallow } from "r-dom";
import { className as _$className } from "r-dom";
import { effect as _$effect } from "r-dom";
@@ -29,3 +30,15 @@ const componentKey = _$createComponent(Row, {
return item.text;
}
});
+var _el$4 = _tmpl$2();
+var _el$5 = _el$4.firstChild;
+_$spread(_el$5, [{ class: "todo" }, () => {
+ return item.attrs;
+}], true);
+_$insert(_el$5, () => {
+ return item.text;
+});
+// On a spread element the same rule applies to the spread path: the key
+// joins the element's sources (renamed for SSR, dropped for DOM) rather than
+// the template.
+const spreadKey = _el$4;
diff --git a/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js b/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js
new file mode 100644
index 000000000..9e24b682a
--- /dev/null
+++ b/packages/compiler/__tests__/fixtures/ssr-server-components/attributeSlots/output.js
@@ -0,0 +1,95 @@
+import { escape as _$escape } from "r-server";
+import { ssr as _$ssr } from "r-server";
+import { ssrAttribute as _$ssrAttribute } from "r-server";
+import { ssrGroup as _$ssrGroup } from "r-server";
+import { ssrElement as _$ssrElement } from "r-server";
+import { ssrElementAttribute as _$ssrElementAttribute } from "r-server";
+import { ssrClaim as _$ssrClaim } from "r-server";
+import { sharedConfig as _$sharedConfig } from "r-server";
+var _tmpl$ = [
+ "
- ", - " " -]; -var _v$ = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ - click: props.onCopy, - ref: props.btn -}) : "", _v$2 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ - input: props.onType, - "custom-thing": props.onCustom -}) : "", _v$3 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ click: localHandler }) : "", _v$4 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ ref: [first, second] }) : ""; -// Ref/event positions on server intrinsics compile to one guarded -// whole-attribute claim hole per element (`_bnd`), gated on the render -// context's claims flag so plain SSR never evaluates the expressions. -const template = _$ssr(_tmpl$, _v$, _v$2, _v$3, _v$4); -var _v$5 = () => { - return _$ssrClassName(status()); -}, _v$6 = _$sharedConfig.context && _$sharedConfig.context.claims ? _$ssrClaim({ click: props.onPick }) : "", _v$7 = () => { - return _$escape(label()); -}; -const dynamicToo = _$ssr(_tmpl$2, _v$5, _v$6, _v$7); diff --git a/packages/compiler/__tests__/fixtures/ssr/keyedElements/output.js b/packages/compiler/__tests__/fixtures/ssr/keyedElements/output.js index 1707761c0..4bc54bf9d 100644 --- a/packages/compiler/__tests__/fixtures/ssr/keyedElements/output.js +++ b/packages/compiler/__tests__/fixtures/ssr/keyedElements/output.js @@ -3,6 +3,7 @@ import { ssr as _$ssr } from "r-server"; import { ssrAttribute as _$ssrAttribute } from "r-server"; import { ssrClassName as _$ssrClassName } from "r-server"; import { ssrGroup as _$ssrGroup } from "r-server"; +import { ssrElement as _$ssrElement } from "r-server"; var _tmpl$ = "
- Apple
- `. One proxy over the range: the keys the engine
+// reads off a range pass through — an EXPLICIT set, the same on both faces
+// (the document face's range is an array, the stream face's a plain
+// object, and `key in target` would let `filter`/`at`/`sort`/`map` fall
+// through to Array.prototype on one face only, writing function source
+// into the markup); any other string key is a property READ, answered
+// with a `SLOT_VALUE` stand-in naming the occurrence and the key, carrying
+// the t=0 value when the fill ran. The attribute helpers (`@solidjs/web`
+// server) bind the position where the stand-in lands. Reserved for the
+// fill's output, therefore, and nothing else: `$`-prefixed keys, symbols,
+// `length`, numeric indices and `slice` (the resolver's array reads — the
+// copy `escape` takes of a placed range), the node keys `t`/`h`/`p`, `then`
+// (thenable probes), and the four Object.prototype names an engine coerces
+// through (`constructor`, `toString`, `valueOf`, `toJSON`) — the document
+// face checks the output and says so.
+const RANGE_KEYS = new Set([
+ "t",
+ "h",
+ "p",
+ "then",
+ "length",
+ "slice",
+ "constructor",
+ "toString",
+ "valueOf",
+ "toJSON"
+]);
+const NODE_KEYS = new Set(["t", "h", "p"]);
+/** Whether a string key read off a slot proxy is the range's own (passes
+ * through) rather than a property read of the fill's output. */
+function isRangeKey(key) {
+ const c = key.charCodeAt(0);
+ return c === 36 /* $ */ || (c >= 48 && c <= 57) /* index */ || RANGE_KEYS.has(key);
+}
+function slotProxy(range, occurrence, face, content, onData) {
+ return new Proxy(range, {
+ get(target, key, receiver) {
+ if (typeof key !== "string" || isRangeKey(key)) return Reflect.get(target, key, receiver);
+ // The first property read fixes the proxy's face as DATA (see
+ // repeatKey): a placed range never gets here.
+ if (onData) onData = void onData();
+ return slotValue(occurrence, key, content ? content[key] : undefined, face);
+ }
+ });
+}
+
+/**
+ * A slot arg's form at the serialization border: `toBorderForm`, after one
+ * check the border alone can make — the arg is, or carries, another slot's
+ * stand-in (`props.child({ parentId: parent.id })`, `parent` a slot;
+ * `{ nested: { x: row.done } }`, `[row.done]`). The server has no value
+ * there (it is the client's), so the record ships `undefined` at that
+ * position and dev says why; serializing the stand-in would hand the
+ * client an object where it expects the value (`{ k, v, f }` — and on the
+ * document face `v` is the t=0 value, which hydration then contradicts).
+ */
+function argBorderForm(value, key, occurrence) {
+ return toBorderForm(withoutStandIns(value, key, occurrence), true);
+}
+
+/**
+ * A slot arg with every stand-in in it replaced by `undefined` — the same
+ * rewrite as `toBorderForm` (copy-on-write, plain arrays and objects by
+ * their leaves, a cycle rewritten as a cycle; see rewriteTree): a
+ * container first (a WeakMap probe — a pending projection proxy's
+ * property reads throw not-ready), then the stand-in test on plain
+ * objects alone; anything exotic is the app's and is not read. Both faces
+ * take the same arg: the document face's t=0 fill reads what hydration
+ * will (see createDocumentSlotProps), the records carry it.
+ */
+function withoutStandIns(value, key, occurrence) {
+ return rewriteTree(
+ value,
+ (v, path) => {
+ if (isContainerTraced(v)) return v;
+ if (Object.getPrototypeOf(v) === Object.prototype && isSlotValue(v)) {
+ if ("_SOLID_DEV_") standInArgFinding(v, key, occurrence, path);
+ return undefined;
+ }
+ return DESCEND;
+ },
+ true
+ );
+}
+
+function standInArgFinding(sv, key, occurrence, path) {
+ if ("_SOLID_DEV_") {
+ // Once per (occurrence, arg, path) per render — and a stand-in shared
+ // between two paths is met once, at its first (`rewriteTree` answers
+ // the second from its record): the document face scrubs the fill's arg
+ // and the record's separately, and a live re-evaluation of the same
+ // getter is the same misuse.
+ const ctx = sharedConfig.context;
+ if (ctx) {
+ const id = `${occurrence}\u0000${key}${path}\u0000arg`;
+ const seen = ctx.slotFindings || (ctx.slotFindings = new Set());
+ if (seen.has(id)) return;
+ seen.add(id);
+ }
+ const where = path === "" ? `Arg \`${key}\`` : `Arg \`${key}${path}\``;
+ devCheck({
+ code: "ATTRIBUTE_SLOT_POSITION",
+ kind: "ssr",
+ severity: "warn",
+ message:
+ `[ATTRIBUTE_SLOT_POSITION] ${where} of \`${occurrence}\` is another slot's value ` +
+ `(\`${sv.k}\` of \`${sv[SLOT_VALUE]}\`). The server does not have it — the client owns ` +
+ `it — so it cannot be passed as data; the arg carries \`undefined\` there on both faces. ` +
+ `Pass the server's own value, or have the client fill read it from its own state.`,
+ data: {
+ reason: "arg",
+ occurrence,
+ key,
+ path: path === "" ? undefined : path,
+ from: sv[SLOT_VALUE],
+ fromKey: sv.k
+ }
+ });
+ }
+}
+
+/** Classify a document-face fill's return for property reads: a plain
+ * object is data (its properties are the t=0 values); content — an SSR
+ * node, a node list, a string, a function — is markup, and a read off it
+ * is a dev finding at the position that binds it. Nothing (`null`/
+ * `undefined`) reads as data with no values. */
+function slotFace(range, content) {
+ if (content == null) return SLOT_FACE_DATA;
+ if (typeof content !== "object" || Array.isArray(content)) return SLOT_FACE_MARKUP;
+ if (isServerContent(content)) {
+ // An SSR node is `{ t }` (plus `h`/`p`) and nothing else. An object
+ // with further keys is the fill's DATA that happened to use a node key
+ // — classified as data in every build (a `t` value is unreadable, the
+ // rest binds), and named below in dev.
+ let data = false;
+ for (const key in content) {
+ if (!NODE_KEYS.has(key)) {
+ data = true;
+ break;
+ }
+ }
+ if (!data) return SLOT_FACE_MARKUP;
+ }
+ if ("_SOLID_DEV_") {
+ for (const key of Object.keys(content)) {
+ if (isRangeKey(key)) {
+ devCheck({
+ code: "ATTRIBUTE_SLOT_POSITION",
+ kind: "ssr",
+ severity: "warn",
+ message:
+ `[ATTRIBUTE_SLOT_POSITION] The fill for \`${range.$occurrence}\` returned a key named \`${key}\`, ` +
+ `which is reserved (keys beginning with \`$\` or a digit, \`length\`, \`slice\`, the node keys \`t\`/\`h\`/\`p\`, ` +
+ `\`then\`, \`constructor\`, \`toString\`, \`valueOf\`, \`toJSON\`): the server reads it as the ` +
+ `slot's range, not as a value. Rename it.`,
+ data: { reason: "reserved-key", occurrence: range.$occurrence, key }
+ });
+ }
+ }
+ }
+ return SLOT_FACE_DATA;
}
// Occurrence ids embed user data (`$key`), and they land in contexts with
@@ -925,16 +1106,118 @@ function encodeOccurrenceKey(key) {
* adoption and every later stream.
*/
function occurrenceId(prop, raw, counts) {
- const k = raw.$key;
- // Numbers encode too: exponent forms ("1e+21") carry `+`.
- if (typeof k === "string" || typeof k === "number") {
- return `${prop}#${encodeOccurrenceKey(k)}`;
- }
+ const keyed = keyedId(prop, raw);
+ if (keyed !== undefined) return keyed;
const n = counts[prop] || 0;
counts[prop] = n + 1;
return `${prop}#${n}`;
}
+/** `prop#<$key>` for a call that names its occurrence; `undefined` otherwise. */
+function keyedId(prop, raw) {
+ const k = raw.$key;
+ // Numbers encode too: exponent forms ("1e+21") carry `+`.
+ return typeof k === "string" || typeof k === "number"
+ ? `${prop}#${encodeOccurrenceKey(k)}`
+ : undefined;
+}
+
+/**
+ * Structural identity of a call's args, for collapsing repeated un-keyed
+ * DATA calls (see repeatKey): a canonical string over plain values
+ * — primitives, and arrays / plain objects of them, keys sorted — or
+ * `undefined` when the args hold anything identity can't be read off by
+ * value: a function (a thunk, a handler), a promise or async iterable (the
+ * value tier), a class instance, a getter (compiled props — evaluating it
+ * here would double the read the record path owns), a cycle (no finite
+ * by-value form). `$key` is excluded: a keyed call is named, not compared.
+ */
+function structuralArgsKey(raw) {
+ let out = "";
+ let ancestors;
+ // Length-prefixed strings and keys keep the encoding injective.
+ const walk = (v, top) => {
+ if (v === null) out += "N";
+ else if (typeof v === "string") out += "s" + v.length + ":" + v;
+ else if (typeof v === "boolean") out += v ? "T" : "F";
+ else if (typeof v === "undefined") out += "U";
+ else if (typeof v === "number") out += "n" + v + ";";
+ else if (typeof v === "bigint") out += "b" + v + ";";
+ else if (typeof v !== "object") return false;
+ else {
+ const isArray = Array.isArray(v);
+ if (!isArray) {
+ const proto = Object.getPrototypeOf(v);
+ if (proto !== Object.prototype && proto !== null) return false;
+ }
+ if (ancestors === undefined) ancestors = new Set();
+ else if (ancestors.has(v)) return false;
+ ancestors.add(v);
+ try {
+ if (isArray) {
+ out += "[";
+ for (const item of v) if (!walk(item)) return false;
+ out += "]";
+ } else {
+ out += "{";
+ for (const k of Object.keys(v).sort()) {
+ if (top && k === "$key") continue;
+ const desc = Object.getOwnPropertyDescriptor(v, k);
+ if (desc.get || desc.set) return false;
+ out += "k" + k.length + ":" + k;
+ if (!walk(desc.value)) return false;
+ }
+ out += "}";
+ }
+ } finally {
+ ancestors.delete(v);
+ }
+ }
+ return true;
+ };
+ return walk(raw, true) ? out : undefined;
+}
+
+/**
+ * One call is one occurrence however many times the render evaluates it.
+ * The natural attribute-slot shape puts the call in a component prop —
+ * `
` — and + * compiled props are getters: every position the shared component binds + * re-evaluates the expression. Without this, each read would mint an + * occurrence, run the fill and emit a record (the double-data disease, once + * per position). Two names collapse a repeat onto the first call's proxy: + * + * - `$key`: the occurrence is named, so any repeat is the same occurrence + * whatever its face — the author said so. + * - structural args, for a call already known to be DATA: identical args + * give an identical fill output, so binding both sites' positions to one + * occurrence changes nothing on screen. Known-data only, because a placed + * range is not collapsible — two ` ` are two + * ranges — and on the stream face a proxy's face is fixed by its first + * use (property read → data; `t` read → placed). The getter shape reads + * at the call, so the second evaluation finds the first registered; a + * call that is neither read nor placed before an identical call stays a + * separate occurrence (duplicate record, correct output). The document + * face classifies the fill's return at the call and registers there. + * + * `$key` therefore names an ENTITY — client state inside the fill's scope + * follows it across responses — and is optional; without it identity is + * positional per prop across responses and structural within one. + * + * Both names share one per-render map (`repeats`): a keyed call's key is + * its occurrence id (`prop#<$key>`), an un-keyed call's is `prop\0 `, + * a zero-arg call's (document face, where the fill runs) is `prop\0` + * — disjoint alphabets. The caller registers a keyed proxy at the call and + * an un-keyed one when its face is known (first wins), and looks up before + * minting. `undefined`: this call can never be recognized as a repeat. + */ +function repeatKey(prop, raw) { + const keyed = keyedId(prop, raw); + if (keyed !== undefined) return keyed; + const structural = structuralArgsKey(raw); + return structural === undefined ? undefined : prop + "\0" + structural; +} + /** An async value in the DR-2 value-tier sense: passed whole, rides the data * channel, and the consumer's READ settles. */ function isAsyncValue(v) { @@ -1018,6 +1301,8 @@ export function createDocumentSlotProps( export function createDocumentSlotProps(clientProps, frameId) { const counts = Object.create(null); const getters = new Map(); + // Repeated calls are one occurrence within a render (see repeatKey). + const repeats = new Map(); // `$slot`-tagged like the stream face's slotRange: the engine resolves a // slot-tagged value MINT-SUPPRESSED, so fill content — client-owned DOM // the adopting frame claims — never grows live-hole markers or bindings. @@ -1026,6 +1311,11 @@ export function createDocumentSlotProps(clientProps, frameId) { // story: arg re-emissions update the adopted occurrence's props. One // known coarsening: a region (server JSX arg) placed by the fill resolves // inside this suppressed span, so its interior holes keep the t=0 latch. + // + // The return is the slot PROXY over this range (see slotProxy): placed, + // it is the range; read, its properties are the fill's t=0 values — this + // being the document face, where the fill ran. A fill that returned + // content classifies as markup and reads off it are dev findings. const range = (occurrence, content) => { const r = [ { t: `` }, @@ -1033,7 +1323,10 @@ export function createDocumentSlotProps(clientProps, frameId) { { t: `` } ]; r.$slot = true; - return r; + r.$occurrence = occurrence; + const face = slotFace(r, content); + r.$face = face; + return slotProxy(r, occurrence, face, face === SLOT_FACE_DATA ? content : undefined); }; // Client content renders under a per-occurrence hydration-key OWNER // scope, so the adopting client re-renders each slot under the SAME @@ -1078,20 +1371,34 @@ export function createDocumentSlotProps(clientProps, frameId) { // Direct-insert position: the client's content renders inline, // wrapped in the range the adopting frame will claim. if (callArgs.length === 0 || callArgs[0] === undefined) { + // A zero-arg call is the occurrence named by the prop, so a + // repeat of one known to be DATA collapses onto the first proxy + // like the args path below (see repeatKey — ` ` re-evaluates the getter at every + // position the component binds, and each evaluation ran the + // fill). A placed range is one range per placement. + const rk = prop + "\0"; + const repeat = repeats.get(rk); + if (repeat) return repeat; // Direct-insert positions are key-scoped like render props — // there is no natural id parity across the boundary, so BOTH // sides evaluate inside the occurrence scope. The prop is read // INSIDE scoped(): compiled component props are getters, so the // client's JSX evaluates lazily at access under the same keys — // plain JSX, no thunk convention. - return suppressedFill(() => + const out = suppressedFill(() => scoped(prop, () => { const value = clientProps[prop]; return range(prop, typeof value === "function" ? value() : value); }) ); + if (out.$face === SLOT_FACE_DATA) repeats.set(rk, out); + return out; } const raw = callArgs[0]; + const rk = repeatKey(prop, raw); + const repeat = rk !== undefined && repeats.get(rk); + if (repeat) return repeat; const occurrence = occurrenceId(prop, raw, counts); const slot = clientProps[prop]; if (typeof slot !== "function") return range(occurrence, undefined); @@ -1240,7 +1547,11 @@ export function createDocumentSlotProps(clientProps, frameId) { configurable: true }); } else { - resolved[key] = value; + // What hydration will read: a stand-in anywhere in the arg is + // `undefined` in the record (argBorderForm), so the t=0 fill + // takes the same value — the one-record shape holds for the + // args the fill saw, not only the ones it shipped. + resolved[key] = vals[key] = withoutStandIns(value, key, occurrence); } } const out = suppressedFill(() => @@ -1273,7 +1584,7 @@ export function createDocumentSlotProps(clientProps, frameId) { if (!isContainerTraced(value) && isServerContent(value)) continue; // Containers (at any depth) ride the record as trace envelopes; // everything else passes through by reference. - args[key] = toBorderForm(value, true); + args[key] = argBorderForm(value, key, occurrence); } // A CLONE serializes; `args` stays canonical for the ledger // below — re-emissions mutate it and clone again, so the @@ -1315,13 +1626,18 @@ export function createDocumentSlotProps(clientProps, frameId) { evals[key], states[key], value => { - args[key] = toBorderForm(value, true); + args[key] = argBorderForm(value, key, occurrence); liveArgs.slot(frameId, occurrence, { ...args }); } ); } } } + // The fill ran and its return is classified: a keyed call + // registers for repeats whatever its face, an un-keyed one only + // as data (two identical placements are two ranges). + if (rk !== undefined && (rk === occurrence || out.$face === SLOT_FACE_DATA)) + repeats.has(rk) || repeats.set(rk, out); return out; }; // A slot getter placed directly as a child (`{props.children}`) is a @@ -1329,10 +1645,6 @@ export function createDocumentSlotProps(clientProps, frameId) { // same way it does on the stream face (the impurity gates would // latch it anyway — this makes it exact rather than incidental). fn.$lhSkip = true; - // The claim brand (Stage 6): a stub placed in a ref/on* position - // instead of being called claims by prop name — `ssrClaim` reads - // this to mint `_bnd`. - fn[CLAIM_PROP] = prop; getters.set(prop, fn); } return fn; @@ -1379,15 +1691,17 @@ const FRAME_ELEMENT_CLOSE = ``; * ships last values, then the channel closes (an open stream would hold the * response forever). * - * CONTEXT GEOMETRY: components render under per-component context CLONES, - * so the ctx a server component arms under is usually not the root object - * the renderer's flush loop reads. Everything read DOWNWARD (`liveHoles`, - * `commit` — consumed by the subtree under the arm point) rides the clone: - * descendants spread-copy it. Everything read at the ROOT (the end latch, - * and the once-per-document arming dedupe — a second component elsewhere - * arms under a sibling clone that never saw the first) rides `ctx.live`, - * the shared slot the root context creates and every clone carries by - * reference. + * CONTEXT GEOMETRY: the ctx a server component arms under is not always + * the root object the renderer's flush loop reads — it may be a DERIVED + * context (`Object.create(root)`: a Loading boundary's buffered context, + * or the claims-arming context `frameTransformDirectResult` renders a + * server-owned frame under). Everything read DOWNWARD (`liveHoles`, + * `commit` — consumed by the subtree under the arm point) is written on + * that ctx and inherited by whatever derives from it below. Everything + * read at the ROOT (the end latch, and the once-per-document arming dedupe + * — a second component elsewhere arms under a sibling derived ctx that + * never saw the first) rides `ctx.live`, the shared slot the root context + * creates and every derived context inherits by reference. */ function armDocumentLiveHoles(ctx) { if (!ctx || ctx.liveHoles !== undefined) return; @@ -1543,21 +1857,33 @@ export function frameTransformDirectResult(value, { id, args }) { // the client's content keeps full app context while the component's // own render is context-isolated. serverOwned(() => { - armDocumentLiveHoles(sharedConfig.context); - // Behavior claims (Stage 6): arm the compiled guard for this subtree - // (descendant context clones spread-copy it). Minting is additionally - // scope-gated inside ssrClaim, so client fill content — which - // re-enters the zone owner outside the component barrier — neither - // claims nor warns. - sharedConfig.context.claims = CLAIMS_DOCUMENT; - const slotProps = createDocumentSlotProps(props, id); - // A `live` answer (the declaration's in-process brand lands on this - // wrapper after it is made, before it renders) marks the scope live: - // every async source inside takes its first value and closes — the - // document completes, and the standing render is the client's - // connection after hydration (RFC 11 §9.5, Server face 3). Read at - // render, not at wrap: the brand arrives from `live`, outside. - return serverComponentScope(() => component(slotProps), !!wrapped[LIVE_SOURCE]); + const page = sharedConfig.context; + armDocumentLiveHoles(page); + // Handler positions: arm the compiled `ssrClaim` guard — and the + // spread walk's slot probes — for this subtree, on a render context + // DERIVED from the page's (prototype: every shared field and method + // reads through, as a Loading boundary's buffered context does). The + // page's own context never carries `claims`, so the document's + // elements after the component keep the pre-slot walk; a late hole + // minted inside re-emits under its mint-time context — this one — + // and stays armed. Marking is additionally scope-gated inside + // ssrClaim, so client fill content — which re-enters the zone owner + // outside the component barrier — neither marks nor warns. + const ctx = Object.create(page); + ctx.claims = CLAIMS_DOCUMENT; + sharedConfig.context = ctx; + try { + const slotProps = createDocumentSlotProps(props, id); + // A `live` answer (the declaration's in-process brand lands on this + // wrapper after it is made, before it renders) marks the scope live: + // every async source inside takes its first value and closes — the + // document completes, and the standing render is the client's + // connection after hydration (RFC 11 §9.5, Server face 3). Read at + // render, not at wrap: the brand arrives from `live`, outside. + return serverComponentScope(() => component(slotProps), !!wrapped[LIVE_SOURCE]); + } finally { + sharedConfig.context = page; + } }), { t: FRAME_ELEMENT_CLOSE } ]; @@ -1791,6 +2117,8 @@ export function createSlotProps( export function createSlotProps(sink, frame) { const counts = Object.create(null); const getters = new Map(); + // Repeated calls are one occurrence within a render (see repeatKey). + const repeats = new Map(); return new Proxy(Object.create(null), { // Every key virtually exists — a prop is a *position* the client may // fill, and the server cannot know which ones the client supplied. This @@ -1812,14 +2140,19 @@ export function createSlotProps(sink, frame) { if (!fn) { fn = (...callArgs) => { if (callArgs.length === 0 || callArgs[0] === undefined) { - return slotRange(prop); + return slotProxy(slotRange(prop), prop, SLOT_FACE_STREAM, undefined); } + const rk = repeatKey(prop, callArgs[0]); + const repeat = rk !== undefined && repeats.get(rk); + if (repeat) return repeat; // Slot records are emit-once: occurrence identity is positional // (`counts`), so a live-hole re-evaluation reaching a called slot // would mint new occurrences and re-serialize args — the double- // data disease. First render stamps the engine so the enclosing // hole latches instead of binding; a sweep that gets here anyway - // (the escalated-first-render case) aborts and closes the binding. + // (the escalated-first-render case) flags the engine (`gateHit`) + // and hands back an inert placeholder — the engine discards that + // sweep's value and closes the binding. const live = sharedConfig.context && sharedConfig.context.liveHoles; if (live) { if (live.sweeping) { @@ -1956,7 +2289,7 @@ export function createSlotProps(sink, frame) { const ref = `arg:${occurrence}:${key}`; // Containers (at any depth) swap for their trace envelopes // before the value meets seroval — see toBorderForm. - ctx.serialize(ref, toBorderForm(value, true)); + ctx.serialize(ref, argBorderForm(value, key, occurrence)); args[key] = { $ref: ref }; if (evaluate && !state) state = { settled: true, last: value }; } @@ -1986,21 +2319,30 @@ export function createSlotProps(sink, frame) { } else { const ref = `arg:${occurrence}:${key}@${sink.nextArgRef(ledgerKey)}`; sink.mintRef(ref); - ctx.serialize(ref, toBorderForm(value, true)); + ctx.serialize(ref, argBorderForm(value, key, occurrence)); args[key] = { $ref: ref }; } sink.slot(occurrence, { ...args }); }); } - return slotRange(occurrence); + // A keyed call registers for repeats at the call; an un-keyed one + // at its first property read — the moment its face is known to be + // data (the proxy calls `onData` once, then never again). + const keyed = rk === occurrence; + const out = slotProxy( + slotRange(occurrence), + occurrence, + SLOT_FACE_STREAM, + undefined, + rk === undefined || keyed ? undefined : () => repeats.has(rk) || repeats.set(rk, out) + ); + if (keyed) repeats.set(rk, out); + return out; }; // A slot getter placed directly as a child (`{props.children}`) is a // function-shaped hole; the tag opts it out of live-hole marking the // same way `$slot` opts out its returned range. fn.$lhSkip = true; - // The claim brand (Stage 6): see createDocumentSlotProps — same - // contract on the stream face. - fn[CLAIM_PROP] = prop; getters.set(prop, fn); } return fn; diff --git a/packages/web/frames/src/frame-transport.ts b/packages/web/frames/src/frame-transport.ts index e7e409550..4f6bcf717 100644 --- a/packages/web/frames/src/frame-transport.ts +++ b/packages/web/frames/src/frame-transport.ts @@ -752,7 +752,7 @@ export function createServerComponentHandler({ host, component, onStream, interc } const version = bump(address); if (onStream) onStream(address, version, response); - applyFrameResponse(response, host, { as: address, version }).catch(err => + const applied = applyFrameResponse(response, host, { as: address, version }).catch(err => host.apply({ type: "error", id: address, @@ -760,7 +760,19 @@ export function createServerComponentHandler({ host, component, onStream, interc error: { message: String(err && err.message) } }) ); - return binding; + // A refetch of a call a boundary is SHOWING settles when its response + // has applied, not at the header. The header is not an answer (#2977 + // said it for address switches; this is the same address): until the + // new content lands the boundary still shows the previous render, so + // a reader that drove the refetch — `isPending(source)`, a `refresh` + // inside an action's transaction holding an optimistic write over the + // old slot args (§9.2.2) — must keep reading pending or it tears. The + // hold is the whole body, as a single-flight mutation's already is. + // A cold mount or a switch to an address nothing shows keeps + // header-time resolution: the mount needs the binding to place the + // boundary and the shell gate is its hold — settling those late would + // block progressive streaming behind a completed body. + return host.get(address) ? applied.then(() => binding) : binding; }, /** diff --git a/packages/web/frames/src/server.ts b/packages/web/frames/src/server.ts index f8dae0700..1a9036f39 100644 --- a/packages/web/frames/src/server.ts +++ b/packages/web/frames/src/server.ts @@ -51,6 +51,33 @@ setAsyncIterableSharer(shareAsyncIterable); */ export type Slot = (props: P & { $key?: string | number }) => SolidElement; +/** + * An attribute slot (principles §9.2.3): the client renders an object instead of + * markup, and the server template consumes it by reading properties at + * positions — `const row = props.row({ id, completed });` then + * `
`. One call is one data context: any element + * in the template may read from it, and the client owns exactly the values + * the template read. Keys are the client's names; the position decides what + * a property IS (attribute, class name, style property, handler, ref). + * + * `P` is the args the server passes (reactive props to the fill, as for + * `Slot`); `J` is the object the fill returns — the same type a shared + * component takes as a prop when the client renders it directly, so one + * `TodoRow` serves both sides. `$key` is occurrence identity, as for `Slot`, + * and optional: within a render, repeated calls with structurally equal + * args are one occurrence (a call in a component prop is re-evaluated per + * position the component binds), so the natural spelling needs no key; + * `$key` is for state inside the fill's scope that must follow the entity + * across responses. A slot with no args (`P` empty) is called bare — + * `const filters = props.filters();` — and is one occurrence named by the + * prop. + * @experimental + */ +export type AttributeSlot> = {} extends P + ? (props?: P & { $key?: string | number }) => J + : (props: P & { $key?: string | number }) => J; + /** * Types an async value crossing the slot border (DR-2, value tier). What you * pass is what ships — the promise / async iterable itself rides the data diff --git a/packages/web/frames/src/tree-rewrite.ts b/packages/web/frames/src/tree-rewrite.ts new file mode 100644 index 000000000..92cc45100 --- /dev/null +++ b/packages/web/frames/src/tree-rewrite.ts @@ -0,0 +1,141 @@ +/** + * Copy-on-write rewrite of a value tree, for the serialization-border walks + * (`toBorderForm` — every document-face serialization and every slot-arg + * record — and the slot-arg stand-in scrub). `visit(value, path)` is asked + * at every OBJECT node first (primitives pass through unasked: no visitor + * replaces one, and leaves are most of a payload) and answers with the + * node's replacement, or `DESCEND` to walk the node's leaves — which + * happens for a plain array or plain object only; anything else (a class + * instance, a `Map`, a proxy) is the app's and passes through untouched. + * + * Author values are never mutated. The walk is plain recursion, copy-on- + * write: an untouched subtree passes by reference, a changed one is copied + * along the path to the root. That is the whole cost for acyclic data of + * ordinary depth (measured below what `next`'s direct recursion paid, the + * primitive short-circuit buying more than the visitor call costs). + * + * A back-reference to an ancestor has no copy-on-write answer (the copy's + * back-reference would point at the original, unrewritten), and tracking + * ancestors at every node would tax every walk. So ancestors are tracked + * only from a depth ordinary payloads never reach (`TRACK`): a cycle is + * caught within one cycle-length past it, the pass aborts and the tree is + * rewritten again as a memoized clone — one copy per container, a back- + * reference resolving to the ancestor's copy. Only cyclic (or unusually + * deep) values pay. Replacements are recorded as they are produced (a trace + * envelope, a multicast seat, a scrubbed stand-in): a node seen again on + * the first pass — a cycle revisits its nodes on every level down to the + * catch — and every node of the clone pass answer from the record, so a + * visitor's side effects run once per node whichever way the walk went. + * Walks that replace nothing never pay the lookup. A value reachable at two + * paths is one node: its replacement is shared (one seat for one iterable — + * the identity the input had, which the serializer writes once and the + * client materializes once), and a shared subtree with nothing to replace + * is visited at each occurrence on the first pass and once on the clone + * pass. `path` is built (`.key`, `[i]`) only when `withPath`. + */ +export const DESCEND: unique symbol = Symbol("descend"); + +const CYCLE = {}; + +/** The depth from which the first pass tracks its ancestors. */ +const TRACK = 16; + +type Visit = (value: object, path: string | undefined) => any; + +type State = { memo: Map
}> +| undefined }; + +export function rewriteTree(value: any, visit: Visit, withPath: boolean): any { + if (value === null || typeof value !== "object") return value; + const path = withPath ? "" : undefined; + const state: State = { memo: undefined, ancestors: undefined }; + try { + return cow(value, visit, path, 0, state); + } catch (err) { + if (err !== CYCLE) throw err; + } + return clone(value, visit, path, state.memo || (state.memo = new Map())); +} + +function shape(value: any): 1 | 2 | 0 { + return Array.isArray(value) ? 1 : Object.getPrototypeOf(value) === Object.prototype ? 2 : 0; +} + +// `value` is an object (the callers test). +function cow(value: any, visit: Visit, path: string | undefined, depth: number, state: State) { + const memo = state.memo; + if (memo !== undefined && memo.has(value)) return memo.get(value); + const r = visit(value, path); + if (r !== DESCEND) { + if (r !== value) (memo || (state.memo = new Map())).set(value, r); + return r; + } + const s = shape(value); + if (s === 0) return value; + // Deep enough to suspect a cycle: this container joins the ancestors for + // the walk of its leaves. No try/finally — an abort discards the set, a + // visitor's error propagates past it. + let ancestors; + if (depth >= TRACK) { + ancestors = state.ancestors || (state.ancestors = new Set()); + if (ancestors.has(value)) throw CYCLE; + ancestors.add(value); + } + let out = value; + if (s === 1) { + for (let i = 0; i < value.length; i++) { + const c = value[i]; + if (c === null || typeof c !== "object") continue; + const next = cow( + c, + visit, + path === undefined ? undefined : `${path}[${i}]`, + depth + 1, + state + ); + if (next !== c) { + if (out === value) out = value.slice(); + out[i] = next; + } + } + } else { + for (const k of Object.keys(value)) { + const c = value[k]; + if (c === null || typeof c !== "object") continue; + const next = cow(c, visit, path === undefined ? undefined : `${path}.${k}`, depth + 1, state); + if (next !== c) { + if (out === value) out = { ...value }; + out[k] = next; + } + } + } + if (ancestors !== undefined) ancestors.delete(value); + return out; +} + +// `value` is an object (the callers test). +function clone(value: any, visit: Visit, path: string | undefined, memo: Map ; children?: FunctionMaybe ; $ServerOnly?: boolean | undefined; + /** + * Entity identity for server markup: the frame morph matches keyed + * elements across responses by it, so client state attached to the + * element (an attribute slot's bound positions, focus) follows the entity + * through reorders and refetches. SSR compiles it to the `_key` + * attribute; a DOM compile strips it. On a component, `$key` is slot + * occurrence identity across responses (optional; a repeated call is + * one occurrence per render with or without it). + */ + $key?: string | number | undefined; } interface ExplicitProperties {} type PropAttributes = { diff --git a/packages/web/jsx/jsx.d.ts b/packages/web/jsx/jsx.d.ts index b176c3a24..9cdceed73 100644 --- a/packages/web/jsx/jsx.d.ts +++ b/packages/web/jsx/jsx.d.ts @@ -250,6 +250,16 @@ export namespace JSX { ref?: Ref ; children?: Element | undefined; $ServerOnly?: boolean | undefined; + /** + * Entity identity for server markup: the frame morph matches keyed + * elements across responses by it, so client state attached to the + * element (an attribute slot's bound positions, focus) follows the entity + * through reorders and refetches. SSR compiles it to the `_key` + * attribute; a DOM compile strips it. On a component, `$key` is slot + * occurrence identity across responses (optional; a repeated call is + * one occurrence per render with or without it). + */ + $key?: string | number | undefined; } interface ExplicitProperties {} type PropAttributes = { diff --git a/packages/web/package.json b/packages/web/package.json index e94caac26..21425d165 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -41,7 +41,8 @@ "frames/package.json", "performance-tracks/dist", "performance-tracks/types", - "performance-tracks/package.json" + "performance-tracks/package.json", + "skills" ], "exports": { ".": { diff --git a/packages/web/skills/server-components/SKILL.md b/packages/web/skills/server-components/SKILL.md new file mode 100644 index 000000000..81f469550 --- /dev/null +++ b/packages/web/skills/server-components/SKILL.md @@ -0,0 +1,206 @@ +# Writing Solid server components with slots + +A Solid server component is a `"use server"` function that returns a +template; the browser receives its markup and never its code. Anything the +client contributes goes through a **slot** on the component's props. This +guide is the set of rules an author — a person or an agent — needs to write +one correctly the first time. The design record is +`documentation/server-components/server-components-principles.md` §9.2.3; +this file is the operative subset. + +## Where things go + +> **An element lives where the data that creates it lives.** + +- Exists because of **server data** (a todo row, a nav link, a search + form the server renders)? It is **server markup**. Client behavior or a + client-driven value on it is an **attribute slot** — bind, never wrap. + Do not wrap a server-rendered element in a client component to give it a + handler or a class. +- Exists because of **client state alone** (an optimistic add, a modal, a + drag ghost, an editor open over a field)? It is a **client component** + placed through a **markup slot**. + +When the client confirms an optimistic entity and the server renders it, the +row _becomes_ server markup; `$key` on the element reconciles the two. + +## The two kinds of slot + +```tsx +import type { AttributeSlot, Slot } from "@solidjs/web/frames"; + +interface TodosProps { + pending: Slot; // markup: the client returns JSX + row: AttributeSlot<{ id: string; completed: boolean }, RowBehavior>; // attributes: the client returns an object + filters: AttributeSlot<{}, FilterBehavior>; // no args: called bare +} +``` + +A **markup slot** is placed as an element: ` `. The client +owns those nodes. + +An **attribute slot** is _called_ once per data context and its properties +are _bound_ at positions of the server's own template: + +```tsx +export async function todoList() { + "use server"; + const todos = await db.list(); + return (props: TodosProps) => { + const filters = props.filters(); + return ( + <> + -
+ {todos.map(t => (
+
+ ))} + + ({ all: filter() === "all", … })} pending={() => {…} } /> +``` + +## The one rule for attribute slots + +> **A slot property is a JSX attribute value, whole, and nothing else.** + +Legal positions: an attribute (`hidden={row.removed}`, `checked={row.done}`, +`title={row.error}`), a class name inside object form +(`class={{ completed: row.done }}`), the whole `class`/`style` +(`class={row.rowClass}`), a style property (`style={{ opacity: row.fade }}`), +an event (`onInput={row.onToggle}`), a ref (`ref={row.ref}`) — on an element +with a spread too (`` — the last +source that has the key wins, `undefined` included, as the client's +spread reads it). Not a `prop:*` +property, not a text child, not inside another slot call's args (nested in +plain objects and arrays included). Reserved keys the fill must not use: +keys beginning with `$` or a digit, `length`, `slice`, `t`/`h`/`p`, `then`, +`constructor`/`toString`/`valueOf`/`toJSON`; anything else (`filter`, `map` +included) is a plain property. + +The server **does not have the value** — on the stream face a property read +is a stand-in with no value, on the document face only the initial one — so +nothing can be computed from it on the server. Every one of these is wrong: + +| Wrong | Why | Write instead | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| ``class={`todo ${row.done}`}`` | stringified: not the whole value | `class={{ todo: true, completed: row.done }}` or return `rowClass` from the fill | +| `row.count > 3 ? "a" : "b"` | comparison on a stand-in | decide in the fill; return the decided value | +| `if (row.error) …`, `row.error && `, `` | 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 | +| `{row.count}` | text is not a bindable position yet | a markup slot for the text | +| `format(row.title)` (a server helper) | the helper receives a stand-in | do the formatting in the fill | +| ` - ` | spread: the template must show what the client owns | name each position | +| `onClick={() => …}` on a server element | a server function can never run in the browser | bind a slot property or a form `action` | + +Every case except truthiness is a dev finding (`ATTRIBUTE_SLOT_POSITION`) +and renders **nothing on either face**, so it shows on the first render. +Truthiness has no runtime hook: if a retry button appears on every row, this +is why. + +## Writing the fill + +- **Values as getters, handlers as plain closures** when a shared client + component also consumes the object (the usual case): + + ```tsx + const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({ + get rowClass() { + return { todo: true, completed: done(p.id, p.completed), pending: !!intent.byId[p.id] }; + }, + get done() { + return done(p.id, p.completed); + }, + get removed() { + return removed(p.id); + }, + onToggle: e => actions.toggle(p.id, e.currentTarget.checked), + onRemove: () => actions.remove(p.id) + }); + ``` + + A client `
` reads `props.row.onToggle` once, + untracked, in its body; a plain-value fill would do its reactive reads + there and never update (`STRICT_READ_UNTRACKED` names it). Getters move + each read to the position that binds it. Plain values are fine when only + the server template reads the object. + +- **Name it like a props interface**, because it is one (a shared component + takes it as a prop). Handlers are `on` + intent — `onToggle`, `onRemove`, + `onCopy`, `onClearCompleted`; the position names the DOM event, the key + names the meaning, as a component's `onSelect` does. Values are nouns or + adjectives (`done`, `rowClass`, `error`, `busy`); a ref is `ref`. The + runtime reads nothing into the prefix — the position decides what a + property is — but a reader can tell a handler from a value without + opening the type. +- The fill runs once per occurrence (one call); each bound position tracks + its own reads; handlers dispatch to the fill's _current_ handler; a ref + fires once per element. +- **`$key` is optional.** A call repeated within a render (a component + prop re-evaluates it per position) is one occurrence either way. Add + `$key: t.id` when the fill holds its own state (an edit draft, a signal + created inside) that must follow the entity across refetches and + reorders. Values never depend on it. +- Reserved keys in the returned object: anything beginning with `$`, the + node keys `t` `h` `p` `then`, and `Object`/`Array` prototype member names + (`length`, `map`, …). + +## Shared components + +One component can render on both sides: on the server its `row` prop is +the attribute slot's return, on the client it is the fill's result. It +cannot tell and need not. Put `$key={props.id}` on the element it renders +(morph identity) — the slot call's own `$key` is a different key for a +different job. Do not read `document`/`window` during render; that is the +ordinary isomorphic rule. + +## Compiling + +Server components need the SSR compile with the `serverComponents` compiler +option. With `@solidjs/vite-plugin`, `solid({ ssr: true, serverFunctions: +{ components: true } })` is the turnkey setup (the examples under +`examples/todos-server`, `examples/notes`, `examples/chat`); a hand-rolled +build passes `serverComponents: true` to `@solidjs/compiler` or +`@solidjs/babel-plugin` for the SSR side. Without it a dynamic +`class`/`style` compiles inside the template's quotes, where a slot value +cannot be marked — the `inline` finding below. + +## Diagnostics + +`ATTRIBUTE_SLOT_POSITION` (`data.reason`): + +| reason | severity | what happened | fix | +| -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `spread` | error (throws) | a slot's return was spread onto an element | name each position | +| `stringified` | warn | template literal / concatenation | whole value at one position | +| `coerced` | warn | comparison, arithmetic, `==` | decide in the fill | +| `text` | warn | placed as a text child | markup slot | +| `inline` | warn | reached `class`/`style` inside template quotes | compile with `serverComponents: true` | +| `markup` | warn | the fill returned JSX but the template read a property | return an object, or place the slot | +| `server-local` | warn | a server function at `on*`/`ref` | bind a slot property | +| `reserved-key` | warn | the fill used a reserved key | rename it | +| `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 | +| `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 | +| `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 | +| `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 | + +Every reason but `fill-shape` and `orphan` comes from the server render. +`orphan` is the one failure this model cannot otherwise show you: the +element is inert — a handler that never fires, a class that never updates — +with no error. + +`STRICT_READ_UNTRACKED` inside a fill: use getters (above). diff --git a/packages/web/src/client.ts b/packages/web/src/client.ts index bcbbf6340..a4717d21c 100644 --- a/packages/web/src/client.ts +++ b/packages/web/src/client.ts @@ -2619,18 +2619,7 @@ function eventHandler(e, container, state) { value }); const handleNode = () => { - let handler = node[key]; - // Server-claimed handler (`_bnd` marker, Stage 6 behavior claims): - // resolved at dispatch through the frame runtime's registered-symbol - // seam — latest-props by construction, importless in both directions. - // The read lives entirely inside this walk (no module-level state): - // client.js contributes ZERO top-level bytes to tree-shaken subsets, - // and the seam stays live for markers adopted before the frame runtime - // loads (the document face). Only pays when no compiled handler exists. - if (handler === undefined && node.hasAttribute && node.hasAttribute("_bnd")) { - const seam = globalThis[Symbol.for("solid.bnd")]; - if (seam) handler = seam.resolve(node, e.type); - } + const handler = node[key]; if (handler && !node.disabled) { const data = node[`${key}Data`]; data !== undefined diff --git a/packages/web/src/index.ts b/packages/web/src/index.ts index a5eb5d587..6ce01896e 100644 --- a/packages/web/src/index.ts +++ b/packages/web/src/index.ts @@ -481,7 +481,17 @@ export function dynamic ( // at this seam. Initialize from the LATEST resolved address: the // kept binding's own `.address` is the first resolution's and // goes stale the moment a later call is kept-delivered. - const [address, setAddress] = createSignal((deliveredAddress ??= binding.address)); + // `ownedWrite`: a delivery is a write from wherever the + // resolution lands — a promise microtask for an async source, + // but INSIDE the factory's compute when the source is a memo that + // already settled the call (the multi-flight `refresh(todos)` + // shape, and the hydrated document's first refetch), and inside + // the equals gate for a pump's yield. None of those read the + // address back, so the owned-scope write guard has nothing to + // protect here. + const [address, setAddress] = createSignal((deliveredAddress ??= binding.address), { + ownedWrite: true + }); sites.add(setAddress); onCleanup(() => sites.delete(setAddress)); return untrack(() => (binding.component as any)(props, address)); diff --git a/packages/web/src/server.ts b/packages/web/src/server.ts index 1aa3a40c7..334609e74 100644 --- a/packages/web/src/server.ts +++ b/packages/web/src/server.ts @@ -339,6 +339,14 @@ export { createComponent, effect, memo, untrack, mergeProps, scope, getOwner }; // the claims-gate guard (`sharedConfig.context.claims ? ssrClaim(...) : ""`) // needs the shared render context at template-evaluation time. export { sharedConfig }; +// Module-local alias for the per-element hot paths (`ssrElement`'s walk): +// an ESM module runner that keeps imports live exposes each imported +// binding through a getter, so every `sharedConfig.x` at a call site is a +// getter call — the SSR bench lane runs the source that way and showed the +// walk's one context read per element as a ~5–10% regression that the +// bundled output (a plain binding) never had. Reading through a module +// constant makes it a property load in both. +const renderConfig = sharedConfig; export { DOMWithState, @@ -616,6 +624,14 @@ function applyAssetTracking(context, tracking, manifest, noScripts) { }); context.registerModule = tracking.registerModule; context.getBoundaryModules = tracking.getBoundaryModules; + // The per-request resolution cache lazy() reads (`resolveLazyAssets`), + // created on the ROOT context: render contexts derive from it by + // prototype (a Loading boundary's buffered context, a server-owned + // frame's claims context), and a cache the first lazy() on the page + // created lazily on a derived context would be that subtree's alone — + // the next lazy() outside it would start a second Map and re-ask the + // resolver for every module the first already resolved. + context._lazyAssets = new Map(); // A manifest can be the static object produced by a build (sync lookups, // entry enumeration) or a resolver — the primitive a dev server implements // against its live module graph: `{ resolve, resolveSync? }`, where @@ -3562,9 +3578,9 @@ export function createLiveHoles(sink, scoped) { // face never noticed — its whole response is one render, so the global // still points at the armed context when async sweeps fire. The document // face replaces it as the document renders past the component, so swept - // re-emissions there lost every context-derived byte: `_bnd` claim - // markers vanished from late holes (a copy button that compiled, streamed - // its markup, and never armed). + // re-emissions there lost every context-derived byte: handler-position + // slot markers (`_s:on:click`) vanished from late holes (a copy button + // that compiled, streamed its markup, and never bound). const swept = (owner, ctx, fn) => { const prev = sharedConfig.context; sharedConfig.context = ctx; @@ -4190,12 +4206,18 @@ export function ssrClassName(value) { if (typeof value === "number") return "" + value; if (!value) return ""; if (typeof value === "string") return escape(value, true); + // An attribute-slot value here (whole, or as a class-name's condition) landed + // inside `class="…"` quotes, where its position marker cannot be emitted + // (see ssrElementAttribute): the element was compiled without the + // `serverComponents` option. Say so; nothing renders (either face). + if (isSlotValue(value)) return slotValueInline("class", value) ?? ""; value = classListToObject(value); let classKeys = Object.keys(value), result = ""; for (let i = 0, len = classKeys.length; i < len; i++) { - const key = classKeys[i], - classValue = !!value[key]; + const key = classKeys[i]; + let classValue = value[key]; + if (isSlotValue(classValue)) classValue = slotValueInline("class", classValue); if (!key || key === "undefined" || !classValue) continue; result && (result += " "); // Object keys land inside class="..." so they must be attribute-escaped. @@ -4208,6 +4230,7 @@ export function ssrStyle(value: string | { [k: string]: string }): string; export function ssrStyle(value) { if (!value) return ""; if (typeof value === "string") return escape(value, true); + if (isSlotValue(value)) return slotValueInline("style", value) ?? ""; let result = ""; const k = Object.keys(value); @@ -4215,7 +4238,8 @@ export function ssrStyle(value) { // Object keys land inside style="..." so they must be attribute-escaped // to prevent breaking out via `"`. const s = escape(k[i], true); - const v = value[k[i]]; + let v = value[k[i]]; + if (isSlotValue(v)) v = slotValueInline("style", v); if (v != undefined) { const r = escape(v, true); if (r != undefined && r !== "undefined") { @@ -4234,6 +4258,7 @@ export function ssrStyleProperty(name, value) { // `style={{ [k]: v }}` the compiler wraps the key with `_$escape(k, true)` // before concatenating the `:` suffix. Either way `name` is safe to splice // into style="..." without further escaping. + if (isSlotValue(value)) value = slotValueInline("style", value); return value != null ? name + value : ""; } export function ssrElement( @@ -4242,10 +4267,11 @@ export function ssrElement( children: any, needsId: boolean, skip?: (key: string) => boolean, - attrs?: string | (() => string) + attrs?: string | (() => string), + claims?: () => Record - `) is the retired + // 09-27 shape (principles §9.2.3): the client would decide what it owns + // and the template could not show it. Its range tag (`$slot`) is how it + // surfaces among the sources; name the positions instead. The tag is + // probed where the sources are already being classified, and a tagged + // source leaves the plain path with the other non-literal kinds — the + // collecting pass (`collectSpreadSources`) replaces it. This function is + // the SSR spread's hot path: what is not the plain walk lives in helpers + // so the walk itself stays small enough to optimize as one unit + // (spread-static-tail bench), and every slot probe on it — the `$slot` + // tag per source, the object test per attribute — sits behind `slots`: + // a stand-in is only ever met inside a server component's render, where + // the frame renderers arm `context.claims` (the compiled `ssrClaim` + // guard's value), so a render with no server components walks exactly + // as it did before attribute slots existed. + const ctx = renderConfig.context; + const slots = ctx !== undefined && ctx.claims !== undefined; if (Array.isArray(props)) { - let i = 0; - for (; i < props.length; i++) { - const s = props[i]; - if (s == null || typeof s === "function" || $PROXY in s) break; - } - if (i === props.length) sources = props; + if (slots && props.$slot === true) props = slotSpreadSource(tag, props); else { - viewKeys = []; - owners = []; - for (let i = 0; i < props.length; i++) { - let s = props[i]; - // A function source is a plain thunk, called once (see above); a - // nullish source contributes nothing (#3297). - if (typeof s === "function") s = s(); - if (s != null) sourceOwners(s, viewKeys, owners); + let i = 0; + for (; i < props.length; i++) { + const s = props[i]; + if (s == null || typeof s === "function" || $PROXY in s || (slots && s.$slot === true)) + break; + } + if (i === props.length) sources = props; + else { + viewKeys = []; + owners = []; + if (slots) ownerIndex = []; + collectSpreadSources(tag, props, viewKeys, owners, slots, ownerIndex); } } } else if (props == null) { @@ -4311,6 +4358,8 @@ export function ssrElement(tag, props, children, needsId, skip, attrs) { owners = []; sourceOwners(props, viewKeys, owners); } else proxy = true; + } else if (slots && props.$slot === true) { + props = slotSpreadSource(tag, props); } const info = tagInfo(tag); const skipChildren = info.isVoid; @@ -4318,6 +4367,12 @@ export function ssrElement(tag, props, children, needsId, skip, attrs) { // already does), so skipped props leave no stray whitespace behind: // `
- ` rather than `
- ` (#3382). let result = info.open + hk; + // Handler/ref positions met under `slots` (principles §9.2.3), by position + // with the index of the source that owns each; emitted as one marker each + // after the walk, settled against the compiled `claims` in source order + // (see spreadBehaviorMarkers). Never touched outside a server component's + // render. + let behaviors = null; // One walk over one prop body: the outer loop runs once for a single props // object and once per source otherwise. With several sources every // source's key list is taken once up front, and "a later source owns this @@ -4384,34 +4439,49 @@ export function ssrElement(tag, props, children, needsId, skip, attrs) { const value = props[prop]; // Nullish is "not set" for every attribute, `style`/`class` included — // the client removes the attribute for `undefined`, and emitting - // `style=""` here made the server disagree with it (#3382). - if ( - value == undefined || - prop === "ref" || - prop.startsWith("on") || - prop.startsWith("prop:") - ) { - // Behavior claims ride NAMED ref/on* positions only — the compiler - // can't see through a spread, so a claim-carrying stub landing here - // silently drops. Say so where the author can act on it. - if ( - "_SOLID_DEV_" && - typeof value === "function" && - value[CLAIM_PROP] !== undefined && - (prop === "ref" || prop.slice(0, 2) === "on") - ) { - devCheck({ - code: "BEHAVIOR_CLAIM_DROPPED", - kind: "ssr", - severity: "warn", - message: - `[BEHAVIOR_CLAIM_DROPPED] A spread on a server-rendered <${tag}> carries \`${prop}\` from client props — ` + - `spreads don't participate in behavior claims, so this drops. ` + - `Write the position out: \`${prop}={props.${String(value[CLAIM_PROP])}}\`.`, - data: { reason: "spread", tag, position: prop, prop: String(value[CLAIM_PROP]) } - }); - } + // `style=""` here made the server disagree with it (#3382). A nullish + // handler/ref key still OWNS its position under `slots`: the client's + // spread shadows an earlier source's key by presence (`collectProps`, + // `sourceHas`), then attaches nothing for `undefined` — so a named + // handler before this source binds nothing either. + if (value == undefined) { + if (slots && claims !== undefined && (prop === "ref" || prop.startsWith("on"))) + behaviors = spreadBehaviorPosition( + behaviors, + prop, + value, + ctx.claims, + ownerIndex !== null ? ownerIndex[i] : s, + true + ); + continue; + } + if (prop.startsWith("prop:")) { + // A property write has no server side; a stand-in there is named. + if (slots && typeof value === "object") spreadPropPosition(prop, value); continue; + } + // An attribute-slot value at this key (principles §9.2.3) binds the position + // the key names: an attribute, a handler, a ref, or — for `class` / + // `style` objects — a name inside the attribute. A stand-in is an + // object, so under `slots` every object value takes the one helper + // that knows them (`spreadObjectAttribute`; the compiled positions + // share it); strings and booleans — the walk's common case — never + // do, and outside a server component the ladder is the pre-slot one. + if (prop === "ref" || prop.startsWith("on")) { + if (slots) + behaviors = spreadBehaviorPosition( + behaviors, + prop, + value, + ctx.claims, + ownerIndex !== null ? ownerIndex[i] : s, + claims !== undefined + ); + continue; + } + if (slots && typeof value === "object") { + result += spreadObjectAttribute(prop, value); } else if (prop === "style") { result += ` style="${ssrStyle(value)}"`; } else if (prop === "class") { @@ -4444,6 +4514,15 @@ export function ssrElement(tag, props, children, needsId, skip, attrs) { // source it replaces had its getters read: the expressions run at the same // point in the hydration-id sequence. Evaluating it in argument position // would move them ahead of the element's own key. + // `claims` is the compiled claim map of the element's named `ref`/`on*` + // attributes (the spread element's counterpart of the template path's + // guarded `ssrClaim` hole), keyed by the source index each attribute sits + // before, a thunk read only inside a server component's render — the same + // gate the template path's guard reads — so plain SSR never evaluates a + // handler expression. Called here, after the walk and before the tail + // thunk, for the same hydration-id reason. + if (slots && (behaviors !== null || claims !== undefined)) + result += spreadBehaviorMarkers(behaviors, claims, ctx.claims); if (attrs !== undefined) result += typeof attrs === "function" ? attrs() : attrs; // The hydration key is unquoted, so a void element needs the space before // `/>` or the slash becomes part of the key's value. @@ -4478,9 +4557,19 @@ export function ssrElementAttribute(key, value) { // absent, `""` is a bare attribute, anything else is attribute-escaped. // `key` is a compile-time attribute name (never `ref`, `on*` or `prop:*`, // which the compiler drops) and is trusted like `ssrAttribute`'s. + // + // Under the `serverComponents` compiler option a dynamic `class`/`style` + // on an intrinsic element compiles to THIS helper rather than into + // template quotes, so an attribute-slot value (principles §9.2.3) — the whole + // value, or a name's condition inside the object — can emit its position + // marker beside the attribute. if (value == undefined) return ""; - if (key === "style") return ` style="${ssrStyle(value)}"`; - if (key === "class") return ` class="${ssrClassName(value)}"`; + if (key === "style" || key === "class") { + return typeof value === "object" + ? slotClassOrStyle(key, value) + : ` ${key}="${key === "class" ? ssrClassName(value) : ssrStyle(value)}"`; + } + if (isSlotValue(value)) return slotAttribute(key, value); if (typeof value === "boolean") return value ? ` ${key}` : ""; return value === "" ? ` ${key}` : ` ${key}="${escape(value, true)}"`; } @@ -4490,9 +4579,17 @@ export function ssrAttribute(key, value) { // Compiler contract: `key` is always a compile-time string literal emitted // from a JSX attribute name (see setAttr in babel-plugin/src/ssr/element.js) // which can never contain `"`, `<`, `&`, or `>`. `value` is already - // attribute-escaped by the compiler via `_$escape(..., true)`. Both are - // trusted here so this hot path stays a pure string concatenation. - return value == null || value === false ? "" : value === true ? ` ${key}` : ` ${key}="${value}"`; + // attribute-escaped by the compiler via `_$escape(..., true)` — which + // passes an attribute-slot value through untouched, so the position it names + // is bound here (principles §9.2.3). Both are trusted here so this hot + // path stays a pure string concatenation. + if (value == null || value === false) return ""; + if (typeof value === "object") { + return isSlotValue(value) + ? slotAttribute(key, value) + : ` ${key}="${escape(String(value), true)}"`; + } + return value === true ? ` ${key}` : ` ${key}="${value}"`; } export function ssrHydrationKey(): string; @@ -4501,81 +4598,529 @@ export function ssrHydrationKey() { return hk ? ` _hk=${hk}` : ""; } -// ---- server-component behavior claims (Stage 6: ref/event props) ---- +// ---- Attribute slots: positions in server markup that a client fill's values own ---- +// +// (server-components-principles.md §9.2.3.) A slot is a client render; a +// ATTRIBUTE slot's fill returns a plain object instead of JSX, and the server +// template consumes it by reading properties at positions: +// +// const row = props.row({ id, completed }); +//
- +// +// +// The call mints the occurrence and its args record exactly as a placed +// (markup) slot call does; what comes back is the slot PROXY (frame-sink.ts), +// whose property reads hand out `SLOT_VALUE`-branded stand-ins: the +// occurrence, the property name and — on the document face, where the fill +// ran at t=0 — the value. Every place an attribute value is written on the +// server recognizes the brand and does two things: writes the t=0 value as +// the attribute (document face; the stream face never runs fills and writes +// nothing) and emits the position's MARKER beside it, on the consuming +// element: // -// Compiled SSR output (behind the `serverComponents` compiler option) emits -// `ctx.claims ? ssrClaim({ click: expr, ref: expr2 }) : ""` as a -// whole-attribute hole on intrinsic elements carrying ref/on* positions. The -// brand is the slot-props stub: a function-valued prop read off a server -// component's props proxy carries its prop name (CLAIM_PROP), and the marker -// simply names it — `_bnd="click=onCopy"`. Resolution happens client-side at -// dispatch/adoption time through the frame's LIVE props (nearest `data-fid` -// ancestor), which is what makes re-renders latest-props by construction: no -// binding table, no versioning, no supersession window. +// _s:
=" : " whole attribute +// _s:class=" : = ,…" a name inside class/style +// _s:on: =" : " handler +// _s:ref=" : [,…]" ref // -// The gate has two layers, split between evaluation and mint: -// - `ctx.claims` (the compiled guard) is ARMING — a plain enum the frame -// renderers set at server-component entry, so renders with no server -// components never evaluate the expressions (a property miss), and -// context clones carry it by spread. -// - the mint check here is SCOPE — on the document face (CLAIMS_DOCUMENT) -// only owner chains inside the component barrier mint. Client fill -// content re-enters the zone owner captured OUTSIDE the barrier, so -// fills neither claim nor warn (their handlers are hydration's, and -// legitimate). The stream face (CLAIMS_STREAM) mints unconditionally: -// the whole response is the component and fills never render there. -export const CLAIM_PROP = /*#__PURE__*/ Symbol.for("solid.claim-prop"); +// The `_hk` family: framework-owned marks. The client frame discovers +// consumers by these attributes, groups them by occurrence, runs the fill +// once per occurrence and writes each position from the returned object; +// the morph reads the same markers off incoming markup to know which +// positions are the client's. Keys are semantic (the client's names), +// positions structural (the template decides what a property IS by where it +// binds it) — nothing in the object says attribute, handler or ref. +// +// Where the brand is met: `ssrAttribute` (a compiled attribute; `escape` +// passes the stand-in through), `ssrElementAttribute` (a compiled +// `class`/`style` under the `serverComponents` option, or a trailing +// attribute of a spread element), `ssrElement`'s walk (a runtime spread), +// `ssrClaim` (the compiled per-element hole for ref/on* positions). The +// grammar: the occurrence alphabet (frame-sink.ts) excludes `:`, `,` and +// `=`; keys and names percent-encode onto an alphabet that excludes them +// too, so every split is exact and the client decodes names back. + +// The compiled guard's arming values (`sharedConfig.context.claims`): the +// frame renderers set one at server-component entry so renders with no +// server components never evaluate the ref/on* hole's expressions. On the +// document face only owner chains inside the component barrier warn about +// server-local handlers (client fill content re-enters the zone owner +// captured OUTSIDE the barrier — its handlers are hydration's). export const CLAIMS_STREAM = 1; export const CLAIMS_DOCUMENT = 2; -// `_bnd` value grammar: `pos=prop[,pos=prop]*`. Prop names are client- -// controlled strings landing in a quoted attribute that splits on `,`/`=`, -// so unsafe characters percent-encode — URI-style (UTF-8 %XX sequences), -// because unlike occurrence ids the CLIENT decodes these back to prop names -// (`decodeURIComponent` at dispatch). The passthrough alphabet is attribute- -// and grammar-safe; `%` itself encodes, so the mapping is injective. -// Position names come from static JSX attribute names and are grammar-safe -// by construction. -const CLAIM_UNSAFE = /[^A-Za-z0-9_.!~*'()-]/g; -function encodeClaimKey(key) { - return String(key).replace(CLAIM_UNSAFE, c => encodeURIComponent(c)); +/** The brand on an attribute slot's stand-in for one property read. */ +export const SLOT_VALUE = /*#__PURE__*/ Symbol.for("solid.slot-value"); +/** Marker attribute prefix on a consuming element (`_s:class`, `_s:on:click`, `_s:ref`). */ +export const SLOT_MARKER = "_s:"; +/** Faces a stand-in can come from (`slotValue`'s `face`). */ +export const SLOT_FACE_STREAM = 0; +export const SLOT_FACE_DATA = 1; +export const SLOT_FACE_MARKUP = 2; + +const ATTRIBUTE_SLOT_POSITION = "ATTRIBUTE_SLOT_POSITION"; + +/** + * Report a position finding once per (occurrence, key, reason, position) for + * the current render: a live hole evaluates its expression more than once + * (registration, then the baseline the re-emission ledger keeps), and the + * same misuse must not print twice. The set lives on the render context and + * dies with it. + */ +function slotFinding(sv, reason, position, message, severity = "warn") { + if ("_SOLID_DEV_") { + const ctx = sharedConfig.context; + if (ctx) { + const id = `${sv[SLOT_VALUE]}\u0000${sv.k}\u0000${reason}\u0000${position || ""}`; + const seen = ctx.slotFindings || (ctx.slotFindings = new Set()); + if (seen.has(id)) return; + seen.add(id); + } + devCheck({ + code: ATTRIBUTE_SLOT_POSITION, + kind: "ssr", + severity, + message, + data: { reason, occurrence: sv[SLOT_VALUE], key: sv.k, position } + }); + } } -export function ssrClaim(map) { - const mode = sharedConfig.context && sharedConfig.context.claims; - if ( - !mode || - (mode === CLAIMS_DOCUMENT && - !(typeof inServerComponentScope === "function" && inServerComponentScope())) - ) { - return ""; +export function isSlotValue(value: unknown): boolean; + +export function isSlotValue(value) { + return value !== null && typeof value === "object" && value[SLOT_VALUE] !== undefined; +} + +/** + * An attribute slot's stand-in for one property read. `face` says what the + * occurrence's fill produced where this read happens: nothing (the stream + * face never runs fills), a data object (the document face — `value` is + * the t=0 value of `key`), or markup (the document face ran the fill and + * it returned content — a read off it is a dev finding at the position). + * The server has no value to compute with — on the stream face none at + * all, on the document face only the t=0 one — so the ONLY thing a stand-in + * can be is the whole value at one position. Every coercion the runtime can + * see (a template literal, `+`, a comparison, an explicit `String()`) is a + * dev finding, and it renders NOTHING on either face: the document face + * never shows a t=0 value the stream face cannot reproduce, so a misuse is + * visible on the first render rather than on the first refetch. Truthiness + * (`if (row.done)`, `row.x && …`) has no hook and is the one misuse only + * the rule can catch — a stand-in is an object and always truthy. + * @internal Created by the slot proxies (frames server). + */ +export function slotValue(occurrence: string, key: string, value: unknown, face: number): object; + +export function slotValue(occurrence, key, value, face) { + const sv = { [SLOT_VALUE]: occurrence, k: key, v: value, f: face }; + // Every implicit coercion goes through `Symbol.toPrimitive` first: + // `>`/`<`/arithmetic/`==` with hint "number" or "default", template + // literals, `String(x)` and string concatenation with "string". An + // explicit `.toString()` call is the one path around it. + Object.defineProperty(sv, Symbol.toPrimitive, { + value: hint => slotValueString(sv, hint === "string" ? "stringified" : "coerced") + }); + Object.defineProperty(sv, "toString", { value: () => slotValueString(sv, "stringified") }); + return sv; +} + +function slotValueString(sv, reason) { + if ("_SOLID_DEV_") { + const prop = propOfOccurrence(sv[SLOT_VALUE]); + slotFinding( + sv, + reason, + undefined, + reason === "coerced" + ? `[${ATTRIBUTE_SLOT_POSITION}] \`${prop}\`'s \`${sv.k}\` is an attribute-slot value used in an expression ` + + `(a comparison, arithmetic, or a branch on its result). The server does not have the value — ` + + `the client owns it — so nothing can be computed from it here. It must be the WHOLE value of ` + + `an attribute, class name, style property, handler or ref; a decision that depends on it ` + + `belongs in the client fill (return the decided value) or in a markup slot.` + : `[${ATTRIBUTE_SLOT_POSITION}] \`${prop}\`'s \`${sv.k}\` is an attribute-slot value ` + + `and was stringified outside a bindable position — it must be the WHOLE value of an attribute, ` + + `class name, style property, handler or ref (\`class={row.${sv.k}}\`, not \`class={\`x \${row.${sv.k}}\`}\`). ` + + `If it is, the element was compiled without the \`serverComponents\` compiler option. ` + + `Nothing renders here on either face.` + ); + } + return ""; +} + +function slotTextPosition(sv) { + if ("_SOLID_DEV_") { + slotFinding( + sv, + "text", + undefined, + `[${ATTRIBUTE_SLOT_POSITION}] \`${sv.k}\` of slot \`${propOfOccurrence(sv[SLOT_VALUE])}\` is placed as TEXT. ` + + `Text is not a bindable position yet: nothing renders here on either face. ` + + `Bind it to an attribute, or render the text in a markup slot.` + ); + } + return ""; +} + +function slotMarkupRead(sv, position) { + if ("_SOLID_DEV_" && sv.f === SLOT_FACE_MARKUP) { + slotFinding( + sv, + "markup", + position, + `[${ATTRIBUTE_SLOT_POSITION}] \`${position}\` reads \`${sv.k}\` off slot \`${propOfOccurrence(sv[SLOT_VALUE])}\`, ` + + `but the client fill returned markup, not an object. A slot renders one or the other: ` + + `return an object (\`{ ${sv.k}: … }\`) for positions, or place the slot as content.` + ); } +} + +/** A stand-in rendered where its marker cannot go (inside template quotes): + * a dev finding; the position gets no value (`undefined`) on either face. */ +function slotValueInline(kind, sv) { + if ("_SOLID_DEV_") { + slotFinding( + sv, + "inline", + kind, + `[${ATTRIBUTE_SLOT_POSITION}] An attribute-slot value (\`${sv.k}\` of \`${propOfOccurrence(sv[SLOT_VALUE])}\`) ` + + `reached \`${kind}\` inside template quotes, where its position marker cannot be emitted — the ` + + `element was compiled without the \`serverComponents\` compiler option. Nothing renders here ` + + `on either face.` + ); + } + return undefined; +} + +// ` : [= ]` — the marker value's one entry. Keys and +// names are client-controlled strings landing in a quoted attribute that +// splits on `,`, `:` and `=`; they percent-encode URI-style onto an +// alphabet that excludes all three (and `%`, so the mapping is injective), +// and the CLIENT decodes them back (`decodeURIComponent`). +const SLOT_KEY_UNSAFE = /[^A-Za-z0-9_.!~*'()-]/g; +function encodeSlotKey(key) { + return String(key).replace(SLOT_KEY_UNSAFE, c => encodeURIComponent(c)); +} +function slotEntry(sv, name) { + return `${sv[SLOT_VALUE]}:${encodeSlotKey(sv.k)}${name !== undefined ? "=" + encodeSlotKey(name) : ""}`; +} +function slotMarker(position, entries) { + return ` ${SLOT_MARKER}${position}="${entries}"`; +} +function propOfOccurrence(occurrence) { + const i = occurrence.indexOf("#"); + return i === -1 ? occurrence : occurrence.slice(0, i); +} + +/** One whole attribute bound to a stand-in: the t=0 value, then the marker. */ +function slotAttribute(key, sv) { + slotMarkupRead(sv, key); let out = ""; - for (const pos in map) { - const value = map[pos]; - const list = Array.isArray(value) ? value : [value]; - for (const fn of list) { - const prop = (typeof fn === "function" && fn[CLAIM_PROP]) || undefined; - if (prop === undefined) { - if ("_SOLID_DEV_") { - devCheck({ - code: "BEHAVIOR_CLAIM_DROPPED", - kind: "ssr", - severity: "warn", - message: - `[BEHAVIOR_CLAIM_DROPPED] A \`${pos}\` position on a server-rendered element received a server-local ` + - `${typeof fn} — this handler can never run. Pass the function through the ` + - `server component's props from the client (compose on the client before ` + - `passing), or bind a mutation to \`action=\`.`, - data: { reason: "server-local", position: pos, received: typeof fn } - }); + if (sv.f === SLOT_FACE_DATA) { + const v = sv.v; + if (v != null && v !== false) { + out = v === true || v === "" ? ` ${key}` : ` ${key}="${escape(String(v), true)}"`; + } + } + return out + slotMarker(key, slotEntry(sv)); +} + +/** + * `class`/`style` as `ssrElementAttribute` writes them: the whole value may + * be a stand-in, or the object's members may be (a class name's condition, + * a style property's value) — each member binds that NAME. Without a + * stand-in anywhere the output is the plain helpers', byte for byte. + */ +function slotClassOrStyle(key, value) { + const isClass = key === "class"; + if (isSlotValue(value)) { + slotMarkupRead(value, key); + let out = ""; + if (value.f === SLOT_FACE_DATA && value.v != null) { + out = ` ${key}="${isClass ? ssrClassName(value.v) : ssrStyle(value.v)}"`; + } + return out + slotMarker(key, slotEntry(value)); + } + if (typeof value === "object" && value !== null) { + const obj = isClass ? classListToObject(value) : value; + let entries = ""; + let inner = ""; + for (const name of Object.keys(obj)) { + let v = obj[name]; + if (isSlotValue(v)) { + slotMarkupRead(v, `${key}:${name}`); + entries += (entries ? "," : "") + slotEntry(v, name); + v = v.f === SLOT_FACE_DATA ? v.v : undefined; + } + if (isClass) { + if (!name || name === "undefined" || !v) continue; + inner += (inner ? " " : "") + escape(name, true); + } else if (v != undefined) { + const r = escape(v, true); + if (r != undefined && r !== "undefined") { + inner += (inner ? ";" : "") + `${escape(name, true)}:${r}`; + } + } + } + // No stand-in: `inner` IS the plain helper's string (same walk, same + // escaping, same skips), written as the plain path writes it. + if (entries === "") return ` ${key}="${inner}"`; + return (inner ? ` ${key}="${inner}"` : "") + slotMarker(key, entries); + } + return ` ${key}="${isClass ? ssrClassName(value) : ssrStyle(value)}"`; +} + +/** `onClick` → `click` (the client runtime's derivation). */ +function eventPosition(prop) { + return prop.slice(2).toLowerCase(); +} + +/** + * A `ref`/`on*` key met by `ssrElement`'s walk under `slots` — in a + * source, whatever its shape: a stand-in, a list of them (refs), a handler + * tuple, a server-local function, nothing — collected by position into + * `behaviors` exactly as `ssrClaim` reads the compiled claim map, so the + * spread path and the template path bind the same shapes and raise the + * same finding. A later source owns a key outright (the walk reads only + * the owner), so within the sources a position is one value. With no + * compiled claims on the element (`settle` false — the common spread, and + * the gated walk's hot path) the map is `pos` → marker entries, empty + * positions left out. With claims to settle, `pos` → `{ e: entries, at: + * owning source index }`, every position recorded whatever its value: a + * server-local function or `undefined` owns the position as the client + * sees it (`collectProps` shadows by key presence) and binds nothing + * (spreadBehaviorMarkers). + */ +function spreadBehaviorPosition(behaviors, prop, value, mode, index, settle) { + const pos = prop === "ref" ? "ref" : eventPosition(prop); + const entries = value == null ? "" : claimEntries(pos, value, mode); + if (!settle) { + if (entries) (behaviors ||= new Map()).set(pos, entries); + return behaviors; + } + behaviors ||= new Map(); + const b = behaviors.get(pos); + if (b === undefined) behaviors.set(pos, { e: entries, at: index }); + else { + b.e = entries; + b.at = index; + } + return behaviors; +} + +/** + * The behavior markers of a spread element: the sources' (`behaviors`) + * settled against its compiled claim map (`claims` — the named `ref`/`on*` + * attributes, keyed by the index of the source each sits before; a thunk + * `ssrElement` calls only under `slots`, so plain SSR never evaluates + * them). The marker promises what the client binds, and the client's + * `spread(el, [a, { onClick }, b])` keeps the LAST source that HAS the key + * (`collectProps`: a later source's key shadows by presence; `merge()`'s + * lookup is `property in s`), a named attribute being a source at its + * position: a named handler at index `k` binds unless a spread at index + * `k` or later owns the position — with any value, `undefined` included — + * and a nullish named handler that is not so owned clears the position + * (the client attaches nothing for `undefined`); a later named attribute + * overrides an earlier one (the compilers keep only the last, so a segment + * never repeats a handler). Refs merge whatever their order (the client + * fires every ref); a nullish ref contributes nothing. One marker per + * position. + */ +function spreadBehaviorMarkers(behaviors, claims, mode) { + if (claims !== undefined) { + const segments = claims(); + // Integer keys enumerate in ascending order: source order. + for (const k in segments) { + const map = segments[k]; + for (const pos in map) { + const value = map[pos]; + behaviors ||= new Map(); + const b = behaviors.get(pos); + if (pos === "ref") { + if (value == null) continue; + const entries = claimEntries("ref", value, mode); + if (!entries) continue; + if (b === undefined) behaviors.set("ref", { e: entries, at: -1 }); + else b.e = b.e ? b.e + "," + entries : entries; + continue; + } + if (b !== undefined && b.at >= +k) continue; + const entries = value == null ? "" : claimEntries(pos, value, mode); + if (b === undefined) behaviors.set(pos, { e: entries, at: -1 }); + else b.e = entries; + } + } + } + let out = ""; + if (behaviors !== null) { + for (const [pos, b] of behaviors) { + const e = claims === undefined ? b : b.e; + if (e) out += slotMarker(pos === "ref" ? "ref" : "on:" + pos, e); + } + } + return out; +} + +/** + * `ssrElement`'s collecting pass for sources that are not all plain + * literals: a function source is a plain thunk, called once (see the walk; + * the compilers thunk a spread CALL, `{...props.row(args)}`); a nullish + * source contributes nothing (#3297); a slot's return spread whole is the + * retired shape (`slotSpreadSource`, probed only under `slots` — see the + * walk); everything else is collected through its leaves (`sourceOwners`). + * Under `slots` (`ownerIndex` given) each key also records the index of the + * source it came from, kept in step with `sourceOwners`' merge (a key seen + * again moves to the end, owned by the later source): what settles a + * handler position against the element's named claims. + */ +function collectSpreadSources(tag, props, viewKeys, owners, slots, ownerIndex) { + for (let i = 0; i < props.length; i++) { + let s = props[i]; + if (typeof s === "function") s = s(); + if (s != null) { + if (slots && !($PROXY in s) && s.$slot === true) s = slotSpreadSource(tag, s); + if (ownerIndex === null) sourceOwners(s, viewKeys, owners); + else { + const ks = []; + const os = []; + sourceOwners(s, ks, os); + for (let j = 0; j < ks.length; j++) { + const at = viewKeys.indexOf(ks[j]); + if (at !== -1) { + viewKeys.splice(at, 1); + owners.splice(at, 1); + ownerIndex.splice(at, 1); + } + viewKeys.push(ks[j]); + owners.push(os[j]); + ownerIndex.push(i); } - continue; } - out += `${out ? "," : ""}${pos}=${encodeClaimKey(prop)}`; } } - return out ? ` _bnd="${out}"` : ""; +} + +/** + * A `prop:*` key of a runtime spread whose value is a stand-in: the + * compiler drops `prop:` on the server (a property is the client DOM's), so + * a slot cannot bind there yet — nothing renders, and dev says so. + */ +function spreadPropPosition(prop, value) { + if ("_SOLID_DEV_" && isSlotValue(value)) { + slotFinding( + value, + "prop", + prop, + `[${ATTRIBUTE_SLOT_POSITION}] \`${value.k}\` of slot \`${propOfOccurrence(value[SLOT_VALUE])}\` is bound ` + + `at \`${prop}\`. Property positions are not bindable (the server renders no properties): nothing ` + + `renders here. Bind the attribute form (\`${prop.slice(5)}\`), or set the property in the client fill's ref.` + ); + } +} + +/** + * An object value at an attribute key of a runtime spread: a `class`/`style` + * map (which may carry stand-ins as its conditions), a stand-in for the + * whole attribute, or any other object, attribute-escaped as its string. + */ +function spreadObjectAttribute(prop, value) { + if (prop === "style" || prop === "class") return slotClassOrStyle(prop, value); + if (value[SLOT_VALUE] !== undefined) return slotAttribute(attrName(prop), value); + return ` ${attrName(prop)}="${escape(value, true)}"`; +} + +/** + * A slot's return spread whole onto an element (` - `): the + * retired shape — the client would decide what it owns and the template + * could not show it. Dev throws; prod contributes nothing. + */ +function slotSpreadSource(tag, source) { + if ("_SOLID_DEV_") { + const occurrence = source.$occurrence; + const text = + `[${ATTRIBUTE_SLOT_POSITION}] A slot${occurrence ? ` (\`${propOfOccurrence(occurrence)}\`)` : ""} is spread ` + + `onto a server-rendered <${tag}>. An attribute slot binds by position — name each one ` + + `(\`class={row.rowClass} onClick={row.remove}\`) so the template shows what the client owns.`; + recordFinding({ + code: ATTRIBUTE_SLOT_POSITION, + kind: "ssr", + severity: "error", + message: text, + data: { reason: "spread", tag, occurrence } + }); + throw new Error(text); + } + return {}; +} + +/** + * The compiled per-element hole for ref/on* positions on a server + * intrinsic (behind the `serverComponents` compiler option): + * `ctx.claims ? ssrClaim({ click: expr, ref: expr2 }) : ""`. The compiler + * drops handler and ref expressions from plain SSR output, so this is + * where a stand-in at one of those positions is seen. A server-local + * function there can never run (the server has no client to run it on); + * dev says so, inside the component barrier only. + */ +export function ssrClaim(map: Record
+ + ); + }; + const Inline = frameTransformDirectResult(ServerComp, { id: "dscl" }) as any; + const html = plain( + await document(() => [ + , + Inline({ codeBlock: () => ({ copy: () => {} }) }), + , + {}} /> + ]) + ); + expect(seen).toEqual([undefined, undefined]); + expect(html).toContain(''); + expect(html).toMatch(/<\/div>/); + expect(findings()).toEqual([]); + }); + + it("a fill that returned markup is read as data at a position: a dev finding, nothing written", async () => { + const ServerComp = (props: any) => { + const row = props.row({ id: 1 }); + return- x
; + }; + const Inline = frameTransformDirectResult(ServerComp, { id: "dsd1" }) as any; + const html = plain(await document(() => Inline({ row: () => content }))); + expect(html).toContain('- x
'); + expect(findings("markup").length).toBe(1); + }); + + it("fill keys that shadow prototype methods (`filter`, `at`, `sort`, `map`, `join`) bind as data on both faces", async () => { + // The document-face proxy's target is the range ARRAY and the stream + // face's a plain object: a key present on either prototype must still + // read as a slot value, never fall through to the prototype (which on + // the document face wrote `data-f="function filter() { [native code] }"` + // with no marker, and `hidden={row.at}` hid the element). + const ServerComp = (props: any) => { + const row = props.row({ id: 1 }); + return ( +- + x +
+ ); + }; + const Inline = frameTransformDirectResult(ServerComp, { id: "dsd2p" }) as any; + const html = plain( + await document(() => + Inline({ row: () => ({ filter: "f", at: false, sort: "s", map: true, join: "j" }) }) + ) + ); + expect(html).toContain( + '- ' + ); + expect(html).toContain('x'); + expect(html).not.toContain("native code"); + expect(findings()).toEqual([]); + + const chunks = await collect(renderServerComponent(ServerComp, { frame: { id: "ds2p" } })); + const stream = plain(chunks.find(c => c.type === "html").html); + expect(stream).toContain( + '
- x
' + ); + expect(findings()).toEqual([]); + }); + + it("a placed document-face range with a dynamic node survives the resolver's copy", async () => { + // `escape` copies a node array with `.slice()` when it cannot join it + // (a function node forces the copy). The document-face range is a + // proxy over that array: `slice` must reach Array.prototype, not be + // answered as a fill key — with the explicit passthrough set it was, + // and every dynamic placement threw `s.slice is not a function`. + const ServerComp = (props: any) =>{props.note()} ; + const Inline = frameTransformDirectResult(ServerComp, { id: "dsd0d" }) as any; + const html = plain( + await document(() => + Inline({ + note: () => { + const t = createMemo(() => "late"); + return {t()}; + } + }) + ) + ); + expect(html).toMatch(/- x
; + }; + const Inline = frameTransformDirectResult(ServerComp, { id: "dsd2" }) as any; + await document(() => Inline({ row: () => ({ removed: false, t: 1, $key: 2 }) })); + expect(findings("reserved-key").map(e => (e.data as any).key)).toEqual(["t", "$key"]); + }); + + it("a stand-in placed as text, stringified, or coerced renders NOTHING at t=0 too — the faces agree — with a dev finding each", async () => { + // The document face has the t=0 value and the stream face never does; + // rendering it at t=0 would make the first refetch change the page. + const ServerComp = (props: any) => { + const row = props.row({ id: 1 }); + return ( +-
+
- {row.title} + +
- 3 ? "yes" : "no"} data-sum={row.count + 1} /> +
++ ), + { manifest } + ); + + expect(html.match(/mod-content/g)).toHaveLength(2); + expect(resolved).toEqual(["./Mod.tsx"]); + }); }); describe("retry wrapper flattening", () => { diff --git a/packages/web/test/server/spread-slot-walk.bench.tsx b/packages/web/test/server/spread-slot-walk.bench.tsx new file mode 100644 index 000000000..4039ea4ae --- /dev/null +++ b/packages/web/test/server/spread-slot-walk.bench.tsx @@ -0,0 +1,69 @@ +// Tier-1 SSR-lane bench: the slot-aware spread walk (principles §9.2.3), +// under `renderServerComponent` — the stream face, where `context.claims` +// is armed for the whole render and `ssrElement`'s walk probes every +// object value and every non-literal source for a stand-in. Two forms: +// +// bound — `waiting}> + ++ + - `: one occurrence per row, +// read at a class-name, an attribute and a handler position. The +// walk mints three markers per element and the sink one record +// per occurrence — the per-row cost of an attribute slot. +// armed — the same spread with plain string values: the gate is up (the +// `context.claims` read per element) but no value is an object, +// so every slot probe short-circuits. The control — what a +// server component's ordinary elements pay for being inside one. +// +// `spread-static-tail` is the plain-SSR side of the same walk (the gate +// down); the two lanes together cover both branches of `slots`. +// +// Vitest's reported mean is the full stream — render, records, html chunk. + +/** + * @jsxImportSource @solidjs/web + */ +import { bench } from "vitest"; +import { renderServerComponent } from "../../frames/src/frame-sink.js"; + +const ROWS = 500; +const rows = Array.from({ length: ROWS }, (_, i) => ({ + id: i, + title: `Row ${i}`, + kind: i % 2 ? "odd" : "even" +})); + +const Bound = (props: any) => ( +
-
+ {rows.map(r => {
+ const row = props.row({ id: r.id });
+ return (
+
- + {r.title} + + ); + })} +
-
+ {rows.map(r => (
+
- {r.title} + ))} +
` reaches the server `createComponent` with its label // and diagnostics carry `ownerPath` (server-diagnostics.spec.tsx pins it). + // `serverComponents`: what the plugin passes for an SSR build with + // `serverFunctions.components` — attribute-slot positions (`ref`/`on*`, dynamic + // `class`/`style`) compile to runtime holes (test/server/frame-attribute-slots). plugins: [ solidPlugin({ compiler, - solid: { generate: "ssr", hydratable: true, sourceNames: true } + solid: { generate: "ssr", hydratable: true, sourceNames: true, serverComponents: true } }) ], test: { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4d9375091..f2bd3cd75 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -331,6 +331,25 @@ importers: specifier: ^7.0.0 version: 7.3.3(@types/node@25.6.0)(lightningcss@1.33.0)(terser@5.49.0) + examples/todos-server: + dependencies: + '@solidjs/web': + specifier: workspace:* + version: link:../../packages/web + solid-js: + specifier: workspace:* + version: link:../../packages/solid + unstorage: + specifier: ^1.17.5 + version: 1.17.5 + devDependencies: + '@solidjs/vite-plugin': + specifier: 3.0.0-next.35 + version: 3.0.0-next.35(@solidjs/web@packages+web)(@testing-library/jest-dom@6.9.1)(solid-js@packages+solid)(vite@8.1.5(@types/node@25.6.0)(esbuild@0.27.7)(terser@5.49.0)) + vite: + specifier: ^8.0.0 + version: 8.1.5(@types/node@25.6.0)(esbuild@0.27.7)(terser@5.49.0) + packages/babel-plugin: dependencies: '@babel/helper-module-imports': @@ -3512,10 +3531,6 @@ packages: resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==} engines: {node: '>=8.6'} - picomatch@4.0.3: - resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==} - engines: {node: '>=12'} - picomatch@4.0.4: resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==} engines: {node: '>=12'} @@ -5915,7 +5930,7 @@ snapshots: dependencies: '@types/estree': 1.0.8 estree-walker: 2.0.2 - picomatch: 4.0.3 + picomatch: 4.0.5 optionalDependencies: rollup: 4.59.0 @@ -7142,8 +7157,6 @@ snapshots: picomatch@2.3.1: {} - picomatch@4.0.3: {} - picomatch@4.0.4: {} picomatch@4.0.5: {} @@ -7456,8 +7469,8 @@ snapshots: tinyglobby@0.2.16: dependencies: - fdir: 6.5.0(picomatch@4.0.4) - picomatch: 4.0.4 + fdir: 6.5.0(picomatch@4.0.5) + picomatch: 4.0.5 tinyglobby@0.2.17: dependencies: diff --git a/scripts/size/floor-caps.json b/scripts/size/floor-caps.json index 8a68bc927..bd2c40a4f 100644 --- a/scripts/size/floor-caps.json +++ b/scripts/size/floor-caps.json @@ -2,6 +2,6 @@ "signals: core floor (createSignal/Memo/Effect/Root/flush)": "9.51 KB", "app: render + one signal (the simple-app floor)": "12.05 KB", "app: hydrating (no stores) with Show/For/Loading/Errored/lazy": "19.69 KB", - "page: base server components (hydrating + dynamic + frames + sf reference)": "44.93 KB", - "page: live server components (base + live/GET + action + isPending/latest)": "49.10 KB" + "page: base server components (hydrating + dynamic + frames + sf reference)": "45.77 KB", + "page: live server components (base + live/GET + action + isPending/latest)": "49.96 KB" } diff --git a/scripts/size/scenarios.js b/scripts/size/scenarios.js index da6e9d685..b03d6ce52 100644 --- a/scripts/size/scenarios.js +++ b/scripts/size/scenarios.js @@ -2839,7 +2839,35 @@ module.exports = [ // rounded up to the next 0.01 kB. Deltas across this line are not comparable. // Rebased onto `next` @ ee49b3eee (2026-09-28): 11768 -> 11768 B, unchanged // by the three signals fixes that landed since (#3678, #3684, #3682); cap stays. - limit: "11.77 KB", + // + // Attribute slots, second form (#3704, 2026-09-28): 11.77 -> + // 12.70 KB, measured at 12,693 B against `next` @ 695836771's 11,768 + // (+925 B; 923 B over the cap). +3,259 B minified: frames client +3,225 + // (32,610 -> 35,835), the retained transport slice +34. The frames bytes + // are the feature replacing behavior claims: `_s: ` markers + // parsed per element (`slotPositions`, `ownedPositions`), a data + // occurrence's consumer set bound per position with a render effect per + // element (`bindDataOccurrence`, `consumersEqual`) — value positions + // diffed through `assign` with released positions pruned from the diff + // state, one listener per element fanning out to every key bound at an + // event, one stable ref per key set, a final empty write for an element + // the rebind dropped — the owned positions held through every morph + // path (`applyOwned` + the class/style splitters, in `morphAttributes` + // and `#applyAttrs`), and `#syncSlots` resolving fills by occurrence and + // args records by id. The `_bnd` claim path it retires (`bndMap`, + // `sweepBound`, `fireRefs`, `claimFn`, `clientProp`, ~1.8 KB + // unminified) is the offset already in the number. Dev-only (the + // `ATTRIBUTE_SLOT_POSITION` orphan and fill-shape reporters) is 0 B + // here: module functions behind the flag, not methods. Conscious bump: a + // consumer that never binds a slot still carries the position parser + // and the owned-attribute morph; a split behind the marker is the + // candidate follow-up, like the live reader's split behind the wire slot. + // Review fixes (#3704, same day): 12,693 -> 12,695 B (+2 B; +35 B + // minified, frames client 35,835 -> 35,870): an occurrence's `onCleanup` + // detaching the listeners it attached (a kept un-keyed element carried + // one per occurrence that ever bound it and fired twice; a dropped + // occurrence's handler ran through its disposed fill). Cap unchanged. + limit: "12.70 KB", alias: framesAlias, external: framesExternal }, @@ -2908,6 +2936,16 @@ module.exports = [ // -3 B minified). The same parking-gate change as the hydrating (no // stores) note; brotli layout turns the -3 B minified into a saving on // this page. Not ratcheted. + // Size-Exception (#3704, 2026-09-28): 44.93 -> 45.76 KB, + // measured at 45,756 B against `next` @ 695836771's 44,865 (+891 B; + // +3,165 B minified, all of it the frames client) — attribute slots, + // second form: the per-position binding of a slot's props on server + // elements, held through the morph paths, replacing the `_bnd` claim + // sweep (the frames scenario note itemizes it). Accepted by the + // maintainer. Review fixes, same PR: 45,756 -> 45,761 B (+5 B; +35 B + // minified — the occurrence's listener detach, frames note), over the + // rounded cap by 1 B; 45.76 -> 45.77 KB under the same exception. The + // cap is frozen again at 45.77 KB. limit: floorCaps["page: base server components (hydrating + dynamic + frames + sf reference)"], alias: pageAlias }, @@ -2959,6 +2997,12 @@ module.exports = [ // and the CSR app +5 B on the identical -3 B minified core; brotli layout // amplifies it here as #3684's and #3675's did. Accepted by the // maintainer. The cap is frozen again at 49.10 KB. + // Size-Exception (#3704, 2026-09-28): 49.10 -> 49.96 KB, + // measured at 49,951 B against `next` @ 695836771's 49,094 (+857 B; + // +3,165 B minified) — the same attribute-slot bytes as the base page; + // the live path adds nothing of its own. Accepted by the maintainer. The + // cap is frozen again at 49.96 KB. Review fixes, same PR: 49,951 -> + // 49,901 B (-50 B; +35 B minified — brotli layout), under the cap. limit: floorCaps["page: live server components (base + live/GET + action + isPending/latest)"], alias: pageAlias } - ` | spread: the template must show what the client owns | name each position | +| `onClick={() => …}` on a server element | a server function can never run in the browser | bind a slot property or a form `action` | + +Every case except truthiness is a dev finding (`ATTRIBUTE_SLOT_POSITION`) +and renders **nothing on either face**, so it shows on the first render. +Truthiness has no runtime hook: if a retry button appears on every row, this +is why. + +## Writing the fill + +- **Values as getters, handlers as plain closures** when a shared client + component also consumes the object (the usual case): + + ```tsx + const rowFor = (p: { id: string; completed: boolean }): RowBehavior => ({ + get rowClass() { + return { todo: true, completed: done(p.id, p.completed), pending: !!intent.byId[p.id] }; + }, + get done() { + return done(p.id, p.completed); + }, + get removed() { + return removed(p.id); + }, + onToggle: e => actions.toggle(p.id, e.currentTarget.checked), + onRemove: () => actions.remove(p.id) + }); + ``` + + A client `
- ", "