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

package/src/system/remote.machine.ts

@@ -0,0 +1,219 @@
+import { assign, fromPromise, sendParent, setup } from "xstate";
+
+import { loadRemoteModule } from "./load-federated-module";
+import type { FederationInstance } from "./module-federation";
+
+/**
+ * @public
+ */
+export interface RemoteRenderOptions {
+  basePath?: string;
+  scheme?: "light" | "dark";
+  /**
+   * This is a temporary measure designed to authenticate federated
+   * studios & SDK apps before we write a working protocol.
+   */
+  unstable_temporaryToken?: string | null;
+}
+
+/**
+ * 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 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;
+}
+
+/**
+ * @public
+ */
+export interface RemoteError {
+  message: string;
+  cause: unknown;
+}
+
+/**
+ * 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) {
+    super(`Remote "${remoteId}" did not expose a render function`);
+  }
+}
+
+/**
+ * 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 {
+  /** Fully-qualified module id — `${appId}/${expose}`. One child per moduleId. */
+  moduleId: string;
+  entry: string;
+  instance: FederationInstance;
+}
+
+type RemoteContext = RemoteInput & {
+  /** The loaded module, shape-agnostic — each consumer narrows it. @see {@link RemoteModuleByInterfaceType} */
+  module: unknown;
+  error: RemoteError | null;
+};
+
+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 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, 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.
+ *
+ * @internal
+ */
+export const remoteLogic = setup({
+  types: {
+    input: {} as RemoteInput,
+    context: {} as RemoteContext,
+    tags: {} as "loading" | "ready" | "failed",
+  },
+  actors: {
+    load: loadLogic,
+  },
+  actions: {
+    setModule: assign({
+      module: (_, params: { module: unknown }) => params.module,
+      error: () => null,
+    }),
+    setError: assign({
+      module: () => null,
+      error: (_, params: { error: unknown }) => normaliseError(params.error),
+    }),
+  },
+}).createMachine({
+  id: "remote",
+  initial: "loading",
+  context: ({ input }) => ({
+    ...input,
+    module: null,
+    error: null,
+  }),
+  states: {
+    loading: {
+      tags: ["loading"],
+      invoke: {
+        src: "load",
+        input: ({ context }) => ({
+          moduleId: context.moduleId,
+          entry: context.entry,
+          instance: context.instance,
+        }),
+        onDone: {
+          target: "loaded",
+          actions: [
+            {
+              type: "setModule",
+              params: ({ event }) => ({ module: event.output }),
+            },
+          ],
+        },
+        onError: {
+          target: "error",
+          actions: [
+            {
+              type: "setError",
+              params: ({ event }) => ({ error: event.error }),
+            },
+          ],
+        },
+      },
+    },
+    loaded: {
+      tags: ["ready"],
+      entry: sendParent(({ context }) => ({
+        type: "remote.settled" as const,
+        moduleId: context.moduleId,
+        status: "loaded" as const,
+      })),
+    },
+    error: {
+      tags: ["failed"],
+      entry: sendParent(({ context }) => ({
+        type: "remote.settled" as const,
+        moduleId: context.moduleId,
+        status: "error" as const,
+      })),
+    },
+  },
+});
+
+function normaliseError(error: unknown): RemoteError {
+  if (error instanceof Error) {
+    return { message: error.message, cause: error };
+  }
+  return { message: String(error), cause: error };
+}

package/src/system/remotes.machine.ts

@@ -0,0 +1,92 @@
+import { type ActorRefFrom, assign, setup } from "xstate";
+
+import { type FederationInstance } from "./module-federation";
+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"; moduleId: string; entry: string }
+  | { type: "remote.settled"; moduleId: string; status: "loaded" | "error" };
+
+/**
+ * Supervisor machine for federated modules.
+ *
+ * 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,
+  },
+  actors: {
+    remote: remoteLogic,
+  },
+  guards: {
+    remoteNotKnown: ({ context }, params: { moduleId: string }) =>
+      !context.children.has(params.moduleId),
+  },
+  actions: {
+    spawnRemote: assign({
+      children: (
+        { context, spawn },
+        params: { moduleId: string; entry: string },
+      ) => {
+        const ref = spawn("remote", {
+          id: params.moduleId,
+          systemId: `remotes.${params.moduleId}`,
+          input: {
+            moduleId: params.moduleId,
+            entry: params.entry,
+            instance: context.instance,
+          },
+        });
+        return new Map(context.children).set(params.moduleId, ref);
+      },
+    }),
+  },
+}).createMachine({
+  id: "remotes",
+  context: ({ input }) => ({
+    instance: input.instance,
+    children: new Map(),
+  }),
+  on: {
+    "remote.load.request": {
+      guard: {
+        type: "remoteNotKnown",
+        params: ({ event }) => ({ moduleId: event.moduleId }),
+      },
+      actions: [
+        {
+          type: "spawnRemote",
+          params: ({ event }) => ({
+            moduleId: event.moduleId,
+            entry: event.entry,
+          }),
+        },
+      ],
+    },
+    // Reserved for future supervision/retry. Forwarded by per-remote
+    // children on entry to `loaded` or `error`; currently a no-op so the
+    // event is part of the typed surface rather than a silent unknown.
+    "remote.settled": {},
+  },
+});

package/src/system/root.machine.ts

@@ -0,0 +1,224 @@
+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 {
+  createInstance,
+  type FederationInstance,
+  log,
+} from "./module-federation";
+import { remotesLogic } from "./remotes.machine";
+import { servicesLogic } from "./services.machine";
+import {
+  type SystemPreferencesAdapter,
+  systemPreferencesLogic,
+} from "./system-preferences.machine";
+import {
+  telemetryLogic,
+  type WorkbenchUserProperties,
+} from "./telemetry.machine";
+
+type OSInput = WorkbenchUserProperties & {
+  systemPreferencesAdapter?: SystemPreferencesAdapter;
+};
+
+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;
+};
+
+/**
+ * The base inputs for the OS machine.
+ * @internal
+ */
+export interface OSBaseInput extends Pick<OSContext, "instance"> {}
+
+/**
+ * The sanity OS machine, responsible for managing the global state of the OS.
+ * @public
+ * @example
+ * ```ts
+ * import { os, createOSOptions } from "@sanity/workbench/system";
+ * import { useActor } from "@xstate/react";
+ *
+ * const [state, send] = useActor(os, createOSOptions({
+ *   version: "1.0.0",
+ *   organizationId: "...",
+ *   environment: "production",
+ *   userAgent: navigator.userAgent,
+ * }));
+ * ```
+ */
+export const os = setup({
+  types: {
+    input: {} as OSInput,
+    context: {} as OSContext,
+    events: {} as
+      | { type: "boot.auth.ready" }
+      | { type: "boot.auth.failed" }
+      | { type: "boot.telemetry.ready" },
+    // https://github.com/statelyai/xstate/issues/5515
+    children: {} as {
+      auth: "auth";
+      telemetry: "telemetry";
+      "system-preferences": "systemPreferences";
+      remotes: "remotes";
+      services: "services";
+    },
+  },
+  actors: {
+    auth: authLogic,
+    telemetry: telemetryLogic,
+    systemPreferences: systemPreferencesLogic,
+    remotes: remotesLogic,
+    services: servicesLogic,
+  },
+  guards: {
+    hasTag: (_, params: { hasTag: boolean }) => params.hasTag,
+  },
+  actions: {
+    raiseAuthReady: raise({ type: "boot.auth.ready" }),
+    raiseAuthFailed: raise({ type: "boot.auth.failed" }),
+    raiseTelemetryReady: raise({
+      type: "boot.telemetry.ready",
+    }),
+    startTelemetry: sendTo("telemetry", {
+      type: "telemetry.start",
+    }),
+  },
+}).createMachine({
+  id: "os",
+  context: ({ input }) => ({
+    instance: createSanityInstance(),
+    federationInstance: createInstance({
+      name: "workbench-applications",
+      plugins: [log(logger.debug)],
+    }),
+    userProperties: {
+      version: input.version,
+      organizationId: input.organizationId,
+      environment: input.environment,
+      userAgent: input.userAgent,
+    },
+    systemPreferencesAdapter: input.systemPreferencesAdapter,
+  }),
+  initial: "booting",
+  invoke: [
+    {
+      id: "auth",
+      systemId: "auth",
+      src: "auth",
+      input: ({ context }) => ({ instance: context.instance }),
+      onSnapshot: [
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("authenticated"),
+            }),
+          },
+          actions: [{ type: "raiseAuthReady" }],
+        },
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("error"),
+            }),
+          },
+          actions: [{ type: "raiseAuthFailed" }],
+        },
+      ],
+    },
+    {
+      id: "telemetry",
+      systemId: "telemetry",
+      src: "telemetry",
+      input: ({ context }) => ({
+        instance: context.instance,
+        ...context.userProperties,
+      }),
+      onSnapshot: [
+        {
+          guard: {
+            type: "hasTag",
+            params: ({ event }) => ({
+              hasTag: event.snapshot.hasTag("telemetry-resolved"),
+            }),
+          },
+          actions: [{ type: "raiseTelemetryReady" }],
+        },
+      ],
+    },
+    {
+      id: "system-preferences",
+      systemId: "system-preferences",
+      src: "systemPreferences",
+      input: ({ context }) => ({ adapter: context.systemPreferencesAdapter }),
+    },
+    {
+      id: "remotes",
+      systemId: "remotes",
+      src: "remotes",
+      input: ({ context }) => ({ instance: context.federationInstance }),
+    },
+    {
+      id: "services",
+      systemId: "services",
+      src: "services",
+      input: ({ context }) => ({ instance: context.federationInstance }),
+    },
+  ],
+  states: {
+    booting: {
+      initial: "auth",
+      states: {
+        auth: {
+          on: {
+            "boot.auth.ready": {
+              target: "telemetry",
+              actions: [{ type: "startTelemetry" }],
+            },
+            "boot.auth.failed": { target: "error" },
+          },
+        },
+        telemetry: {
+          on: {
+            "boot.telemetry.ready": { target: "done" },
+          },
+        },
+        error: {},
+        done: { type: "final" },
+      },
+      onDone: { target: "running" },
+    },
+    running: {
+      type: "parallel",
+    },
+  },
+});
+
+/**
+ * Creates a set of default options for the OS machine. Forwards the workbench
+ * user properties to the machine's input and wires the structured-logging
+ * `inspect` callback. Browser-specific concerns (color-scheme seeding,
+ * persistence) live in the {@link SystemPreferencesAdapter} the host passes
+ * via `systemPreferencesAdapter`.
+ * @public
+ */
+export function createOSOptions(input: OSInput) {
+  return {
+    id: "os",
+    input,
+    inspect,
+  } satisfies ActorOptions<typeof os>;
+}