docs: re-sync the API reference against solid next and add the until page

- Disposition the exports added since the last sync: until (new reference
  page under Lifecycle & Actions, folding UntilOptions, Truthy, and
  TimeoutError), registerFlightDataSource (single-flight page),
  LiveServerFunction (live), DynamicOptions (dynamic), PreloadLink
  (renderToStream), and the attribution/observe types (DEV).
- Hide the wire-protocol constants and the store-target introspection
  helpers consumed by the DOM list driver.
- Add tone fixups for emphasis capitals in the upstream JSDoc.
- Regenerate all 93 reference pages from solid@05725e84.
- Stores: add 'fetch in memos, shape in stores' guidance.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

scripts/extract-solid-ref.mjs

@@ -109,6 +109,7 @@ const CANONICAL_ROUTES = {
 	affects: ["lifecycle-actions/affects.mdx", "Lifecycle & Actions"],
 	onSettled: ["lifecycle-actions/on-settled.mdx", "Lifecycle & Actions"],
 	refresh: ["lifecycle-actions/refresh.mdx", "Lifecycle & Actions"],
+	until: ["lifecycle-actions/until.mdx", "Lifecycle & Actions"],
 
 	children: ["components-context/children.mdx", "Components & Context"],
 	createContext: [
@@ -315,6 +316,10 @@ const ADVANCED_ROUTES = {
 		"server-functions/single-flight.mdx",
 		"Server functions / Integration",
 	],
+	registerFlightDataSource: [
+		"server-functions/single-flight.mdx",
+		"Server functions / Integration",
+	],
 	decodeResponse: [
 		"server-functions/single-flight.mdx",
 		"Server functions / Integration",
@@ -368,9 +373,21 @@ const FOLD_INTO = {
 	DiagnosticCode: "DEV",
 	DiagnosticEvent: "DEV",
 	DiagnosticKind: "DEV",
+	DiagnosticListener: "DEV",
+	DiagnosticSubject: "DEV",
 	Diagnostics: "DEV",
 	DiagnosticSeverity: "DEV",
+	AttributionHooks: "DEV",
+	AttributionSlot: "DEV",
+	InteractionRef: "DEV",
+	Observe: "DEV",
+	OBSERVE: "DEV",
 	DynamicProps: "Dynamic",
+	DynamicOptions: "dynamic",
+	Truthy: "until",
+	UntilOptions: "until",
+	TimeoutError: "until",
+	PreloadLink: "renderToStream",
 	EffectBundle: "createEffect",
 	EffectFunction: "createEffect",
 	EffectOptions: "createEffect",
@@ -417,6 +434,7 @@ const FOLD_INTO = {
 	ServerFunction: "withMeta",
 	ServerFunctionMetadata: "withMeta",
 	LiveSource: "live",
+	LiveServerFunction: "live",
 	LiveSourceStatus: "live",
 	InvokeOptions: "invoke",
 	ServerFunctionInvoker: "invoke",
@@ -550,7 +568,17 @@ const HIDDEN_EXPORTS = new Set([
 	"GENERIC_SERVER_ERROR_MESSAGE",
 	"HREF",
 	"INSTANCE_HEADER",
+	"NULL_BODY_STATUSES",
+	"REDIRECT_HEADER",
+	"RESPONSE_HEADER_VALUE_LIMIT",
 	"REVALIDATE_HEADER",
+	"UNKNOWN_HEADER",
+	"decodeRedirectHeaderValue",
+	"getFlightDataSourceIds",
+	// Store-target introspection consumed by the DOM list driver.
+	"storeHasFamily",
+	"storeHasOptimisticFamily",
+	"storeIsShallow",
 	"RequestContext",
 	"SAFE_ERROR",
 	"SERVER_FUNCTION_INVOKE",
@@ -626,6 +654,8 @@ const ENTRY_CALLOUTS = {
 };
 
 const ENTRY_SUMMARY_OVERRIDES = {
+	until:
+		"Awaits a reactive predicate and resolves the first time it becomes truthy, with the narrowed value. A falsy result or a pending async read means not yet, so the subscription stays live and re-evaluates as sources change. A thrown error, a rejected async source, a timeout, or an abort rejects the promise.",
 	affects:
 		"Marks a reactive source or store location as pending while work that will change it is in flight. Marked values remain readable, and derived readers report the pending state until the surrounding action or update settles.",
 	clientOnly:
@@ -923,6 +953,22 @@ const REFERENCE_FIXUPS = [
 		"createSignal<T>(fn, options?:",
 	],
 	[/the payload just has to be/g, "the payload must be"],
+	[/reads the AUTHORITATIVE view/g, "reads the authoritative view"],
+	[/target's NEXT QUIESCENT\s+STATE/g, "target's next settled state"],
+	[/transaction is STAGED;/g, "transaction is staged;"],
+	[/IMPORTANT for implementers/g, "Important for implementers"],
+	[/Fired BEFORE\b/g, "Fired before"],
+	[/against the DOCUMENT\s+URL/g, "against the document URL"],
+	[/it is ENTRY-ONLY:/g, "it is entry-only:"],
+	[/from READING the response/g, "from reading the response"],
+	[/to EXECUTE from any origin/g, "to execute from any origin"],
+	[/The DEPLOYMENT SECRET:/g, "The deployment secret:"],
+	[/the UNBOUND function base/g, "the unbound function base"],
+	[
+		/the optimistic store IS the live-fed store/g,
+		"the optimistic store is the live-fed store",
+	],
+	[/This is\s+load-bearing, not a loophole: truth/g, "This is required: truth"],
 	[/optimistic local edit/g, "temporary local edit"],
 	[/\(a "transition"\)/g, ""],
 	[

src/routes/(2)concepts/(1)stores.mdx

@@ -163,6 +163,22 @@ Check the box and "Write docs" appears above it; the row for "Review examples" i
 
 See the [`createProjection` reference](/reference/solid-js/stores/create-projection) for mutation and return forms.
 
+### Fetch in memos, shape in stores
+
+A projection function may return a promise, so `createStore(async () => api.rows(period()), [])` fetches and reconciles in one step.
+That collapsed form is right when nothing needs to sit between the request and the store.
+
+When something does, keep the two jobs apart: the memo owns the request, the store owns the shape.
+
+```tsx
+const rows = createMemo(() => api.rows(period()));
+const [table] = createStore(() => rows(), [] as Row[]);
+```
+
+`rows` is where you attach request-level concerns: [`isPending(rows)`](/reference/solid-js/reactivity/is-pending) for the refetch indicator, [`refresh(rows)`](/reference/solid-js/lifecycle-actions/refresh) to re-ask, a second consumer that reads the same response.
+`table` is where per-row tracking and reconciliation happen; when a new response lands, `rows` changes once and the store diffs it once.
+The line between them is the visible marker of where a request-level policy lives, and it is the shape the rest of the docs use when a fetch and a store appear together.
+
 ## Optimistic stores
 
 `createOptimisticStore` has the same nested draft update model with a tentative overlay.

src/routes/(2)concepts/(3)async-reactivity.mdx

@@ -762,6 +762,7 @@ Use `yield promise` as the suspension point, or place a bare `yield` before writ
 - Use [`refresh`](/reference/solid-js/lifecycle-actions/refresh) to rerun a derived source with the same inputs.
 - Use [`affects`](/reference/solid-js/lifecycle-actions/affects) to declare which data in-flight work can change.
 - Use [`resolve`](/reference/solid-js/advanced/interop-async/resolve) to await one reactive expression outside tracking.
+- Use [`until`](/reference/solid-js/lifecycle-actions/until) inside an action to hold it open until a predicate over confirmed state becomes true, such as a live source echoing the write.
 - Use [`onSettled`](/reference/solid-js/lifecycle-actions/on-settled) to run code after owned async work and queued updates settle.
 - Use `loadingValue` or `seedLoadingValue` when a placeholder value should answer for a source before its first result.
 

src/routes/reference/(1)solid-js/(1)reactivity/create-effect.mdx

@@ -55,15 +55,6 @@ system if there is none. It is _not_ routed to the bundle's `error` handler.
 createEffect<T>(compute, effectFn | { effect, error }, options?: EffectOptions);
 ```
 
-> Deprecated: `createEffect(compute)` (single argument) is no longer supported.
-> Pass a separate effect function as the second argument:
-> `createEffect(compute, effect)`. See `MISSING_EFFECT_FN`.
-
-- For a side effect that reacts to changes, split the work:
-  `createEffect(() => signal(), value => doWork(value))`.
-- For a derived value, use `createMemo(() => signal())`.
-- For a one-shot side effect at construction time, just call the function.
-
 ## Import
 
 ```ts
@@ -78,9 +69,6 @@ function createEffect<T>(
 	effectFn: EffectFunction<NoInfer<T>, T> | EffectBundle<NoInfer<T>, T>,
 	options?: EffectOptions
 ): void;
-function createEffect<T>(
-	compute: ComputeFunction<undefined | NoInfer<T>, T>
-): never;
 ```
 
 ## Parameters

src/routes/reference/(1)solid-js/(2)stores/create-optimistic-store.mdx

@@ -32,11 +32,12 @@ import { createOptimisticStore } from "solid-js";
 ```ts
 const createOptimisticStore: {
 	<T extends object = {}>(
-		store: NoFn<T> | Store<NoFn<T>>
+		initialValue: NoFn<T> | Store<NoFn<T>>,
+		options?: StoreOptions
 	): [get: Store<T>, set: StoreSetter<T>];
 	<T extends object = {}>(
-		fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
-		store: NoFn<T> | Store<NoFn<T>>,
+		fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
+		seed: Partial<T> | Store<NoFn<T>>,
 		options?: HydrationProjectionOptions
 	): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
 };

src/routes/reference/(1)solid-js/(2)stores/create-projection.mdx

@@ -31,7 +31,7 @@ import { createProjection } from "solid-js";
 ```ts
 const createProjection: <T extends object = {}>(
 	fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
-	initialValue: Partial<T> | Store<NoFn<T>>,
+	seed: Partial<T> | Store<NoFn<T>>,
 	options?: HydrationProjectionOptions
 ) => Refreshable<Store<T>>;
 ```
@@ -40,12 +40,13 @@ const createProjection: <T extends object = {}>(
 
 ### `ProjectionOptions`
 
-Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`.
+Options for derived/projected stores created with
+`createStore(fn, seed, options?)`, `createProjection(fn, seed, options?)`,
+or `createOptimisticStore(fn, seed, options?)`.
 
 ```ts
 interface ProjectionOptions extends StoreOptions {
 	key?: string | ((item: NonNullable<any>) => any) | null;
-	shallow?: boolean;
 	seedLoadingValue?: boolean;
 }
 ```
@@ -56,12 +57,6 @@ interface ProjectionOptions extends StoreOptions {
 
 Key property name or function for reconciliation identity; `null` merges positionally
 
-#### `shallow`
-
-- **Type:** `boolean`
-
-Single-layer store: root keys reactive, values raw records replaced by reference
-
 #### `seedLoadingValue`
 
 - **Type:** `boolean`

src/routes/reference/(1)solid-js/(2)stores/create-store.mdx

@@ -10,15 +10,15 @@ tags:
   - "api"
   - "v2"
 version: "2.0"
-description: "Public createStore: plain form `(init, options?)` and derived writable\nform `(fn, seed, options?)`."
+description: "Public createStore: plain form `(initialValue, options?)` and derived writable\nform `(fn, seed, options?)`."
 source_repo: "solidjs/solid"
 source_ref: "next"
 source_path: "packages/signals/src/store/index.ts"
 ---
 
 {/* Generated by scripts/extract-solid-ref.mjs. Edit the source JSDoc or disposition map, then regenerate. */}
 
-Public createStore: plain form `(init, options?)` and derived writable
+Public createStore: plain form `(initialValue, options?)` and derived writable
 form `(fn, seed, options?)`.
 
 ## Import
@@ -31,12 +31,12 @@ import { createStore } from "solid-js";
 
 ```ts
 function createStore<T extends object = {}>(
-	store: NoFn<T> | Store<NoFn<T>>,
-	options?: StoreOptions & { shallow?: boolean }
+	initialValue: NoFn<T> | Store<NoFn<T>>,
+	options?: StoreOptions
 ): [get: Store<T>, set: StoreSetter<T>];
 function createStore<T extends object = {}>(
-	fn: (store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
-	store: Partial<T> | Store<NoFn<T>>,
+	fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
+	seed: Partial<T> | Store<NoFn<T>>,
 	options?: ProjectionOptions
 ): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
 ```
@@ -45,12 +45,13 @@ function createStore<T extends object = {}>(
 
 ### `ProjectionOptions`
 
-Options for derived/projected stores created with `createStore(fn)`, `createProjection`, or `createOptimisticStore(fn)`.
+Options for derived/projected stores created with
+`createStore(fn, seed, options?)`, `createProjection(fn, seed, options?)`,
+or `createOptimisticStore(fn, seed, options?)`.
 
 ```ts
 interface ProjectionOptions extends StoreOptions {
 	key?: string | ((item: NonNullable<any>) => any) | null;
-	shallow?: boolean;
 	seedLoadingValue?: boolean;
 }
 ```
@@ -61,12 +62,6 @@ interface ProjectionOptions extends StoreOptions {
 
 Key property name or function for reconciliation identity; `null` merges positionally
 
-#### `shallow`
-
-- **Type:** `boolean`
-
-Single-layer store: root keys reactive, values raw records replaced by reference
-
 #### `seedLoadingValue`
 
 - **Type:** `boolean`
@@ -109,11 +104,12 @@ type Refreshable<T> = T & { readonly [$REFRESH]: any };
 
 ### `StoreOptions`
 
-Base options for store primitives.
+Options shared by all store primitives.
 
 ```ts
 interface StoreOptions {
 	name?: string;
+	shallow?: boolean;
 }
 ```
 
@@ -123,9 +119,15 @@ interface StoreOptions {
 
 Debug name (dev mode only)
 
+#### `shallow`
+
+- **Type:** `boolean`
+
+Single-layer store: root keys reactive, values raw records replaced by reference
+
 ### `StoreReturn`
 
-Tuple returned by the plain `createStore(initialValue)` form.
+Tuple returned by the plain `createStore(initialValue, options?)` form.
 
 ```ts
 type StoreReturn<T> = [get: Store<T>, set: StoreSetter<T>];
@@ -144,8 +146,9 @@ A store setter. The callback receives a writable **draft** of the store.
 
 The setter does **not** perform keyed reconciliation. If you need surviving
 items to keep their store identity across full-array replacement, use the
-projection form — `createStore(fn, seed, { key })` or `createProjection` —
-whose derive function reconciles its return by `options.key`.
+projection form — `createStore(fn, seed, { key })` or
+`createProjection(fn, seed, { key })` — whose derive function reconciles
+its return by `options.key`.
 
 ```ts
 type StoreSetter<T> = (fn: (state: T) => T | void) => void;

src/routes/reference/(1)solid-js/(3)lifecycle-actions/refresh.mdx

@@ -10,24 +10,42 @@ tags:
   - "api"
   - "v2"
 version: "2.0"
-description: "Invalidates one reactive source, forcing it to re-execute even if its inputs\nhaven't changed."
+description: "Invalidates one reactive source, forcing it to re-execute even if its inputs\nhaven't changed, and returns a promise for the target's next settled state — the re-ask (and anything that supersedes it) has settled."
 source_repo: "solidjs/solid"
 source_ref: "next"
-source_path: "packages/signals/src/core/core.ts"
+source_path: "packages/signals/src/signals.ts"
 ---
 
 {/* Generated by scripts/extract-solid-ref.mjs. Edit the source JSDoc or disposition map, then regenerate. */}
 
 Invalidates one reactive source, forcing it to re-execute even if its inputs
-haven't changed.
+haven't changed, and returns a promise for the target's next settled state — the re-ask (and anything that supersedes it) has settled.
 
 Pass either a Solid-created accessor or a projected store created from
 `createStore(fn, ...)` / `createProjection(...)`. `refresh()` is a
 write-like invalidation operation: it does not read the target's value, and
-refreshing a plain signal accessor is a no-op.
+refreshing a plain signal accessor is a no-op that resolves immediately.
 
-Use it to invalidate cached async values (e.g. force a re-fetch) without
-tearing the consumer down.
+The returned promise is safe to ignore (fire-and-forget refresh is
+unchanged, and a failed refetch will not surface an unhandled rejection).
+Awaiting it gives imperative flows the settle point without a reactive
+read:
+
+- Accessor targets resolve with the settled value; store targets resolve
+  with the store node passed (reads through it are fresh after the await).
+- A failed re-ask rejects with the error (inside an action's generator,
+  `yield refresh(x)` throws back at the yield point and the action reverts
+  like any other failure).
+- Semantics are quiescence, not flight identity: if another refresh (or
+  any invalidation) supersedes this one mid-flight, the promise waits for
+  — and delivers — whatever finally lands.
+- Inside an action, truth landing into the held transaction is staged;
+  the promise still settles then (matching `resolve()`/`until()`, #2930)
+  and delivers the staged value — the caller's own optimistic override is
+  never the delivered value.
+- The re-ask itself stays verdict-quiet exactly as before: `isPending`
+  does not flip for a bare refresh (pair with `affects()` for a visible
+  pending window).
 
 ## Import
 
@@ -38,14 +56,19 @@ import { refresh } from "solid-js";
 ## Type signature
 
 ```ts
-function refresh<T>(target: Refreshable<T>): void;
+function refresh<T>(
+	target: Refreshable<T>
+): Promise<T extends (...args: any) => infer V ? V : T>;
 ```
 
 ## Examples
 
 ```ts
 const user = createMemo(async () => fetch(`/users/${id()}`).then(r => r.json()));
 
-// Re-fetch on demand
-<button onClick={() => refresh(user)}>Reload</button>
+// Fire-and-forget re-fetch
+<button onClick={() => refresh(user)}>Reload</button>;
+
+// Imperative settle point
+const fresh = await refresh(user);
 ```