@fluid-app/widget-runtime

Remote DOM runtime for third-party Fluid widgets.

The package has two deliberately small public entry points:

• @fluid-app/widget-runtime mounts a widget worker into a host element.
• @fluid-app/widget-runtime/worker starts a worker containing authored React widgets and exposes declared host capabilities.

Widget discovery, descriptor validation, catalog access, publishing, and builder registration belong to portal packages and the CLI. This package owns only the host/worker execution boundary.

Host

Portal applications should use the Portal SDK host. It owns the complete reviewed Fluid UI renderer map and keeps component overlays inside the widget shadow root. The application only supplies the compiled shadow-root CSS:

import { createPortal } from "@fluid-app/portal-sdk";
import fluidComponentCssUrl from "@fluid-app/portal-sdk/remote-widget-shadow.css?url";

createPortal({
  remoteWidgets: { fluidComponentCssUrls: [fluidComponentCssUrl] },
});

The current portal application and generated portal starter include this configuration. Mist's direct live-preview host supplies the same renderer map, containment wrapper, and stylesheet as inline CSS.

mountRemoteDomWidget() is the lower-level host API. A direct consumer of a current Fluid widget worker must provide all three Fluid UI host pieces:

• the complete reviewed componentRenderers map;
• a wrapRemoteRoot implementation that contains portals in the widget area;
• the matching fluidComponentCssText or fluidComponentCssUrls.

The runtime advertises Fluid UI contract v2 only when every v2 renderer is present. A Fluid UI worker therefore fails contract negotiation instead of mounting against a host with a partial renderer set.

import { mountRemoteDomWidget } from "@fluid-app/widget-runtime/remote-dom";
import {
  REMOTE_DOM_COMPONENT_RENDERERS,
  wrapRemoteDomRoot,
} from "@fluid-app/portal-sdk";
import fluidComponentCssUrl from "@fluid-app/portal-sdk/remote-widget-shadow.css?url";

const handle = mountRemoteDomWidget({
  host: document.querySelector("#widget")!,
  artifact: {
    packageId: "example.widgets",
    version: "1.0.0",
    widgetType: "Greeting",
    workerEntryUrl: "https://cdn.example.com/widget.js",
    cssUrls: [],
    assetUrls: [],
    capabilities: [{ name: "account", version: "1" }],
  },
  props: { name: "Ada" },
  componentRenderers: REMOTE_DOM_COMPONENT_RENDERERS,
  wrapRemoteRoot: wrapRemoteDomRoot,
  fluidComponentCssUrls: [fluidComponentCssUrl],
  callCapability: (capability, method, payload) =>
    portalCapabilities.call(capability, method, payload),
});

await handle.ready;
handle.updateProps({ name: "Grace" });
handle.dispose();

Each mount creates one module worker and one Remote DOM thread. Disposal releases the thread, worker, styles, event listeners, and rendered nodes. The host sanitizes all mutations, URLs, CSS, events, and serializable values before applying them to a shadow root.

Worker

import {
  startRemoteDomWidgetWorker,
  useRemoteDomCapability,
} from "@fluid-app/widget-runtime/worker";

function Greeting({ name }: { readonly name: string }) {
  const account = useRemoteDomCapability("account");
  return (
    <button onClick={() => account.call("openProfile")}>Hello {name}</button>
  );
}

startRemoteDomWidgetWorker({ widgets: { Greeting } });

Workers can render arbitrary supported HTML and CSS through upstream Remote DOM. The runtime disables storage, nested-worker, fresh-realm, and non-fetch network globals where the worker environment permits it. Host calls are limited to capabilities declared by the widget package descriptor.

fetch is denied unless the selected widget declares networkAccess version 1 and the host supplies an exact persisted grant. Granted calls go directly through the preserved native worker fetch; the runtime does not inject Fluid credentials or headers. The initial URL cannot address fluid.app, the host portal origin, loopback, or a private-network IP. DNS resolution and redirect destinations are not inspected. A redirect can therefore reach a target that would have been rejected as the initial URL. WebSocket, EventSource, WebTransport, and streaming-specific APIs remain unavailable in v1.

Threat model

Widget catalog approval is a trust decision: approved packages are trusted application code supplied by a company or Droplet owner. Worker-global lockdown, capability validation, mutation sanitization, URL policy, resource limits, and shadow-root isolation are defense in depth around that trusted code. They protect the host DOM and narrow accidental ambient access, but they do not constitute a complete network sandbox or a substitute for package review, catalog authorization, browser isolation, or server-side access control.

Network-enabled code can send any portal data available to that widget to an external service. Worker isolation does not protect the reputation of Fluid domains from package behavior; catalog, builder, and CLI approval must treat network access as a publisher trust decision.

Non-goals

• No classic script loading or browser globals.
• No legacy widget registration or descriptor conversion.
• No catalog or package validation API.
• No worker pooling, heartbeat, diagnostics framework, or version disabling.
• No compatibility layer for legacy portal SDK hooks.