@wix/web5-embed

SDK primitives for embedding Wix Web5 conversational UI on host pages.

This package provides the shared infrastructure used by per-client embed bundles (e.g. @wix/w5-client-circana's embed bundle). It does not render a widget on its own. Each client owns its own widget DOM, styles, and defaults and composes them with the SDK primitives below.

Distribution model

Per-client IIFE bundles ship to a CloudFront-backed CDN that's keyed by the client's Wix MSID and supports /production/ and /latest/ aliases. Host pages embed the bundle via a single URL that never changes:

<script src="https://d13cktzsgh0qls.cloudfront.net/<MSID>/latest/user-query.iife.js"
        data-target="#my-app"
        data-base-url="/web5"
></script>

The Wix Web5 CLI scaffolds and deploys the per-client bundle, replacing <MSID> with the customer's real MSID. No bootstrap loader, no version pinning in URLs — /production/ resolves to the latest deployed version on each page load.

What's inside

• Focus-shortcut coordinator (getFocusShortcutCoordinator) — cross-bundle singleton that handles / and Cmd/Ctrl+K shortcuts so multiple Web5 widgets on the same page don't fight for the keyboard.
• Design-token loader (attachPromptInputTokensStylesheet) — fetches prompt-input-tokens.css from a versioned CDN (parastorage by default, which does not support /production/) and attaches it to a widget's shadow root. Resolves the version via static-versions.
• Static-versions helpers (fetchStaticVersions, findVersion, getCachedVersions, cacheVersions, DEFAULT_STATIC_VERSIONS_URL) — thin wrappers over the artifact registry endpoint with an in-memory cache. Used internally by the token loader; available for clients with similar needs.
• Script-tag config parsing (readBaseConfigFromScript, readBottomConfigFromScript, resolveTarget, shouldInit, shouldInitForPath) — shared logic for turning host-page <script data-*> attributes into a typed config object.
• Widget hooks (createInputHeightSync, createCollapseController, createSubmitFlow) — small composable utilities each widget can wire in without inheriting from a base class.

Defaults assume Wix infra

The SDK is published to public npm so external partners can integrate, but the defaults call Wix endpoints:

| Hook | Default | Override option | |---|---|---| | fetchStaticVersions(url?) | https://www.wixapis.com/web50-server/static-versions | first arg url | | attachPromptInputTokensStylesheet(shadow, opts?) | static.parastorage.com/services/web50-server-ui/<v>/prompt-input-tokens.css, artifact com.wixpress.web50-server-ui | opts.staticVersionsUrl, opts.tokensCdnBase, opts.tokensArtifactId, opts.tokensFileName, opts.fallbackVersion |

If you're running outside Wix infrastructure, override every hook above with your own endpoints.

Shadow DOM is required

Per-client widgets must render into a shadow root. The SDK helpers assume a shadow root for token-stylesheet attachment and CSS isolation; widgets that mount into the regular DOM will leak styles into the host page and may pick up unintended host-page CSS.

Quick start (minimal client widget)

// in your per-client `main.ts`
import {
  attachPromptInputTokensStylesheet,
  createSubmitFlow,
  getFocusShortcutCoordinator,
  resolveTarget,
  readBaseConfigFromScript,
  shouldInit,
} from '@wix/web5-embed';

const config = readBaseConfigFromScript(document.currentScript);
if (!shouldInit(config.requireParam)) {
  // host page didn't opt in
} else {
  const host = resolveTarget(config.target);
  const shadow = host.attachShadow({ mode: 'open' });
  shadow.innerHTML = `<style>/* your branded styles */</style><textarea></textarea>`;
  void attachPromptInputTokensStylesheet(shadow);
  const submit = createSubmitFlow({ baseUrl: config.baseUrl ?? 'https://my-host/web5/v2' });
  // ... wire up textarea + submit
}

For a complete reference, see Circana's implementation in packages/w5-client-circana/src/web5-embed/.

License

MIT — see LICENSE.