@sanity/workbench 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/system/service.machine.ts

@@ -0,0 +1,207 @@
+import { assign, fromCallback, setup } from "xstate";
+
+import { logger } from "../core/log";
+import { type FederationInstance } from "./module-federation";
+import {
+  remoteLogic,
+  type RemoteError,
+  type ServiceLoaderModule,
+} from "./remote.machine";
+
+/**
+ * @internal
+ */
+export interface ServiceInput {
+  /** Stable child key, `${appId}:${serviceName}`. */
+  key: string;
+  appId: string;
+  serviceName: string;
+  /** The app's `mf-manifest.json` URL — the federation remote entry. */
+  entry: string;
+  instance: FederationInstance;
+}
+
+type ServiceContext = ServiceInput & {
+  /** Resolved worker-bundle URL, absolute on the app origin. */
+  workerUrl: string | null;
+};
+
+/** Federation expose segment a service's loader lives under: `services/<name>`. */
+const SERVICES_MODULE = "services";
+
+/**
+ * Run the worker. `new Worker(appOriginUrl)` is cross-origin-blocked, and the
+ * dev worker isn't self-contained (its root-relative imports would resolve
+ * against the wrong origin from a blob). So bootstrap a same-origin worker that
+ * dynamically `import()`s the app-origin URL: the worker module then resolves
+ * its own imports against the app origin, in dev and build alike. Crashes, a
+ * failed load, and the worker's `console.*` (bridged by the wrapper) are
+ * surfaced through the host logger (the host owns logging; a worker's own
+ * console isn't visible in the page DevTools anyway). Cleanup disposes, then
+ * terminates.
+ */
+const runWorker = fromCallback<
+  { type: string },
+  { key: string; serviceName: string; workerUrl: string }
+>(({ input }) => {
+  let worker: Worker | undefined;
+  let blobUrl: string | undefined;
+
+  try {
+    // A same-origin module worker whose only job is to load the real worker
+    // from the app origin, so that worker's imports resolve there too.
+    const bootstrap = `import(${JSON.stringify(input.workerUrl)})`;
+    blobUrl = URL.createObjectURL(
+      new Blob([bootstrap], { type: "text/javascript" }),
+    );
+    worker = new Worker(blobUrl, { type: "module" });
+
+    worker.addEventListener("message", (event: MessageEvent) => {
+      if (event.data?.kind === "workbench.worker.error") {
+        logger.error(
+          `Service "${input.key}" worker error`,
+          event.data.payload?.message,
+        );
+      } else if (event.data?.kind === "workbench.worker.log") {
+        // Re-emit the worker's `console.*` (bridged by the wrapper) through the
+        // host logger, prefixed with the service name so it shows in the page
+        // console.
+        const { level, message } = event.data.payload ?? {};
+        const emit: Record<string, (message: string) => void> = {
+          warn: logger.warn,
+          error: logger.error,
+          debug: logger.debug,
+        };
+        (emit[level] ?? logger.info)(
+          `[service:${input.serviceName}] ${message ?? ""}`,
+        );
+      }
+    });
+
+    // A module-load failure (or any uncaught worker error) fires here on the
+    // host side — surface it instead of failing silently.
+    worker.addEventListener("error", (event: ErrorEvent) => {
+      logger.error(
+        `Service "${input.key}" worker error: ${event.message || String(event)}`,
+      );
+    });
+  } catch (error) {
+    logger.error(`Service "${input.key}" failed to start its worker`, error);
+  }
+
+  return () => {
+    try {
+      worker?.postMessage({ kind: "workbench.worker.terminate" });
+    } finally {
+      worker?.terminate();
+      if (blobUrl) URL.revokeObjectURL(blobUrl);
+    }
+  };
+});
+
+/**
+ * Lifecycle machine for a single background service worker.
+ *
+ * Spawned by the {@link servicesLogic} supervisor, one per `(app, service)`.
+ * `loading` loads the worker's loader module through the shared
+ * {@link remoteLogic} lifecycle — the same machine every interface (panel, app,
+ * worker) loads through — and reads the bundle URL off it. A worker isn't a
+ * render module, so it's never handed to an island; `running` bootstraps it as
+ * a Web Worker from that URL.
+ *
+ * @internal
+ */
+export const serviceLogic = setup({
+  types: {
+    input: {} as ServiceInput,
+    context: {} as ServiceContext,
+    tags: {} as "loading" | "running" | "failed",
+  },
+  actors: {
+    loadInterface: remoteLogic,
+    runWorker,
+  },
+}).createMachine({
+  id: "service",
+  initial: "loading",
+  context: ({ input }) => ({ ...input, workerUrl: null }),
+  // The invoked loader `sendParent`s a `remote.settled` on settle; this machine
+  // reacts via `onSnapshot` instead, so the event is a no-op here.
+  on: { "remote.settled": {} },
+  states: {
+    loading: {
+      tags: ["loading"],
+      invoke: {
+        id: "loader",
+        src: "loadInterface",
+        input: ({ context }) => ({
+          moduleId: `${context.appId}/${SERVICES_MODULE}/${context.serviceName}`,
+          entry: context.entry,
+          instance: context.instance,
+        }),
+        onSnapshot: [
+          {
+            // Loaded and exposing a bundle URL → run it.
+            guard: ({ event }) => {
+              const module = event.snapshot.context
+                .module as ServiceLoaderModule | null;
+              return (
+                event.snapshot.hasTag("ready") &&
+                typeof module?.url === "string"
+              );
+            },
+            target: "running",
+            actions: assign({
+              workerUrl: ({ context, event }) => {
+                const module = event.snapshot.context
+                  .module as ServiceLoaderModule;
+                // The URL is root-relative to the app; resolve it absolute
+                // against the app origin since the loader runs in the host page.
+                return new URL(module.url, new URL(context.entry).origin).href;
+              },
+            }),
+          },
+          {
+            // Load failed, or loaded without a usable URL → no worker.
+            guard: ({ event }) => {
+              const module = event.snapshot.context
+                .module as ServiceLoaderModule | null;
+              return (
+                event.snapshot.hasTag("failed") ||
+                (event.snapshot.hasTag("ready") &&
+                  typeof module?.url !== "string")
+              );
+            },
+            target: "error",
+            // A worker has no UI surface (unlike a view's error boundary), so a
+            // failed load would otherwise be silent — log it through the host.
+            actions: ({ context, event }) => {
+              const cause = (event.snapshot.context.error as RemoteError | null)
+                ?.message;
+              logger.error(
+                `Service "${context.key}" failed to load its worker${
+                  cause ? `: ${cause}` : ""
+                }`,
+              );
+            },
+          },
+        ],
+      },
+    },
+    running: {
+      tags: ["running"],
+      invoke: {
+        src: "runWorker",
+        input: ({ context }) => ({
+          key: context.key,
+          serviceName: context.serviceName,
+          // `workerUrl` is set on entry to `running` from `loading`'s output.
+          workerUrl: context.workerUrl!,
+        }),
+      },
+    },
+    error: {
+      tags: ["failed"],
+    },
+  },
+});

package/src/system/services.machine.ts

@@ -0,0 +1,120 @@
+import { type ActorRefFrom, enqueueActions, setup } from "xstate";
+
+import { type FederationInstance } from "./module-federation";
+import { serviceLogic } from "./service.machine";
+
+/** The shared federation instance, supplied by the root machine. */
+type ServicesInput = {
+  instance: FederationInstance;
+};
+
+type ServicesContext = {
+  instance: FederationInstance;
+  children: Map<string, ActorRefFrom<typeof serviceLogic>>;
+};
+
+/**
+ * The full set of background services the workbench should currently be
+ * running, re-sent whenever the application list — or any app's declared
+ * interfaces — changes. The supervisor reconciles its children against it.
+ */
+type ServicesEvent = {
+  type: "services.sync";
+  services: ReadonlyArray<{
+    appId: string;
+    serviceName: string;
+    entry: string;
+  }>;
+};
+
+/** Stable child key for a service: `${appId}:${serviceName}`. */
+function serviceKey(appId: string, serviceName: string): string {
+  return `${appId}:${serviceName}`;
+}
+
+/**
+ * Supervisor machine for background service workers.
+ *
+ * Uses the shared {@link FederationInstance} (supplied by the root machine and
+ * shared with `remotes`, so an app's remote is registered once for both its
+ * views and its workers) and spawns one {@link serviceLogic} child per
+ * `(app, service)`. Invoked at the root of the OS machine for inspector
+ * visibility — boot does not gate on it.
+ *
+ * On every `services.sync` it reconciles its children against the desired set:
+ * a newly-declared worker is spawned, and a worker whose declaration was
+ * removed (e.g. deleted from `sanity.cli.ts` during dev — FR-024) is stopped,
+ * which disposes its `runWorker` callback and terminates the Web Worker. A
+ * service `src` edit still triggers a Vite full page reload (workers have no
+ * HMR boundary), which reboots the workbench and respawns with the new code.
+ *
+ * @internal
+ */
+export const servicesLogic = setup({
+  types: {
+    input: {} as ServicesInput,
+    context: {} as ServicesContext,
+    events: {} as ServicesEvent,
+  },
+  actors: {
+    service: serviceLogic,
+  },
+  actions: {
+    /**
+     * Reconcile the running workers against the desired set: spawn the ones not
+     * yet running, stop (and forget) the ones no longer declared.
+     */
+    syncServices: enqueueActions(({ context, event, enqueue }) => {
+      const desired = new Map(
+        event.services.map((service) => [
+          serviceKey(service.appId, service.serviceName),
+          service,
+        ]),
+      );
+
+      // Stop + forget workers whose declaration was removed. Stopping the child
+      // disposes its `runWorker` callback, which terminates the Web Worker.
+      for (const [key, ref] of context.children) {
+        if (!desired.has(key)) enqueue.stopChild(ref);
+      }
+
+      enqueue.assign({
+        children: ({ context: ctx, spawn }) => {
+          const next = new Map<string, ActorRefFrom<typeof serviceLogic>>();
+          // Keep the children still declared.
+          for (const [key, ref] of ctx.children) {
+            if (desired.has(key)) next.set(key, ref);
+          }
+          // Spawn the newly-declared ones.
+          for (const [key, service] of desired) {
+            if (next.has(key)) continue;
+            next.set(
+              key,
+              spawn("service", {
+                id: key,
+                systemId: `services.${key}`,
+                input: {
+                  key,
+                  appId: service.appId,
+                  serviceName: service.serviceName,
+                  entry: service.entry,
+                  instance: ctx.instance,
+                },
+              }),
+            );
+          }
+          return next;
+        },
+      });
+    }),
+  },
+}).createMachine({
+  id: "services",
+  context: ({ input }) => ({
+    instance: input.instance,
+    children: new Map(),
+  }),
+  on: {
+    "services.sync": { actions: "syncServices" },
+  },
+});

package/src/system/system-preferences.machine.ts

@@ -0,0 +1,215 @@
+import { assign, fromCallback, sendTo, setup } from "xstate";
+
+type ColorScheme = "light" | "dark";
+
+type ColorSchemePreference = "system" | ColorScheme;
+
+/**
+ * The system-preferences machine's context. Consumers read fields directly
+ * (e.g. via `useSelector`) rather than going through a resolver utility —
+ * the action handlers keep `colorScheme` in sync with `preferredColorScheme`
+ * and `osColorScheme`.
+ *
+ * Note: `colorScheme` is intentionally stored as derived state in context so
+ * consumers can read the resolved value directly without a utility. The
+ * action handlers below are the single source of truth for the resolution.
+ * @public
+ */
+export type SystemPreferencesContext = {
+  /** User's color scheme choice; `system` defers to the OS preference. */
+  preferredColorScheme: ColorSchemePreference;
+  /** Last reported OS color scheme. Used to resolve `colorScheme` when the
+   * preference is `system`. */
+  osColorScheme: ColorScheme;
+  /** Resolved color scheme — what the UI should render. Recomputed by the
+   * action handlers whenever an input changes. */
+  colorScheme: ColorScheme;
+};
+
+const DEFAULT_PREFERRED_COLOR_SCHEME: ColorSchemePreference = "system";
+const DEFAULT_OS_COLOR_SCHEME: ColorScheme = "light";
+
+/**
+ * Events the system-preferences machine accepts. Both originate from the
+ * host's adapter — `preferredColorScheme.set` is also forwarded back to it
+ * so it can persist the user's choice.
+ * @public
+ */
+export type SystemPreferencesEvent =
+  | {
+      type: "preferredColorScheme.set";
+      preferredColorScheme: ColorSchemePreference;
+    }
+  | {
+      type: "osColorScheme.set";
+      osColorScheme: ColorScheme;
+    };
+
+/**
+ * Adapter interface the host implements to give the system-preferences
+ * machine access to the user's environment (OS color scheme, persistent
+ * storage, cross-context change notifications).
+ *
+ * The package owns all orchestration — synchronous seeding, idempotent
+ * persistence, mapping cleared storage to `"system"`. The host's
+ * implementation is pure DOM/storage glue: read, write, subscribe.
+ * @public
+ */
+export type SystemPreferencesAdapter = {
+  /** Read the user's stored preference. `null` means "no preference set"
+   * (the machine treats this as `"system"`). */
+  getPreferredColorScheme: () => ColorSchemePreference | null;
+  /** Write the user's preference to persistent storage. */
+  persistPreferredColorScheme: (value: ColorSchemePreference) => void;
+  /** Subscribe to cross-context preference changes (e.g. another tab
+   * writing to the shared storage). The callback receives the new stored
+   * value (or `null` if it was cleared). Returns an unsubscribe function. */
+  subscribePreferredColorScheme: (
+    callback: (next: ColorSchemePreference | null) => void,
+  ) => () => void;
+  /** Read the current OS-detected color scheme. */
+  getOsColorScheme: () => ColorScheme;
+  /** Subscribe to OS color-scheme changes (e.g. user flipping dark mode).
+   * Returns an unsubscribe function. */
+  subscribeOsColorScheme: (callback: (next: ColorScheme) => void) => () => void;
+};
+
+const resolveColorScheme = (
+  preferred: ColorSchemePreference,
+  osColorScheme: ColorScheme,
+): ColorScheme => (preferred === "system" ? osColorScheme : preferred);
+
+// Internal bridge actor — subscribes to the host's adapter for runtime
+// changes and persists user-driven preference changes when the parent
+// forwards them. No-op if the host didn't pass an adapter (SSR, tests).
+type AdapterBridgeReceiveEvent = Extract<
+  SystemPreferencesEvent,
+  { type: "preferredColorScheme.set" }
+>;
+
+const adapterBridgeLogic = fromCallback<
+  AdapterBridgeReceiveEvent,
+  SystemPreferencesAdapter | undefined,
+  SystemPreferencesEvent
+>(({ input: adapter, sendBack, receive }) => {
+  if (!adapter) return;
+
+  const unsubscribePreferredColorScheme = adapter.subscribePreferredColorScheme(
+    (next) => {
+      // Falls back to `"system"` so an external clear (another tab deleting
+      // the key) resets the preference rather than silently keeping the
+      // previous value.
+      sendBack({
+        type: "preferredColorScheme.set",
+        preferredColorScheme: next ?? "system",
+      });
+    },
+  );
+
+  const unsubscribeOs = adapter.subscribeOsColorScheme((next) => {
+    sendBack({ type: "osColorScheme.set", osColorScheme: next });
+  });
+
+  receive((event) => {
+    // Idempotent: skip writes that match the current stored value so a
+    // `preferredColorScheme.set` originating from cross-context change
+    // doesn't loop back into another write.
+    if (adapter.getPreferredColorScheme() === event.preferredColorScheme)
+      return;
+
+    adapter.persistPreferredColorScheme(event.preferredColorScheme);
+  });
+
+  return () => {
+    unsubscribePreferredColorScheme();
+    unsubscribeOs();
+  };
+});
+
+/**
+ * @internal
+ */
+export const systemPreferencesLogic = setup({
+  types: {
+    input: {} as { adapter?: SystemPreferencesAdapter },
+    context: {} as SystemPreferencesContext & {
+      adapter: SystemPreferencesAdapter | undefined;
+    },
+    events: {} as SystemPreferencesEvent,
+  },
+  actors: {
+    adapterBridge: adapterBridgeLogic,
+  },
+  actions: {
+    setPreferredColorScheme: assign({
+      preferredColorScheme: (
+        _,
+        params: { preferredColorScheme: ColorSchemePreference },
+      ) => params.preferredColorScheme,
+      colorScheme: (
+        { context },
+        params: { preferredColorScheme: ColorSchemePreference },
+      ) =>
+        resolveColorScheme(params.preferredColorScheme, context.osColorScheme),
+    }),
+    setOsColorScheme: assign({
+      osColorScheme: (_, params: { osColorScheme: ColorScheme }) =>
+        params.osColorScheme,
+      colorScheme: ({ context }, params: { osColorScheme: ColorScheme }) =>
+        resolveColorScheme(context.preferredColorScheme, params.osColorScheme),
+    }),
+  },
+}).createMachine({
+  id: "system-preferences",
+  initial: "ready",
+  context: ({ input }) => {
+    const adapter = input.adapter;
+    const preferredColorScheme =
+      adapter?.getPreferredColorScheme() ?? DEFAULT_PREFERRED_COLOR_SCHEME;
+    const osColorScheme =
+      adapter?.getOsColorScheme() ?? DEFAULT_OS_COLOR_SCHEME;
+
+    return {
+      adapter,
+      preferredColorScheme,
+      osColorScheme,
+      colorScheme: resolveColorScheme(preferredColorScheme, osColorScheme),
+    };
+  },
+  invoke: {
+    id: "adapter",
+    src: "adapterBridge",
+    input: ({ context }) => context.adapter,
+  },
+  states: {
+    ready: {
+      on: {
+        "preferredColorScheme.set": {
+          actions: [
+            {
+              type: "setPreferredColorScheme",
+              params: ({ event }) => ({
+                preferredColorScheme: event.preferredColorScheme,
+              }),
+            },
+            // Forward to the adapter bridge so it can persist the user's
+            // choice. The bridge guards against redundant writes, so
+            // round-tripping a `preferredColorScheme.set` it sourced itself
+            // (e.g. from a `storage` event in another tab) is a no-op.
+            sendTo("adapter", ({ event }) => event),
+          ],
+        },
+        "osColorScheme.set": {
+          actions: [
+            {
+              type: "setOsColorScheme",
+              params: ({ event }) => ({
+                osColorScheme: event.osColorScheme,
+              }),
+            },
+          ],
+        },
+      },
+    },
+  },
+});