@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/application/host/bootstrap.ts

@@ -0,0 +1,43 @@
+// Builds the host's controller from what the build aliases in: the generated
+// manifest (which also carries the kit's persistence setting), the kit's
+// preview options and its registered views, plus the shell's own options,
+// which may depend on the catalog, so the catalog is built first.
+// The regeneration endpoint exists on the development server only, so the static
+// build gets a controller without a regeneration transport. The html source
+// is the development server's to print on request; the static build reads
+// what generation printed for each scenario. The iframes load
+// from the URL the preview is served under, so a static build works from a
+// subpath as well as from a domain's root.
+import manifest from '@preview-generated/manifest.json';
+import { options as previewOptions } from '@preview-configuration';
+import { views } from '@preview-views';
+import {
+  catalogFromManifest,
+  createFetchHtmlSourceTransport,
+  createFetchRegenerationTransport,
+  createPreviewController,
+  createStaticHtmlSourceLoader,
+  type PreviewController,
+} from '../../src/controller';
+import type { PreviewShell } from '../../src/shell';
+import { shellOptionsFor } from '../../src/shell-acceptance';
+import { previewBaseUrl } from '../lib/base-url';
+
+export function createHostController(
+  shell: Pick<PreviewShell, 'options'> = {}
+): PreviewController {
+  const catalog = catalogFromManifest(manifest, views);
+  return createPreviewController({
+    catalog,
+    options: previewOptions,
+    shellOptions: shellOptionsFor(shell, catalog),
+    regeneration: import.meta.env.DEV
+      ? createFetchRegenerationTransport()
+      : undefined,
+    ...(import.meta.env.DEV
+      ? { htmlSource: createFetchHtmlSourceTransport() }
+      : { scenarioHtmlSources: createStaticHtmlSourceLoader(previewBaseUrl) }),
+    persistence: manifest.persistence,
+    baseUrl: previewBaseUrl,
+  });
+}

package/application/host/main.ts

@@ -0,0 +1,31 @@
+// The host page's bootstrap: the one module that reads the build aliases. It
+// loads the shell the kit configured (`@preview-shell`), checks it, builds the
+// controller with the shell's own options (resolved against the catalog when
+// the shell gives them as a function), and mounts the shell into the root
+// element. During development a changed shell is unmounted and the new one
+// mounted over the same controller, so the selection and the editor's tree
+// survive an edit to the shell.
+import shellModule from '@preview-shell';
+import { createHostController } from './bootstrap';
+import { acceptShell, mountShell } from './shell-host';
+
+const root = document.getElementById('root')!;
+const shell = acceptShell(shellModule, root);
+
+/** The host's controller, built once per page load. */
+export const controller = createHostController(shell);
+
+let unmountShell = mountShell(shell, root, controller);
+
+/** Unmount the shell; the controller stays. */
+export function unmount(): void {
+  unmountShell();
+}
+
+if (import.meta.hot) {
+  import.meta.hot.accept('@preview-shell', (updated) => {
+    if (!updated) return;
+    unmountShell();
+    unmountShell = mountShell(acceptShell(updated.default, root), root, controller);
+  });
+}

package/application/host/shell-host.ts

@@ -0,0 +1,47 @@
+// How the host page takes a shell: it checks the module's default export
+// against the contract version it serves, refusing one it cannot serve with a
+// message shown in the page as well as thrown, and mounts an accepted shell
+// into the root element over the controller. Framework-free; the bootstrap
+// (main.ts) calls it on load and again on a hot update of the shell.
+import type { PreviewController, PreviewShell } from '../../src/shell';
+import { shellProblem } from '../../src/shell-acceptance';
+
+/**
+ * The shell a module default-exports, once checked. A module whose export is
+ * not a shell this preview serves is refused: the reason is written into
+ * `root` for the person looking at the page and thrown for the console.
+ *
+ * @param candidate - The shell module's default export.
+ * @param root - The host page's root element.
+ * @returns The shell.
+ */
+export function acceptShell(candidate: unknown, root: HTMLElement): PreviewShell {
+  const problem = shellProblem(candidate);
+  if (problem !== undefined) {
+    const message = `[preview] The configured shell cannot be used. ${problem}`;
+    root.replaceChildren();
+    const notice = root.ownerDocument.createElement('pre');
+    notice.setAttribute('data-preview-shell-problem', '');
+    notice.textContent = message;
+    root.appendChild(notice);
+    throw new Error(message);
+  }
+  return candidate as PreviewShell;
+}
+
+/**
+ * Mount `shell` into `root`, emptied first, over `controller`.
+ *
+ * @param shell - An accepted shell.
+ * @param root - The host page's root element.
+ * @param controller - The preview's controller, which outlives the shell.
+ * @returns A function that unmounts the shell and empties the root.
+ */
+export function mountShell(shell: PreviewShell, root: HTMLElement, controller: PreviewController): () => void {
+  root.replaceChildren();
+  const unmount = shell.mount(root, controller);
+  return () => {
+    unmount?.();
+    root.replaceChildren();
+  };
+}

package/application/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>scaffold-ui-kit preview</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./host/main.ts"></script>
+  </body>
+</html>

package/application/lib/base-url.ts

@@ -0,0 +1,15 @@
+// The URL the preview is served under: the directory holding the host page,
+// with the iframes' pages below it. It never comes from the page's location,
+// which a shell may change for its own routing. The development server
+// serves the preview from its root. The static build is served from wherever
+// a file server puts it, so there the URL comes from this module's own: the
+// build puts every script, this one bundled among them, in `assets/`
+// (build.assetsDir in the Vite configuration), one directory below the
+// preview's. The relative path is held in a variable so the build does not
+// take `new URL(..., import.meta.url)` for an asset to bundle.
+const SCRIPT_DIRECTORY_PARENT = '../';
+
+/** The URL the preview is served under, ending in `/`. */
+export const previewBaseUrl: string = import.meta.env.DEV
+  ? import.meta.env.BASE_URL
+  : new URL(SCRIPT_DIRECTORY_PARENT, import.meta.url).href;

package/application/lib/no-code-block.ts

@@ -0,0 +1,7 @@
+// The empty code block - aliased in as `@preview-code-block` when the kit
+// names no `codeBlock`: the shell then shows the source itself, and no code
+// iframe loads.
+import type { CodeBlockMount } from '../../src/views';
+
+const mount: CodeBlockMount | undefined = undefined;
+export default mount;

package/application/lib/no-setup.ts

@@ -0,0 +1,3 @@
+// The empty per-target setup module - aliased in as `@preview-setup/<target>`
+// when the kit registers none for that target. Side effects only, so empty.
+export {};

package/application/lib/no-views.ts

@@ -0,0 +1,6 @@
+// The empty custom-view registry - aliased in as `@preview-views` when the kit
+// registers no `viewsModule`.
+import type { PreviewView } from '../../src/views';
+
+export const views: PreviewView[] = [];
+export const viewById = (_id: string): PreviewView | undefined => undefined;

package/application/preview/code/code.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" data-preview-frame="code">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>preview - code</title>
+  </head>
+  <body>
+    <div id="app" data-preview-code></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

package/application/preview/code/main.ts

@@ -0,0 +1,89 @@
+// Code iframe entry: the kit's own code block (`preview.codeBlock`),
+// showing one target's source of the story, named by `?target=`. The entry
+// loads the kit's setup module for the block's framework (named by
+// `?framework=`, so its stylesheets come first, as in the view iframes), then
+// the theme and canvas, then the block; it mounts the block with the first
+// source the host sends, and hands it each one after through the `updates`
+// it mounts with. The host sends a new source whenever the story, its props
+// or its content change, or the shell's wrapping does, and the option values
+// as it sends a story pane's.
+import type { CodeBlockContent, CodeBlockLanguage, ViewFramework } from '../../../src/views';
+import {
+  announcePreviewReady,
+  announcePreviewShown,
+  CODE_TARGET_PARAMETER,
+  PREVIEW_MESSAGE,
+  PREVIEW_MOUNT_ELEMENT_ID,
+  readPreviewMessage,
+  VIEW_FRAMEWORK_PARAMETER,
+} from '../../../src/protocol';
+
+const parameters = new URLSearchParams(window.location.search);
+const target = (parameters.get(CODE_TARGET_PARAMETER) ?? 'react') as CodeBlockContent['target'];
+
+/** Each target's language, as a highlighter names it. */
+const LANGUAGES: Record<CodeBlockContent['target'], CodeBlockLanguage> = {
+  react: 'tsx',
+  vue: 'vue',
+  svelte: 'svelte',
+  html: 'html',
+};
+
+type SetupFramework = Exclude<ViewFramework, 'dom'>;
+
+// Each framework's setup module, loaded only for a block of that framework.
+const SETUP_MODULES: Record<SetupFramework, () => Promise<unknown>> = {
+  react: () => import('@preview-setup/react'),
+  vue: () => import('@preview-setup/vue'),
+  svelte: () => import('@preview-setup/svelte'),
+};
+
+function isSetupFramework(value: string | null): value is SetupFramework {
+  return value !== null && Object.hasOwn(SETUP_MODULES, value);
+}
+
+let content: CodeBlockContent = { target, language: LANGUAGES[target], wrap: false };
+const listeners = new Set<(content: CodeBlockContent) => void>();
+
+async function start(): Promise<void> {
+  const framework = parameters.get(VIEW_FRAMEWORK_PARAMETER);
+  if (isSetupFramework(framework)) await SETUP_MODULES[framework]();
+  const { applyGlobals } = await import('../globals');
+  const { default: mount } = await import('@preview-code-block');
+  const element = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID);
+  let mounted = false;
+
+  window.addEventListener('message', (event: MessageEvent) => {
+    const message = readPreviewMessage(event.data);
+    if (!message) return;
+    if (message.type === PREVIEW_MESSAGE.globals) applyGlobals(message.options);
+    if (message.type !== PREVIEW_MESSAGE.code) return;
+    content = {
+      target,
+      language: LANGUAGES[target],
+      source: message.source,
+      reason: message.reason,
+      wrap: message.wrap === true,
+    };
+    if (!mounted && mount && element) {
+      mounted = true;
+      mount(element, content, {
+        subscribe(listener) {
+          listeners.add(listener);
+          return () => {
+            listeners.delete(listener);
+          };
+        },
+      });
+      // The block, once painted, lets the host show the pane.
+      announcePreviewShown();
+      return;
+    }
+    for (const listener of listeners) listener(content);
+  });
+  // Signal readiness so the host sends the options and the source (an iframe
+  // re-handshakes after each reload).
+  announcePreviewReady();
+}
+
+void start();

package/application/preview/globals.ts

@@ -0,0 +1,254 @@
+// Apply the kit-authored preview options to the preview document. Each option
+// declares its effect in the kit's preview block (`apply`); this module is the
+// single function that executes those effects on the iframe DOM - a generic loop
+// over the registry, so adding an option needs no change here. Everything
+// kit-specific (theme list, the page background, any wrapper the kit puts
+// around the mount, the DOM-name prefix) comes from the kit's preview block,
+// served as `@preview-configuration`; this module holds no kit vocabulary.
+import {
+  options as previewOptions,
+  canvas as previewCanvas,
+  themes as previewThemes,
+  mount as previewMount,
+  viewCanvas as previewViewCanvas,
+} from '@preview-configuration';
+import {
+  optionsById as buildOptionsById,
+  optionDefaults,
+  themeHref,
+  type ApplyTarget,
+  type OptionValue,
+  type PreviewOption,
+  type PreviewMountNode,
+} from '../../src/options';
+import { announcePreviewOptions } from '../../src/protocol';
+import { previewBaseUrl } from '../lib/base-url';
+
+const canvas = previewCanvas;
+const optionsById = buildOptionsById(previewOptions);
+announcePreviewOptions(Object.values(optionsById));
+
+// The code iframe (its mount marked in code.html) shows the kit's code block,
+// not a component: it gets no mount wrapper and no story option, only the
+// global options that set the page's look, and its mount fills the frame.
+const codeFrame =
+  document.getElementById('app')?.hasAttribute('data-preview-code') ?? false;
+const defaultTheme = previewThemes[0]?.id;
+const themeIds = new Set(previewThemes.map((theme) => theme.id));
+
+const THEME_LINK_ID = `${canvas.namePrefix}-theme-css`;
+
+function setTheme(theme: string): void {
+  const id = themeIds.has(theme) ? theme : defaultTheme;
+  if (!id) return;
+  const href = themeHref(id, previewBaseUrl);
+  let link = document.getElementById(THEME_LINK_ID) as HTMLLinkElement | null;
+  if (!link) {
+    link = document.createElement('link');
+    link.id = THEME_LINK_ID;
+    link.rel = 'stylesheet';
+    document.head.appendChild(link);
+  }
+  if (link.getAttribute('href') !== href) link.setAttribute('href', href);
+}
+
+// ── Mount wrapper ────────────────────────────────────────────────────────────
+// A kit may declare a wrapper subtree (`mount`) rendered around the
+// `#app` mount - framework-agnostic DOM the preview builds once at init and
+// reparents `#app` into. The preview knows nothing of what the nodes mean (a
+// kit's surface/box vocabulary lives entirely in its `mount` + CSS); it
+// only records each `ref` so option applies can target a wrapper node. Omitted,
+// `#app` stays a direct child of `<body>`.
+const WRAPPER_MARK = `data-${canvas.namePrefix}-preview-wrapper`;
+
+/** ref name → element, for `apply.target = { ref }` resolution. */
+const referencedElements: Record<string, HTMLElement> = {};
+
+function buildNode(node: PreviewMountNode): {
+  root: HTMLElement;
+  mount: HTMLElement | null;
+} {
+  const element = document.createElement(node.tag ?? 'div');
+  if (node.attributes)
+    for (const [name, value] of Object.entries(node.attributes))
+      element.setAttribute(name, value);
+  if (node.classes?.length) element.classList.add(...node.classes);
+  if (node.style) element.setAttribute('style', node.style);
+  if (node.ref) referencedElements[node.ref] = element;
+  let mount = node.mount ? element : null;
+  if (node.children)
+    for (const child of node.children) {
+      const built = buildNode(child);
+      element.appendChild(built.root);
+      // A deeper `mount: true` wins over an ancestor's (there is exactly one).
+      if (built.mount) mount = built.mount;
+    }
+  return { root: element, mount };
+}
+
+function buildMountWrapper(): void {
+  if (!previewMount) return;
+  // The mount wrapper is the component stage. The custom-view iframe (the
+  // preview's own `?view=` entry) hosts a view, not a component mount, and
+  // shares this module only for theme + option apply - it gets no wrapper.
+  if (new URLSearchParams(location.search).has('view') || codeFrame) return;
+  const mountElement = document.getElementById('app');
+  // Already wrapped (a redundant init on HMR) - leave it be.
+  if (!mountElement || mountElement.closest(`[${WRAPPER_MARK}]`)) return;
+  const parent = mountElement.parentElement ?? document.body;
+  const { root, mount } = buildNode(previewMount);
+  root.setAttribute(WRAPPER_MARK, '');
+  // Slot the wrapper in where `#app` sat, then move `#app` into the mount node.
+  parent.insertBefore(root, mountElement);
+  (mount ?? root).appendChild(mountElement);
+}
+
+// ── Canvas ───────────────────────────────────────────────────────────────────
+// One preview stylesheet, injected once: the page (`body`) paints the kit's page
+// background only if the kit states one - a kit whose own stylesheet carries
+// its page canvas omits `pageBackground` and the document is simply that
+// page - and any wrapper geometry the kit wants (surface fills, insets,
+// padding) rides in `canvas.extraCss`, keyed off the nodes the kit
+// declares in `mount`. The preview authors none of it.
+const PREVIEW_STYLE_ID = `${canvas.namePrefix}-preview-canvas`;
+const classAttribute = `data-${canvas.namePrefix}-preview-class`;
+
+// A scroll that reaches a frame's edge ends there: chained on to the host, it
+// would scroll or bounce the shell around the pane.
+const OVERSCROLL = `html { overscroll-behavior: contain; }`;
+
+function ensureCanvasStyle(): void {
+  if (document.getElementById(PREVIEW_STYLE_ID)) return;
+  // A custom view's iframe has its own canvas: the kit's `viewCanvas`,
+  // else the page background alone, since the component canvas's extra CSS
+  // styles a mount wrapper a view does not have.
+  const pageCanvas = new URLSearchParams(location.search).has('view')
+    ? (previewViewCanvas ?? { pageBackground: canvas.pageBackground })
+    : canvas;
+  const style = document.createElement('style');
+  style.id = PREVIEW_STYLE_ID;
+  if (codeFrame) {
+    // The page background alone, under a mount that fills the frame.
+    style.textContent = [
+      OVERSCROLL,
+      `html, body, #app { height: 100%; }`,
+      `body { margin: 0; }`,
+      ...(canvas.pageBackground
+        ? [`body { background: ${canvas.pageBackground}; }`]
+        : []),
+    ].join('\n');
+    document.head.appendChild(style);
+    return;
+  }
+  style.textContent = [
+    OVERSCROLL,
+    `body { min-height: 100vh; }`,
+    ...(pageCanvas.pageBackground
+      ? [`body { background: ${pageCanvas.pageBackground}; }`]
+      : []),
+    ...(pageCanvas.extraCss ? [pageCanvas.extraCss] : []),
+  ].join('\n');
+  document.head.appendChild(style);
+}
+
+// Build the wrapper, load the default theme + canvas stylesheet, and paint the
+// options' defaults - all at module init, before the host sends its globals, so
+// the first paint is fully styled. globals.ts runs at import, ahead of each
+// entry's `createRoot`/`mount`, and `getElementById('app')` resolves after the
+// reparent.
+if (defaultTheme) setTheme(defaultTheme);
+buildMountWrapper();
+ensureCanvasStyle();
+applyGlobals(optionDefaults(previewOptions));
+
+// Story links are illustrations. A real navigation would load whatever the
+// static server serves at that path INSIDE the pane - for the host's own
+// document, the preview recursively - so every non-hash link click is made
+// inert. Capture-phase, so a story component that stops propagation cannot
+// reintroduce the navigation; preventDefault kills only the navigation, the
+// component's own click handling still runs.
+document.addEventListener(
+  'click',
+  (event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const anchor = target?.closest('a[href]');
+    if (!anchor) return;
+    const href = anchor.getAttribute('href') ?? '';
+    if (href.startsWith('#')) return;
+    event.preventDefault();
+  },
+  { capture: true }
+);
+
+function elementForTarget(target: ApplyTarget): HTMLElement | null {
+  if (target === 'root') return document.documentElement;
+  if (target === 'body') return document.body;
+  return referencedElements[target.ref] ?? null;
+}
+
+/** An option value as an attribute or property value: `false`, empty or
+ *  unset clears it (`undefined`); anything else is its string form. */
+function settableValue(
+  value: OptionValue | null | undefined
+): string | undefined {
+  if (value === false || value === '' || value == null) return undefined;
+  return String(value);
+}
+
+function setOrRemoveAttribute(
+  element: HTMLElement,
+  name: string,
+  value: OptionValue
+): void {
+  const settable = settableValue(value);
+  if (settable === undefined) element.removeAttribute(name);
+  else element.setAttribute(name, settable);
+}
+
+function applyOne(option: PreviewOption, value: OptionValue): void {
+  const apply = option.apply;
+  switch (apply.type) {
+    case 'root-attribute': {
+      const element = elementForTarget(apply.target ?? 'root');
+      if (!element) break;
+      if (apply.omitAtDefault === true && value === option.default) {
+        element.removeAttribute(apply.attribute);
+      } else {
+        setOrRemoveAttribute(element, apply.attribute, value);
+      }
+      break;
+    }
+    case 'stylesheet':
+      if (typeof value === 'string' && value) setTheme(value);
+      break;
+    case 'class': {
+      const element = elementForTarget(apply.target ?? apply.on ?? 'root');
+      if (!element) break;
+      if (apply.className)
+        element.classList.toggle(apply.className, Boolean(value));
+      else setOrRemoveAttribute(element, classAttribute, value);
+      break;
+    }
+    case 'css-var': {
+      const element = elementForTarget(apply.target ?? 'root');
+      if (!element) break;
+      const settable = settableValue(value);
+      if (settable === undefined) element.style.removeProperty(apply.var);
+      else element.style.setProperty(apply.var, settable);
+      break;
+    }
+  }
+}
+
+/** Apply an options payload (id → value) to the preview document. Unknown ids and
+ *  ids not in the payload are ignored, so partial payloads are safe. */
+export function applyGlobals(
+  options: Record<string, OptionValue> | undefined
+): void {
+  if (!options) return;
+  for (const [id, value] of Object.entries(options)) {
+    const option = optionsById[id];
+    if (option && !(codeFrame && option.scope === 'story'))
+      applyOne(option, value);
+  }
+}

package/application/preview/html/main.ts

@@ -0,0 +1,93 @@
+// Html preview entry. Shows the markup a story renders to, as the host sends
+// it, under what every story pane has: the kit's theme stylesheet, its canvas,
+// its mount wrapper and its option values (globals.ts), with the stylesheets
+// the kit lists for it (`htmlStylesheets`) and the styles the kit's build
+// wrote for the components the markup renders, which arrive with it. No
+// framework loads and no setup module runs: the markup is the kit's html at
+// rest, and the pane runs none of the story's behavior. Html mode writes a
+// declared event as a comment, so it does nothing; markup that carries
+// behavior of its own (a script, an inline handler, a `javascript:` URL) has
+// it taken out before it shows, and a form's submission is stopped, as
+// globals.ts stops a link's navigation. While the next markup is printed the
+// pane keeps what it shows; a story with none shows why.
+import '@preview-html-stylesheets';
+import { applyGlobals } from '../globals';
+import {
+  announcePreviewReady,
+  announcePreviewShown,
+  PREVIEW_MESSAGE,
+  PREVIEW_MOUNT_ELEMENT_ID,
+  readPreviewMessage,
+  reportContentSize,
+} from '../../../src/protocol';
+
+const mount = document.getElementById(PREVIEW_MOUNT_ELEMENT_ID)!;
+
+/** The attribute the pane marks its note with, when a story has no html. */
+const UNAVAILABLE_ATTRIBUTE = 'data-preview-html-unavailable';
+
+/** Elements that would run code or load a document of their own. */
+const ACTIVE_ELEMENTS = 'script, iframe, object, embed, frame, frameset';
+
+/** Attributes whose value a browser may run as a script. */
+const URL_ATTRIBUTES = new Set(['href', 'src', 'action', 'formaction', 'xlink:href']);
+
+/** Take out of `fragment` whatever would run: scripts and embedded
+ *  documents, inline event handlers and `javascript:` URLs. */
+function makeInert(fragment: DocumentFragment): void {
+  for (const element of fragment.querySelectorAll(ACTIVE_ELEMENTS)) element.remove();
+  for (const element of fragment.querySelectorAll('*')) {
+    for (const attribute of [...element.attributes]) {
+      const name = attribute.name.toLowerCase();
+      const runs =
+        name.startsWith('on') ||
+        (URL_ATTRIBUTES.has(name) && /^\s*javascript:/i.test(attribute.value));
+      if (runs) element.removeAttribute(attribute.name);
+    }
+  }
+}
+
+/** The element the styles of the shown markup's components are set in,
+ *  after the theme's and the kit's stylesheets. */
+const componentStyle = document.createElement('style');
+componentStyle.setAttribute('data-preview-html-components', '');
+document.head.appendChild(componentStyle);
+
+function showMarkup(markup: string, stylesheet: string): void {
+  if (componentStyle.textContent !== stylesheet) componentStyle.textContent = stylesheet;
+  const template = document.createElement('template');
+  template.innerHTML = markup;
+  makeInert(template.content);
+  mount.replaceChildren(template.content);
+  mount.removeAttribute('aria-busy');
+}
+
+function showReason(reason: string): void {
+  const note = document.createElement('p');
+  note.setAttribute(UNAVAILABLE_ATTRIBUTE, '');
+  note.textContent = reason;
+  mount.replaceChildren(note);
+  mount.removeAttribute('aria-busy');
+}
+
+// A form in the markup is an illustration: submitting it would load whatever
+// its action names inside the pane.
+document.addEventListener('submit', (event) => event.preventDefault(), { capture: true });
+
+window.addEventListener('message', (event: MessageEvent) => {
+  const message = readPreviewMessage(event.data);
+  if (!message) return;
+  if (message.type === PREVIEW_MESSAGE.globals) applyGlobals(message.options);
+  else if (message.type === PREVIEW_MESSAGE.markup) {
+    if (typeof message.markup === 'string')
+      showMarkup(message.markup, typeof message.stylesheet === 'string' ? message.stylesheet : '');
+    else if (typeof message.reason === 'string') showReason(message.reason);
+    else mount.setAttribute('aria-busy', 'true');
+    // The first markup or reason, once painted, lets the host show the pane.
+    if (typeof message.markup === 'string' || typeof message.reason === 'string') announcePreviewShown();
+  }
+});
+
+announcePreviewReady();
+// The story's size reaches the host on each change, so a shell can size the pane to it.
+reportContentSize(mount);

package/application/preview/html/preview.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>preview - html</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>