@storystick/react 0.2.0-rc.2 → 0.2.0-rc.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PUBLIC-API.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @storystick/react API contract
2
2
 
3
- Install this candidate explicitly with `@storystick/react@0.2.0-rc.2` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
3
+ Install this candidate explicitly with `@storystick/react@0.2.0-rc.4` after registry bootstrap and publication. This repository alone does not make the candidate or beta channel available on npm.
4
4
 
5
- Version 0.2.0-rc.2, cohort `sdk-0.2.0-rc.2`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
5
+ Version 0.2.0-rc.4, cohort `sdk-0.2.0-rc.4`. ESM distribution; no CommonJS or universal Edge compatibility is promised.
6
6
 
7
7
  This package is a product integration facade. Reserved contracts are required between SDK packages and must be upgraded with the same cohort. Their public export paths do not promise independent stability.
8
8
 
@@ -32,7 +32,7 @@ This package is a product integration facade. Reserved contracts are required be
32
32
  | `./internal/preview-panel-state` | Reserved SDK contract |
33
33
  | `./internal/preview-host` | Reserved SDK contract |
34
34
 
35
- The qualified toolchain is Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
35
+ Supported consumer Node versions: `^22.13.0 || ^24.19.0`. The release build toolchain remains Node 24.19.0 and pnpm 9.15.9. Next uses App Router 15.5.28, Sharp 0.35.5 and React/React DOM 19.2.8; Astro uses 7.4.4 with the Node adapter 11.1.9. Browser delivery is verified by bundling; hosted Preview activation and cross-browser behavior require the staging manual check. Source/CLI are Node tools, server entries belong on the server, and browser entries must never receive a server API key.
36
36
 
37
37
  Use a generated Query V2 definition. A missing document/singleton returns null, an empty collection returns an empty array, and fetch throws on blocked/degraded execution. Execute exposes the complete result envelope. RSC metadata must remain plain JSON data; request authority must not be stored in shared module state.
38
38
 
package/README.md CHANGED
@@ -223,5 +223,7 @@ do not need to model Content Plane convergence states.
223
223
  ## Candidate distribution contract
224
224
 
225
225
  See [PUBLIC-API.md](./PUBLIC-API.md) for supported entries, reserved SDK contracts,
226
- the qualified runtime matrix and the candidate cohort. Upgrade Storystick
227
- packages together.
226
+ the qualified runtime matrix and the candidate cohort. Keep shared contracts
227
+ compatible. Use the [release guide](../../release/README.md) to select the
228
+ packages and consumers that need an update; an independent adapter fix does
229
+ not require republishing every package.
package/dist/.source-hash CHANGED
@@ -1 +1 @@
1
- cd953980c3d53fab939eb42eb894e0f0f2863a9790a73d70c830db6be353a266
1
+ afb41487b51bb21415f1f3721af3ea1658b8a47b7146978f3c073287178e0049
@@ -1,7 +1,9 @@
1
- import { StorystickError } from '@storystick/client';
1
+ import { StorystickError, type QuerySnapshot } from '@storystick/client';
2
2
  import type { CompiledQueryV2, QueryPageInfo, QueryResult } from '@storystick/types/query-contract';
3
- export interface UseQueryOptions {
3
+ export interface UseQueryOptions<TData = unknown, TPageInfo extends QueryPageInfo | null = QueryPageInfo | null> {
4
4
  readonly enabled?: boolean;
5
+ /** An SSR render seed from preloadQuery. Browser reads still obtain their own authority. */
6
+ readonly initialData?: QuerySnapshot<TData, TPageInfo>;
5
7
  }
6
8
  interface ExecutableQuery<TData, TPageInfo extends QueryPageInfo | null> {
7
9
  compile(): {
@@ -33,5 +35,5 @@ export type UseQueryResult<TData, TPageInfo extends QueryPageInfo | null> = (Use
33
35
  readonly status: 'error';
34
36
  readonly error: StorystickError;
35
37
  });
36
- export declare function useQuery<TData, TPageInfo extends QueryPageInfo | null>(executableQuery: ExecutableQuery<TData, TPageInfo>, options?: UseQueryOptions): UseQueryResult<TData, TPageInfo>;
38
+ export declare function useQuery<TData, TPageInfo extends QueryPageInfo | null>(executableQuery: ExecutableQuery<TData, TPageInfo>, options?: UseQueryOptions<TData, TPageInfo>): UseQueryResult<TData, TPageInfo>;
37
39
  export {};
@@ -1,7 +1,7 @@
1
1
  'use client';
2
- import { useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from 'react';
2
+ import { useEffect, useLayoutEffect, useMemo, useState, useSyncExternalStore } from 'react';
3
3
  import { QueryExecutionError, StorystickError } from '@storystick/client';
4
- import { prepareContentValues, rawContentValues, bindClientSchemaToAuthority, clientMatchesPreviewAuthority, getExecutableQueryDescriptor, getInternalClientRuntime, getPreviewQueryReceiptId, } from '@storystick/client/internal';
4
+ import { prepareContentValues, rawContentValues, readQuerySnapshot, bindClientSchemaToAuthority, clientMatchesPreviewAuthority, getExecutableQueryDescriptor, getInternalClientRuntime, getPreviewQueryReceiptId, } from '@storystick/client/internal';
5
5
  import { getPreviewAuthority, subscribePreviewAuthority, } from '@storystick/preview/runtime/authority';
6
6
  import { getQueryPreviewState, subscribeQueryPreview, loadQueryPreview } from './query-preview-loader.js';
7
7
  import { createRefCountedObserver, convergeQueryProjection, previewQueryHasConfirmedCoverage, previewQueryIsAwaitingTargetedProjection, queryCacheKey, registerPreviewQueryReceipt, subscribeRefCounted, } from './query-cache.js';
@@ -34,8 +34,18 @@ export function useQuery(executableQuery, options = {}) {
34
34
  if (!client || typeof client.projectId !== 'string') {
35
35
  throw new TypeError('storystick/QUERY_INVALID: The executable query is not owned by a Client.');
36
36
  }
37
+ const initialResult = useMemo(() => readQuerySnapshot(options.initialData, client, compiled.canonical), [options.initialData, client, compiled.canonical]);
38
+ const initialSnapshot = useMemo(() => enabled && initialResult ? {
39
+ ...SERVER_PENDING, status: 'success', data: initialResult.data,
40
+ pageInfo: initialResult.pageInfo,
41
+ } : SERVER_PENDING, [enabled, initialResult]);
37
42
  const previewState = useSyncExternalStore(subscribePreviewAuthority, getPreviewAuthority, getPreviewAuthority);
38
43
  const previewModules = useSyncExternalStore(subscribeQueryPreview, getQueryPreviewState, getQueryPreviewState);
44
+ const [hasObservedSession, setHasObservedSession] = useState(false);
45
+ useEffect(() => {
46
+ if (previewState.sessionId !== null)
47
+ setHasObservedSession(true);
48
+ }, [previewState.sessionId]);
39
49
  useEffect(() => {
40
50
  if (enabled && previewState.sessionId)
41
51
  void loadQueryPreview();
@@ -44,7 +54,17 @@ export function useQuery(executableQuery, options = {}) {
44
54
  previewAuthorityMatchesState(previewState.httpClient, client, previewState)
45
55
  ? previewState.httpClient
46
56
  : null;
47
- const hasExecutionAuthority = previewState.sessionId === null || previewAuthority !== null;
57
+ // An authenticated server seed must never trigger a public read while the
58
+ // Preview runtime is starting or changing its authority.
59
+ const hasExecutionAuthority = previewAuthority !== null ||
60
+ (previewState.sessionId === null && !options.initialData?.preview);
61
+ const seedContext = options.initialData?.preview;
62
+ const seedIsCurrent = seedContext
63
+ ? (previewState.sessionId === null && !hasObservedSession) || (previewState.readContext?.contextId === seedContext.contextId &&
64
+ previewState.readContext?.revision === seedContext.revision)
65
+ : previewState.sessionId === null;
66
+ const visibleInitial = seedIsCurrent ? initialSnapshot : SERVER_PENDING;
67
+ const currentInitialResult = seedIsCurrent ? initialResult : undefined;
48
68
  const executionClient = useMemo(() => previewAuthority
49
69
  ? bindClientSchemaToAuthority(previewAuthority, client.schema)
50
70
  : client, [client, previewAuthority]);
@@ -55,7 +75,7 @@ export function useQuery(executableQuery, options = {}) {
55
75
  const keyIdentity = JSON.stringify(key);
56
76
  const store = useMemo(() => {
57
77
  if (typeof window === 'undefined' || !enabled || !hasExecutionAuthority || (previewAuthority && !previewModules.runtime))
58
- return disabledStore();
78
+ return disabledStore(visibleInitial);
59
79
  return deferredStore(() => {
60
80
  const observer = createRefCountedObserver(executionClient, {
61
81
  queryKey: key,
@@ -70,10 +90,13 @@ export function useQuery(executableQuery, options = {}) {
70
90
  return getInternalClientRuntime(executionClient).executionHost.executeCompiled(compiled.query, compiled.canonical, { signal });
71
91
  },
72
92
  enabled: true,
93
+ initialData: currentInitialResult,
94
+ // A seed is not a fresh browser read and carries no query receipt.
95
+ initialDataUpdatedAt: 0,
73
96
  retry: false,
74
97
  staleTime: Infinity,
75
98
  gcTime: 5 * 60 * 1_000,
76
- refetchOnMount: false,
99
+ refetchOnMount: query => query.state.dataUpdatedAt === 0 ? 'always' : false,
77
100
  refetchOnWindowFocus: false,
78
101
  refetchOnReconnect: false,
79
102
  });
@@ -173,10 +196,10 @@ export function useQuery(executableQuery, options = {}) {
173
196
  snapshot,
174
197
  paintProjection: () => paintProjection,
175
198
  };
176
- });
199
+ }, visibleInitial);
177
200
  // The canonical identity deliberately replaces the ephemeral inline builder identity.
178
- }, [client, enabled, executionClient, hasExecutionAuthority, keyIdentity, previewModules]);
179
- const result = useSyncExternalStore(store.subscribe, store.snapshot, () => SERVER_PENDING);
201
+ }, [client, enabled, executionClient, hasExecutionAuthority, keyIdentity, previewModules, seedIsCurrent]);
202
+ const result = useSyncExternalStore(store.subscribe, store.snapshot, () => initialSnapshot);
180
203
  const paintProjection = store.paintProjection?.() ?? null;
181
204
  useLayoutEffect(() => {
182
205
  if (paintProjection?.editorMutationAt === undefined ||
@@ -240,8 +263,7 @@ function executionAuthorityIsCurrent(previewAuthority, owner) {
240
263
  return previewAuthority === null;
241
264
  return previewAuthority !== null && previewAuthorityMatchesState(previewAuthority, owner, current);
242
265
  }
243
- function disabledStore() {
244
- const snapshot = SERVER_PENDING;
266
+ function disabledStore(snapshot = SERVER_PENDING) {
245
267
  return {
246
268
  subscribe: () => () => { },
247
269
  snapshot: () => snapshot,
@@ -291,7 +313,7 @@ function toPublicSnapshot(current, observer, generationError, visibleQueryResult
291
313
  error: null, isFetching: current.isFetching, refetch,
292
314
  };
293
315
  }
294
- function deferredStore(create) {
316
+ function deferredStore(create, initialSnapshot = SERVER_PENDING) {
295
317
  let active = null;
296
318
  let subscribers = 0;
297
319
  return {
@@ -302,7 +324,7 @@ function deferredStore(create) {
302
324
  return () => { stop(); if (--subscribers === 0)
303
325
  active = null; };
304
326
  },
305
- snapshot: () => active?.snapshot() ?? SERVER_PENDING,
327
+ snapshot: () => active?.snapshot() ?? initialSnapshot,
306
328
  paintProjection: () => active?.paintProjection() ?? null,
307
329
  };
308
330
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@storystick/react",
3
- "version": "0.2.0-rc.2",
3
+ "version": "0.2.0-rc.4",
4
4
  "license": "FSL-1.1-MIT",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -116,10 +116,10 @@
116
116
  "dependencies": {
117
117
  "@tanstack/query-core": "5.101.4",
118
118
  "@base-ui/react": "1.3.0",
119
- "@storystick/client": "0.2.0-rc.2",
120
- "@storystick/media": "0.2.0-rc.2",
121
- "@storystick/preview": "0.2.0-rc.2",
122
- "@storystick/types": "0.1.0-rc.2"
119
+ "@storystick/client": "0.2.0-rc.4",
120
+ "@storystick/types": "0.1.0-rc.3",
121
+ "@storystick/preview": "0.2.0-rc.4",
122
+ "@storystick/media": "0.2.0-rc.3"
123
123
  },
124
124
  "peerDependencies": {
125
125
  "react": "^19.2.8",
@@ -137,7 +137,7 @@
137
137
  "vitest": "^3.1.1"
138
138
  },
139
139
  "engines": {
140
- "node": ">=24.19.0 <25"
140
+ "node": "^22.13.0 || ^24.19.0"
141
141
  },
142
142
  "repository": {
143
143
  "type": "git",