@sanity/workbench 0.1.0-alpha.19 → 0.1.0-alpha.20

package/src/system/remote.machine.ts

@@ -1,6 +1,8 @@
 import type { FederationInstance } from "@sanity/federation/runtime";
 import { assign, fromPromise, sendParent, setup } from "xstate";
 
+import { loadRemoteModule } from "./load-federated-module";
+
 /**
  * @public
  */
@@ -15,13 +17,42 @@ export interface RemoteRenderOptions {
 }
 
 /**
+ * A loaded render-contract module. `TProps` is what its `render` accepts —
+ * `RemoteRenderOptions` for an application's full-page view, the view's props
+ * for a dock-panel component.
+ * @public
+ */
+export interface LoadedRemoteModule<TProps = RemoteRenderOptions> {
+  render: (rootElement: HTMLElement, props?: TProps) => () => void;
+}
+
+/**
+ * A worker service's loader module — the `worker` interface's expose. Carries
+ * the worker bundle URL (root-relative to the app origin) for the host to
+ * bootstrap, not a render function; the services counterpart of
+ * {@link LoadedRemoteModule}.
  * @public
  */
-export interface LoadedRemoteModule {
-  render: (
-    rootElement: HTMLElement,
-    options?: RemoteRenderOptions,
-  ) => () => void;
+export interface ServiceLoaderModule {
+  url: string;
+  type: string;
+  name: string;
+  version: number;
+}
+
+/**
+ * The federated-module shape each interface type exposes, keyed by
+ * `interface_type`. Every interface — `panel`, `app`, `worker` — loads through
+ * the same {@link remoteLogic} lifecycle; this maps what its loaded module looks
+ * like so each consumer narrows the machine's shape-agnostic `module` to the
+ * right type: a render contract for `panel`/`app` (rendered by an island), a
+ * worker loader for `worker` (run as a Web Worker, never rendered).
+ * @public
+ */
+export interface RemoteModuleByInterfaceType {
+  panel: LoadedRemoteModule;
+  app: LoadedRemoteModule;
+  worker: ServiceLoaderModule;
 }
 
 /**
@@ -33,10 +64,11 @@ export interface RemoteError {
 }
 
 /**
- * Thrown by the load actor when a remote responds successfully but does
- * not expose a `render` function. Surfaced via `RemoteError.cause` for
- * consumers that need to discriminate.
- * @internal
+ * Thrown by a render consumer (e.g. the island) when a loaded module doesn't
+ * expose a `render` function. Render-specific — `remoteLogic` itself is
+ * shape-agnostic, so this lives with the consumer that needs the contract, not
+ * the loader. Surfaced via `RemoteError.cause` for consumers that discriminate.
+ * @public
  */
 export class ModuleShapeError extends Error {
   constructor(remoteId: string) {
@@ -44,45 +76,59 @@ export class ModuleShapeError extends Error {
   }
 }
 
+/**
+ * Thrown by the load actor when a remote's expose resolves empty — the module
+ * isn't published, or `loadRemote` returned nothing. Generic across interface
+ * types; the shape-specific check (a render function, a worker URL) is the
+ * consumer's, since `remoteLogic` loads every interface the same way.
+ * @internal
+ */
+export class ModuleLoadError extends Error {
+  constructor(remoteId: string) {
+    super(`Remote module "${remoteId}" failed to load`);
+  }
+}
+
 /**
  * @internal
  */
 export interface RemoteInput {
-  id: string;
+  /** Fully-qualified module id — `${appId}/${expose}`. One child per moduleId. */
+  moduleId: string;
   entry: string;
   instance: FederationInstance;
 }
 
 type RemoteContext = RemoteInput & {
-  module: LoadedRemoteModule | null;
+  /** The loaded module, shape-agnostic — each consumer narrows it. @see {@link RemoteModuleByInterfaceType} */
+  module: unknown;
   error: RemoteError | null;
 };
 
-const REMOTE_MODULE = "App";
-
-const loadLogic = fromPromise<LoadedRemoteModule, RemoteInput>(
-  async ({ input }) => {
-    input.instance.registerRemotes([{ name: input.id, entry: input.entry }]);
-    const remoteModule = await input.instance.loadRemote<unknown>(
-      `${input.id}/${REMOTE_MODULE}`,
-    );
-    if (
-      !remoteModule ||
-      typeof (remoteModule as { render?: unknown }).render !== "function"
-    ) {
-      throw new ModuleShapeError(input.id);
-    }
-    return remoteModule as LoadedRemoteModule;
-  },
-);
+const loadLogic = fromPromise<unknown, RemoteInput>(async ({ input }) => {
+  const remoteModule = await loadRemoteModule<unknown>(input.instance, {
+    moduleId: input.moduleId,
+    entry: input.entry,
+  });
+  // The loader is interface-agnostic: it only guarantees a module came back.
+  // Render-vs-worker shape validation is the consumer's (a panel/app island
+  // checks `render`; a service checks `url`).
+  if (remoteModule == null) {
+    throw new ModuleLoadError(input.moduleId);
+  }
+  return remoteModule;
+});
 
 /**
- * Lifecycle machine for a single federated application remote.
+ * Lifecycle machine for a single federated interface module — an application's
+ * `App` entry, one view component, or a worker service's loader. Interface-
+ * agnostic: it loads and tracks any module, leaving the shape contract
+ * (render vs. worker URL) to the consumer.
  *
- * Spawned by the {@link remotesLogic} supervisor on demand. Each instance
- * owns one remote's load lifecycle: `loading` → `loaded | error`. Tags
- * (`loading` / `ready` / `failed`) drive the UI contract — state names
- * are internal.
+ * Spawned by the {@link remotesLogic} supervisor on demand, one per remote id
+ * (`${appId}/${moduleId}`). Each instance owns one module's load lifecycle:
+ * `loading` → `loaded | error`. Tags (`loading` / `ready` / `failed`) drive the
+ * UI contract — state names are internal.
  *
  * The machine sends a `remote.settled` event to its parent on entry to
  * either terminal state, reserved for future supervision/retry.
@@ -100,7 +146,7 @@ export const remoteLogic = setup({
   },
   actions: {
     setModule: assign({
-      module: (_, params: { module: LoadedRemoteModule }) => params.module,
+      module: (_, params: { module: unknown }) => params.module,
       error: () => null,
     }),
     setError: assign({
@@ -122,7 +168,7 @@ export const remoteLogic = setup({
       invoke: {
         src: "load",
         input: ({ context }) => ({
-          id: context.id,
+          moduleId: context.moduleId,
           entry: context.entry,
           instance: context.instance,
         }),
@@ -150,7 +196,7 @@ export const remoteLogic = setup({
       tags: ["ready"],
       entry: sendParent(({ context }) => ({
         type: "remote.settled" as const,
-        id: context.id,
+        moduleId: context.moduleId,
         status: "loaded" as const,
       })),
     },
@@ -158,7 +204,7 @@ export const remoteLogic = setup({
       tags: ["failed"],
       entry: sendParent(({ context }) => ({
         type: "remote.settled" as const,
-        id: context.id,
+        moduleId: context.moduleId,
         status: "error" as const,
       })),
     },

package/src/system/remotes.machine.ts

@@ -1,35 +1,38 @@
-import {
-  createInstance,
-  type FederationInstance,
-} from "@sanity/federation/runtime";
-import { log } from "@sanity/federation/runtime/plugins/log";
+import { type FederationInstance } from "@sanity/federation/runtime";
 import { type ActorRefFrom, assign, setup } from "xstate";
 
-import { logger } from "../core/log";
 import { remoteLogic } from "./remote.machine";
 
+/** The shared federation instance, supplied by the root machine. */
+type RemotesInput = {
+  instance: FederationInstance;
+};
+
 type RemotesContext = {
   instance: FederationInstance;
   children: Map<string, ActorRefFrom<typeof remoteLogic>>;
 };
 
 type RemotesEvent =
-  | { type: "remote.load.request"; id: string; entry: string }
-  | { type: "remote.settled"; id: string; status: "loaded" | "error" };
+  | { type: "remote.load.request"; moduleId: string; entry: string }
+  | { type: "remote.settled"; moduleId: string; status: "loaded" | "error" };
 
 /**
- * Supervisor machine for federated application remotes.
+ * Supervisor machine for federated modules.
  *
- * Owns a single {@link FederationInstance} (the `workbench-applications`
- * instance) and spawns one {@link remoteLogic} child per requested
- * remote. The supervisor is invoked at the root of the OS machine for
- * inspector visibility (`[sanity-workbench:os:remotes]`) — boot does
- * not gate on it.
+ * Uses the shared {@link FederationInstance} (the `workbench-applications`
+ * instance, supplied by the root machine and shared with `services`) and spawns
+ * one {@link remoteLogic} child per remote id (`${appId}/${moduleId}`) — so an
+ * application's `App` entry and each of its dock-panel view components load (and
+ * are tracked) independently. The
+ * supervisor is invoked at the root of the OS machine for inspector visibility
+ * (`[sanity-workbench:os:remotes]`) — boot does not gate on it.
  *
  * @internal
  */
 export const remotesLogic = setup({
   types: {
+    input: {} as RemotesInput,
     context: {} as RemotesContext,
     events: {} as RemotesEvent,
   },
@@ -37,44 +40,47 @@ export const remotesLogic = setup({
     remote: remoteLogic,
   },
   guards: {
-    remoteNotKnown: ({ context }, params: { id: string }) =>
-      !context.children.has(params.id),
+    remoteNotKnown: ({ context }, params: { moduleId: string }) =>
+      !context.children.has(params.moduleId),
   },
   actions: {
     spawnRemote: assign({
-      children: ({ context, spawn }, params: { id: string; entry: string }) => {
+      children: (
+        { context, spawn },
+        params: { moduleId: string; entry: string },
+      ) => {
         const ref = spawn("remote", {
-          id: params.id,
-          systemId: `remotes.${params.id}`,
+          id: params.moduleId,
+          systemId: `remotes.${params.moduleId}`,
           input: {
-            id: params.id,
+            moduleId: params.moduleId,
             entry: params.entry,
             instance: context.instance,
           },
         });
-        return new Map(context.children).set(params.id, ref);
+        return new Map(context.children).set(params.moduleId, ref);
       },
     }),
   },
 }).createMachine({
   id: "remotes",
-  context: () => ({
-    instance: createInstance({
-      name: "workbench-applications",
-      plugins: [log(logger.debug)],
-    }),
+  context: ({ input }) => ({
+    instance: input.instance,
     children: new Map(),
   }),
   on: {
     "remote.load.request": {
       guard: {
         type: "remoteNotKnown",
-        params: ({ event }) => ({ id: event.id }),
+        params: ({ event }) => ({ moduleId: event.moduleId }),
       },
       actions: [
         {
           type: "spawnRemote",
-          params: ({ event }) => ({ id: event.id, entry: event.entry }),
+          params: ({ event }) => ({
+            moduleId: event.moduleId,
+            entry: event.entry,
+          }),
         },
       ],
     },

package/src/system/root.machine.ts

@@ -1,9 +1,16 @@
+import {
+  createInstance,
+  type FederationInstance,
+} from "@sanity/federation/runtime";
+import { log } from "@sanity/federation/runtime/plugins/log";
 import { createSanityInstance, type SanityInstance } from "@sanity/sdk";
 import { raise, sendTo, setup, type ActorOptions } from "xstate";
 
+import { logger } from "../core/log";
 import { authLogic } from "./auth.machine";
 import { inspect } from "./inspect";
 import { remotesLogic } from "./remotes.machine";
+import { servicesLogic } from "./services.machine";
 import {
   type SystemPreferencesAdapter,
   systemPreferencesLogic,
@@ -19,6 +26,12 @@ type OSInput = WorkbenchUserProperties & {
 
 type OSContext = {
   instance: SanityInstance;
+  /**
+   * The single module-federation instance every interface loads through —
+   * shared by the `remotes` (views) and `services` (workers) supervisors so an
+   * app's remote is registered once for all its interfaces.
+   */
+  federationInstance: FederationInstance;
   userProperties: WorkbenchUserProperties;
   systemPreferencesAdapter: SystemPreferencesAdapter | undefined;
 };
@@ -59,6 +72,7 @@ export const os = setup({
       telemetry: "telemetry";
       "system-preferences": "systemPreferences";
       remotes: "remotes";
+      services: "services";
     },
   },
   actors: {
@@ -66,6 +80,7 @@ export const os = setup({
     telemetry: telemetryLogic,
     systemPreferences: systemPreferencesLogic,
     remotes: remotesLogic,
+    services: servicesLogic,
   },
   guards: {
     hasTag: (_, params: { hasTag: boolean }) => params.hasTag,
@@ -84,6 +99,10 @@ export const os = setup({
   id: "os",
   context: ({ input }) => ({
     instance: createSanityInstance(),
+    federationInstance: createInstance({
+      name: "workbench-applications",
+      plugins: [log(logger.debug)],
+    }),
     userProperties: {
       version: input.version,
       organizationId: input.organizationId,
@@ -150,6 +169,13 @@ export const os = setup({
       id: "remotes",
       systemId: "remotes",
       src: "remotes",
+      input: ({ context }) => ({ instance: context.federationInstance }),
+    },
+    {
+      id: "services",
+      systemId: "services",
+      src: "services",
+      input: ({ context }) => ({ instance: context.federationInstance }),
     },
   ],
   states: {

package/src/system/service.machine.ts

@@ -0,0 +1,207 @@
+import { type FederationInstance } from "@sanity/federation/runtime";
+import { assign, fromCallback, setup } from "xstate";
+
+import { logger } from "../core/log";
+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"],
+    },
+  },
+});