Merge pull request storybookjs#35154 from storybookjs/jeppe-cursor/cd8d79b3

Open Service: Load static query snapshots in browser builds

Author: JReinhold

code/.storybook/main.ts

@@ -14,6 +14,7 @@ const currentDirPath = dirname(currentFilePath);
 
 const componentsPath = join(currentDirPath, '../core/src/components/index.ts');
 const managerApiPath = join(currentDirPath, '../core/src/manager-api/index.mock.ts');
+const previewApiPath = join(currentDirPath, '../core/src/preview-api/index.ts');
 const themingCreatePath = join(currentDirPath, '../core/src/theming/create.ts');
 const themingPath = join(currentDirPath, '../core/src/theming/index.ts');
 const imageContextPath = join(currentDirPath, '../frameworks/nextjs/src/image-context.ts');
@@ -173,12 +174,14 @@ const config = defineMain({
             ? {
                 'storybook/internal/components': componentsPath,
                 'storybook/manager-api': managerApiPath,
+                'storybook/preview-api': previewApiPath,
                 'storybook/theming/create': themingCreatePath,
                 'storybook/theming': themingPath,
                 'sb-original/image-context': imageContextPath,
               }
             : {
                 'storybook/manager-api': managerApiPath,
+                'storybook/preview-api': previewApiPath,
               },
       },
       plugins: [react()],

code/.storybook/preview.tsx

@@ -54,7 +54,20 @@ sb.mock(import('uuid'));
 import '../core/src/shared/open-service/sync-test/preview.ts';
 
 const { document } = global;
-globalThis.CONFIG_TYPE = 'DEVELOPMENT';
+
+// The internal Storybook's manager stories (sidebar context menu, onboarding guide, …) demonstrate
+// DEVELOPMENT-only UI, so they must render as if in development even though this Storybook is itself
+// built and served statically (`yarn storybook:ui`, Chromatic, Vitest portable stories). In Vitest the
+// preview builder never injects CONFIG_TYPE (it is undefined); in Chromatic it is injected as PRODUCTION.
+// The one exception is the open-service static-load E2E, which serves a plain production build to
+// exercise the real static-loading path — there CONFIG_TYPE is PRODUCTION and Chromatic is not driving
+// the browser, so we leave the injected value untouched.
+// TODO(open-service): #29743 added an unconditional `CONFIG_TYPE = 'DEVELOPMENT'` here with no rationale.
+// Ask Norbert why the internal Storybook needs to force development mode rather than the stories opting
+// in per-story; if it can be removed, this gate should go with it.
+if (isChromatic() || globalThis.CONFIG_TYPE !== 'PRODUCTION') {
+  globalThis.CONFIG_TYPE = 'DEVELOPMENT';
+}
 
 const ThemeBlock = styled.div<{ side: 'left' | 'right'; layout: string }>(
   {

code/core/src/manager-errors.ts

@@ -19,6 +19,7 @@ export enum Category {
   MANAGER_ROUTER = 'MANAGER_ROUTER',
   MANAGER_THEMING = 'MANAGER_THEMING',
   MANAGER_UNIVERSAL_STORE = 'MANAGER_UNIVERSAL-STORE',
+  MANAGER_OPEN_SERVICE = 'MANAGER_OPEN-SERVICE',
 }
 
 export class ProviderDoesNotExtendBaseProviderError extends StorybookError {
@@ -78,3 +79,46 @@ export class UniversalStoreFollowerTimeoutError extends StorybookError {
     });
   }
 }
+
+export class OpenServiceStaticSnapshotLoadError extends StorybookError {
+  constructor(
+    public data: {
+      serviceId: string;
+      queryName: string;
+      input: unknown;
+      logicalPath: string;
+      url: string;
+      cause: unknown;
+      status?: number;
+      statusText?: string;
+    }
+  ) {
+    super({
+      name: 'OpenServiceStaticSnapshotLoadError',
+      category: Category.MANAGER_OPEN_SERVICE,
+      code: 1,
+      message: `Failed to load open-service static snapshot "${data.logicalPath}" from "${data.url}" for "${data.serviceId}.${data.queryName}".`,
+      cause: data.cause,
+    });
+  }
+}
+
+export class OpenServiceStaticSnapshotInvalidError extends StorybookError {
+  constructor(
+    public data: {
+      serviceId: string;
+      queryName: string;
+      input: unknown;
+      logicalPath: string;
+      url: string;
+      received: unknown;
+    }
+  ) {
+    super({
+      name: 'OpenServiceStaticSnapshotInvalidError',
+      category: Category.MANAGER_OPEN_SERVICE,
+      code: 2,
+      message: `Open-service static snapshot "${data.logicalPath}" from "${data.url}" for "${data.serviceId}.${data.queryName}" must be a plain object.`,
+    });
+  }
+}

code/core/src/manager/globals/exports.ts

@@ -659,6 +659,8 @@ export default {
   ],
   'storybook/internal/manager-errors': [
     'Category',
+    'OpenServiceStaticSnapshotInvalidError',
+    'OpenServiceStaticSnapshotLoadError',
     'ProviderDoesNotExtendBaseProviderError',
     'StatusTypeIdMismatchError',
     'UncaughtManagerError',

code/core/src/server-errors.ts

@@ -276,6 +276,17 @@ export class OpenServiceRemoteCommandDisconnectedError extends StorybookError {
   }
 }
 
+export class OpenServiceRemoteCommandUnhandledError extends StorybookError {
+  constructor(public data: { serviceId: ServiceId; commandName: string }) {
+    super({
+      name: 'OpenServiceRemoteCommandUnhandledError',
+      category: Category.CORE_COMMON,
+      code: 15,
+      message: `No runtime acknowledged remote command "${data.serviceId}.${data.commandName}"; its handler is not implemented in any connected runtime.`,
+    });
+  }
+}
+
 export class WebpackMissingStatsError extends StorybookError {
   constructor() {
     super({

code/core/src/shared/open-service/README.md

@@ -69,7 +69,7 @@ Internal tests and implementation code may import from the individual modules di
 - [service-error-serialization.ts](./service-error-serialization.ts): transport-safe (de)serialization of thrown errors and their `cause` chains, used by remote command replies
 - [channel-slot.ts](../../channels/channel-slot.ts): `getChannel` / `setChannel` — the shared channel install surface
 - [service-transport.ts](./service-transport.ts): shared channel transport — wraps commands to broadcast, wires the sync-start initialization + patch listeners (hub or leaf), and runs the remote-command-execution protocol
-- [service-sync.ts](./service-sync.ts): last-write-wins ordering, the `deepReconcile` structural merge, and the per-service snapshot reconciler
+- [service-sync.ts](./service-sync.ts): last-write-wins ordering, `applyStatePatch` structural state application, and the per-service snapshot reconciler
 - [use-service-query.ts](./use-service-query.ts): `useServiceQuery` React hook backed by `useSyncExternalStore`
 - [use-service-command.ts](./use-service-command.ts): `useServiceCommand` React hook returning a stable command reference
 - [fixtures.ts](./fixtures.ts): scenario fixtures used by the test suite
@@ -338,10 +338,10 @@ an arbitrary style choice:
 - **Reactivity.** State is wrapped in a `deepSignal` proxy for fine-grained per-field tracking, and
   `deepSignal` throws (`"this object can't be observed"`) on scalars, `null`, and `undefined` — there
   are no fields to track on a scalar.
-- **Sync.** Cross-peer reconciliation (`deepReconcile` in [service-sync.ts](./service-sync.ts)) merges
+- **Sync.** Cross-peer reconciliation (`applyStatePatch` in [service-sync.ts](./service-sync.ts)) merges
   state by walking object keys; it has no concept of replacing a whole scalar.
 
-Arrays are a special case: `deepSignal` *can* observe them, but `deepReconcile` replaces arrays
+Arrays are a special case: `deepSignal` *can* observe them, but `applyStatePatch` replaces arrays
 wholesale rather than merging by key, so a **top-level** array state would silently fail to sync
 between peers. They are therefore rejected too. Wrap collections in a field instead:
 
@@ -422,7 +422,7 @@ If multiple tasks resolve to the same path, their states are deep-merged.
 
 `writeOpenServiceStaticFiles(outputDir)` then writes those logical paths underneath `<outputDir>/services`, converting slash-separated logical keys into native filesystem paths for the current operating system.
 
-These snapshots are currently only a build artifact for the server-side static build flow. This slice does not implement a separate runtime mode that consumes prebuilt snapshot stores instead of running `load` normally.
+In a static Storybook build (`CONFIG_TYPE === 'PRODUCTION'`), manager and preview runtimes pass a browser static loader into `registerService`. For every query that declares `staticPath`, the runtime swaps the authored `load` hook for a fetch of `./services/<serviceId>/<staticPath>` relative to the served HTML root (the same convention as `./index.json`), then applies the JSON snapshot via `applyStatePatch(..., { preserveMissingKeys: true })` so snapshots for one query input do not delete state populated by other inputs. Development mode keeps running `load` normally against the dev server.
 
 Static path rules:
 
@@ -489,9 +489,9 @@ Every channel event carries the emitter's `clientId` (generated per `registerSer
 
 Incoming state (from sync-start-reply or patches) is applied via `serviceRuntime.commandSelf.setState(...)` directly — not through the wrapped commands — so no broadcast is triggered for received state.
 
-### `deepReconcile`
+### `applyStatePatch`
 
-Rather than replacing the entire state object on each patch (which would invalidate all signal subscriptions), `deepReconcile` (in [service-sync.ts](./service-sync.ts)) recursively merges plain-object values in place: arrays and primitives are replaced directly, keys absent from the snapshot are deleted so deletions propagate, and `__proto__`/`constructor`/`prototype` are skipped to block prototype pollution. This keeps fine-grained subscriptions on unaffected nested fields from firing spuriously.
+Rather than replacing the entire state object on each patch (which would invalidate all signal subscriptions), `applyStatePatch` (in [service-sync.ts](./service-sync.ts)) recursively merges plain-object values in place: arrays and primitives are replaced directly, `__proto__`/`constructor`/`prototype` are skipped to block prototype pollution, and `preserveMissingKeys` controls whether missing keys are deleted. Cross-peer sync passes `false` so deletions propagate from full snapshots; static JSON loading passes `true` because each static file is a partial snapshot. This keeps fine-grained subscriptions on unaffected nested fields from firing spuriously.
 
 ### State sync sequence
 
@@ -635,9 +635,11 @@ The manager is connected to both the dev server and the preview, so it can invok
 in either; but a preview cannot directly invoke a server-only command, and vice versa — route such
 calls through the manager, or implement the command on a directly-connected peer.
 
-There is **no timeout**. Invoking a command that no reachable peer implements leaves the promise
-pending forever, until the service is unregistered — `disconnect` rejects every outstanding call with
-`OpenServiceRemoteCommandDisconnectedError`.
+If no peer emits `services:command-ack` within a short window, the requester
+rejects with `OpenServiceRemoteCommandUnhandledError` — the common case in a static build when a
+query's `load` calls a server-only command. Once a peer acknowledges, the requester waits for
+`services:command-result` or `services:command-error` as before. Unregistering the service still
+rejects outstanding calls with `OpenServiceRemoteCommandDisconnectedError`.
 
 ## React Hooks
 

code/core/src/shared/open-service/manager.ts

@@ -20,6 +20,7 @@
  */
 
 import { getService, registerService as registerServiceCore } from './service-registry.ts';
+import { createBrowserStaticLoader } from './static-fetch.ts';
 import type {
   Commands,
   Queries,
@@ -48,5 +49,8 @@ export function registerService<
   definition: ServiceDefinition<TState, TQueries, TCommands>,
   registration?: ServiceRegistrationOptions<TState, TQueries, TCommands>
 ): ServiceInstance<TState, TQueries, TCommands> & ServiceRegistryApi {
-  return registerServiceCore(definition, registration, { relay: true });
+  return registerServiceCore(definition, registration, {
+    relay: true,
+    staticLoader: createBrowserStaticLoader(),
+  });
 }

code/core/src/shared/open-service/preview.ts

@@ -22,6 +22,7 @@
  */
 
 import { getService, registerService as registerServiceCore } from './service-registry.ts';
+import { createBrowserStaticLoader } from './static-fetch.ts';
 import type {
   Commands,
   Queries,
@@ -47,5 +48,7 @@ export function registerService<
   definition: ServiceDefinition<TState, TQueries, TCommands>,
   registration?: ServiceRegistrationOptions<TState, TQueries, TCommands>
 ): ServiceInstance<TState, TQueries, TCommands> & ServiceRegistryApi {
-  return registerServiceCore(definition, registration);
+  return registerServiceCore(definition, registration, {
+    staticLoader: createBrowserStaticLoader(),
+  });
 }

code/core/src/shared/open-service/service-channel.ts

@@ -89,8 +89,9 @@ export type CommandInvokePayload = v.InferOutput<typeof commandInvokeSchema>;
 /**
  * Emitted by an implementing peer the moment it accepts a `services:command-invoke`.
  *
- * Purely informational: it tells observers (and the requester) that at least one peer has picked
- * the call up. The requester still resolves/rejects only on the result/error reply.
+ * Requesters use this to detect that at least one peer will run the command; if no ack arrives
+ * within a short window, the request rejects as unhandled. The requester still resolves/rejects on
+ * the result/error reply once a peer has acknowledged.
  */
 export const commandAckSchema = v.object({
   serviceId: v.string(),

code/core/src/shared/open-service/service-command-transport.test.ts

@@ -27,6 +27,7 @@ import {
 } from './service-channel.ts';
 import { deserializeError } from './service-error-serialization.ts';
 import { clearRegistry, registerService, unregisterService } from './service-registry.ts';
+import { REMOTE_COMMAND_ACK_TIMEOUT_MS } from './service-transport.ts';
 import { createTestChannel, installTestChannel } from '../../channels/test-channel.ts';
 
 const remoteOnlyServiceDef = defineService({
@@ -88,6 +89,7 @@ function emittedCalls(channel: ReturnType<typeof createTestChannel>, event: stri
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   clearRegistry();
   installTestChannel(null);
 });
@@ -98,7 +100,6 @@ describe('remote command requester (no local handler)', () => {
     installTestChannel(channel);
 
     const service = registerService(remoteOnlyServiceDef);
-    // Never settled in this test; swallow the unregister rejection clearRegistry triggers in afterEach.
     service.commands.doThing({ value: 'hi' }).catch(() => {});
 
     const invokes = emittedCalls(channel, SERVICE_COMMAND_INVOKE);
@@ -110,6 +111,8 @@ describe('remote command requester (no local handler)', () => {
       callId: expect.any(String),
       clientId: expect.any(String),
     });
+
+    unregisterService(remoteOnlyServiceDef.id);
   });
 
   it('resolves with the result of the matching command-result reply', async () => {
@@ -214,6 +217,50 @@ describe('remote command requester (no local handler)', () => {
     await expect(promise).resolves.toBe('correct');
   });
 
+  it('rejects when no peer acknowledges the invoke within the timeout', async () => {
+    vi.useFakeTimers();
+
+    const channel = createTestChannel();
+    installTestChannel(channel);
+
+    const service = registerService(remoteOnlyServiceDef);
+    const promise = service.commands.doThing({ value: 'hi' });
+    const assertion = expect(promise).rejects.toThrow(
+      'No runtime acknowledged remote command "internal-fixture/remote-only-command.doThing"; its handler is not implemented in any connected runtime.'
+    );
+
+    await vi.advanceTimersByTimeAsync(REMOTE_COMMAND_ACK_TIMEOUT_MS);
+    await assertion;
+  });
+
+  it('does not reject after a peer acknowledges the invoke', async () => {
+    vi.useFakeTimers();
+
+    const channel = createTestChannel();
+    installTestChannel(channel);
+
+    const service = registerService(remoteOnlyServiceDef);
+    const promise = service.commands.doThing({ value: 'hi' });
+
+    const { callId } = emittedCalls(channel, SERVICE_COMMAND_INVOKE)[0][1] as CommandInvokePayload;
+    channel.emitExternal(SERVICE_COMMAND_ACK, {
+      serviceId: remoteOnlyServiceDef.id,
+      callId,
+      clientId: 'peer',
+    });
+
+    await vi.advanceTimersByTimeAsync(REMOTE_COMMAND_ACK_TIMEOUT_MS);
+
+    channel.emitExternal(SERVICE_COMMAND_RESULT, {
+      serviceId: remoteOnlyServiceDef.id,
+      callId,
+      result: 'done',
+      clientId: 'peer',
+    });
+
+    await expect(promise).resolves.toBe('done');
+  });
+
   it('rejects in-flight remote calls when the service is unregistered', async () => {
     const channel = createTestChannel();
     installTestChannel(channel);