@onlook/storybook-plugin 0.4.0-beta.1 → 0.4.0-beta.10

package/dist/preview/index.d.ts

@@ -0,0 +1,156 @@
+import * as React from 'react';
+
+/** Advertised + embedded in every event payload. Mirrored CLI-side (U8). */
+declare const ONLOOK_CONTAINMENT_CONTRACT_VERSION = 1;
+/** Marker attached to every contained export, thrown error, and the global registry. */
+type ContainedModuleMarker = {
+    modulePath: string;
+    reason: 'env-validation';
+    envKeys: string[];
+    schemaKind?: string;
+};
+/**
+ * Handshake global, set by the preview annotations (in `beforeAll` and again
+ * defensively when the decorator first runs):
+ * `globalThis.__ONLOOK_CONTAINMENT_CONTRACT__ = { version: 1 }`.
+ */
+declare const ONLOOK_CONTAINMENT_CONTRACT_GLOBAL = "__ONLOOK_CONTAINMENT_CONTRACT__";
+type OnlookContainmentContract = {
+    version: number;
+};
+/**
+ * Emitted when the error-boundary decorator catches a render-time throw and
+ * renders the "needs setup" card in place of the story.
+ */
+declare const ONLOOK_CONTAINED_EVENT = "onlook/contained";
+/**
+ * Emitted once per story mount, after the boundary's children committed
+ * without throwing. The verifier must key `rendered` on THIS (plus absence of
+ * Storybook error events) — never on `STORY_RENDERED` alone, which Storybook
+ * fires even after its own boundary catches.
+ */
+declare const ONLOOK_RENDERED_EVENT = "onlook/rendered";
+/**
+ * Tag-for-verifier re-emit of errors the boundary cannot catch (loader /
+ * `beforeEach` / module-load throws surface as Storybook's
+ * `storyThrewException` / `storyErrored` channel events, outside the React
+ * render). These remain overlay-not-card; no DOM repaint is attempted.
+ */
+declare const ONLOOK_UNCONTAINED_ERROR_EVENT = "onlook/uncontained-error";
+type OnlookContainedPayload = {
+    storyId: string;
+    contractVersion: number;
+    /** Trimmed failure summary (error message). */
+    message: string;
+    /** Present when the failure is attributed to a contained module (U4). */
+    module?: ContainedModuleMarker;
+};
+type OnlookRenderedPayload = {
+    storyId: string;
+    contractVersion: number;
+};
+type OnlookUncontainedErrorPayload = {
+    /** Best-effort (read from the preview iframe URL); absent when unknown. */
+    storyId?: string;
+    contractVersion: number;
+    message: string;
+    /** Which Storybook channel event this re-emits. */
+    source: 'storyThrewException' | 'storyErrored';
+};
+/**
+ * Render-state attribute, value `'rendered' | 'contained'`. Set on
+ * `#storybook-root` (falling back to `document.body` when absent) after each
+ * boundary commit, and ALSO carried on the card's own wrapper element when
+ * contained. Cleared on boundary unmount (story switch), so a stale value
+ * never leaks into the next story's mount — verifiers should match it
+ * together with `data-onlook-story-id`.
+ */
+declare const ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+/** Companion attribute carrying the story id the render state belongs to. */
+declare const ONLOOK_RENDER_STORY_ATTR = "data-onlook-story-id";
+/** Present (empty value) on the "needs setup" card's wrapper element. */
+declare const ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+type OnlookRenderState = 'rendered' | 'contained';
+
+type ContainmentCardProps = {
+    storyId: string;
+    storyLabel: string;
+    message: string;
+    module?: ContainedModuleMarker;
+};
+declare function ContainmentCard(props: ContainmentCardProps): React.ReactElement;
+type BoundaryProps = {
+    storyId: string;
+    storyLabel: string;
+    children?: React.ReactNode;
+};
+type BoundaryState = {
+    error: unknown;
+    hasError: boolean;
+};
+declare class OnlookContainmentBoundary extends React.Component<BoundaryProps, BoundaryState> {
+    private renderedSignalSent;
+    constructor(props: BoundaryProps);
+    static getDerivedStateFromError(error: unknown): BoundaryState;
+    componentDidCatch(error: unknown): void;
+    componentDidMount(): void;
+    componentDidUpdate(): void;
+    componentWillUnmount(): void;
+    private signalRenderedIfClean;
+    render(): React.ReactNode;
+}
+type StoryContextLike = {
+    id?: string;
+    title?: string;
+    name?: string;
+};
+/**
+ * The project-level decorator delivered through the addon `./preview` entry.
+ * Keyed by story id so switching stories remounts the boundary (resetting
+ * caught-error state and re-arming the once-per-mount rendered signal).
+ */
+declare function onlookContainmentDecorator(Story: unknown, context?: StoryContextLike): React.ReactElement;
+
+type ChannelLike = {
+    emit: (event: string, payload?: unknown) => void;
+    on?: (event: string, listener: (payload?: unknown) => void) => void;
+};
+/**
+ * The preview channel. Prefers `window.__STORYBOOK_ADDONS_CHANNEL__` (set by
+ * builder-vite's setup code before any addon preview annotation loads), then
+ * the global-backed preview addon store — but only when it already HAS a
+ * channel (calling `getChannel()` earlier would install a mock and clobber
+ * Storybook's own setup). `null` when Storybook hasn't wired one (e.g. tests,
+ * portable stories).
+ */
+declare function getPreviewChannel(): ChannelLike | null;
+/**
+ * Snapshot tooling detection (Chromatic's documented `isChromatic()` check).
+ * The vite-plugin half of this package self-disables under `process.env.CI ||
+ * CHROMATIC`; the preview half can't see those env vars in the browser, so it
+ * keys on Chromatic's user agent / URL marker. When true we keep the boundary
+ * behavior (the card still renders deterministically) but skip the dynamic
+ * signals — channel events and root-element attribute writes — so snapshots
+ * stay byte-stable.
+ */
+declare function isSnapshotEnvironment(): boolean;
+/**
+ * Attribute an error to a contained module (U4's env-containment stand-ins).
+ * Primary: the marker the stand-in attaches at `error.__onlookContained`.
+ * Fallback: scan the `globalThis.__ONLOOK_CONTAINED_MODULES__` registry for a
+ * marker whose modulePath appears in the error message (covers errors
+ * re-wrapped by customer code that drops custom properties).
+ */
+declare function attributeErrorToModule(error: unknown): ContainedModuleMarker | undefined;
+declare function installUncontainedErrorRelay(channel?: ChannelLike | null): void;
+/**
+ * The preview annotations' `beforeAll` — runs once when the preview boots,
+ * before any story (and before any loader can throw). Advertises the
+ * handshake global and installs the uncontained-error relay.
+ */
+declare function onlookBeforeAll(): void;
+
+declare const decorators: (typeof onlookContainmentDecorator)[];
+declare const beforeAll: typeof onlookBeforeAll;
+
+export { ContainmentCard, ONLOOK_CONTAINED_CARD_ATTR, ONLOOK_CONTAINED_EVENT, ONLOOK_CONTAINMENT_CONTRACT_GLOBAL, ONLOOK_CONTAINMENT_CONTRACT_VERSION, ONLOOK_RENDERED_EVENT, ONLOOK_RENDER_STATE_ATTR, ONLOOK_RENDER_STORY_ATTR, ONLOOK_UNCONTAINED_ERROR_EVENT, type OnlookContainedPayload, OnlookContainmentBoundary, type OnlookContainmentContract, type OnlookRenderState, type OnlookRenderedPayload, type OnlookUncontainedErrorPayload, attributeErrorToModule, beforeAll, decorators, getPreviewChannel, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator };

package/dist/preview/index.js

@@ -0,0 +1,302 @@
+import * as React from 'react';
+
+// src/preview/containment-boundary.ts
+
+// src/containment-contract/containment-contract.ts
+var ONLOOK_CONTAINMENT_CONTRACT_VERSION = 1;
+var ONLOOK_CONTAINED_MODULES_GLOBAL = "__ONLOOK_CONTAINED_MODULES__";
+var ONLOOK_CONTAINED_PROP = "__onlookContained";
+var ONLOOK_CONTAINMENT_CONTRACT_GLOBAL = "__ONLOOK_CONTAINMENT_CONTRACT__";
+var ONLOOK_CONTAINED_EVENT = "onlook/contained";
+var ONLOOK_RENDERED_EVENT = "onlook/rendered";
+var ONLOOK_UNCONTAINED_ERROR_EVENT = "onlook/uncontained-error";
+var ONLOOK_RENDER_STATE_ATTR = "data-onlook-render-state";
+var ONLOOK_RENDER_STORY_ATTR = "data-onlook-story-id";
+var ONLOOK_CONTAINED_CARD_ATTR = "data-onlook-contained-card";
+
+// src/preview/signals.ts
+var STORYBOOK_STORY_THREW_EXCEPTION = "storyThrewException";
+var STORYBOOK_STORY_ERRORED = "storyErrored";
+function globalScope() {
+  return globalThis;
+}
+function getPreviewChannel() {
+  const g = globalScope();
+  const direct = g.__STORYBOOK_ADDONS_CHANNEL__;
+  if (direct && typeof direct.emit === "function") return direct;
+  const store = g.__STORYBOOK_ADDONS_PREVIEW;
+  if (store && typeof store.hasChannel === "function" && store.hasChannel() && typeof store.getChannel === "function") {
+    return store.getChannel();
+  }
+  return null;
+}
+function isSnapshotEnvironment() {
+  try {
+    const w = globalScope().window;
+    if (!w) return false;
+    if (/Chromatic/.test(w.navigator?.userAgent ?? "")) return true;
+    if (/chromatic=true/.test(w.location?.href ?? "")) return true;
+  } catch {
+  }
+  return false;
+}
+function exposeContract() {
+  globalScope()[ONLOOK_CONTAINMENT_CONTRACT_GLOBAL] = {
+    version: ONLOOK_CONTAINMENT_CONTRACT_VERSION
+  };
+}
+function signalElement() {
+  if (typeof document === "undefined") return null;
+  return document.getElementById("storybook-root") ?? document.body ?? null;
+}
+function setRenderState(state, storyId) {
+  if (isSnapshotEnvironment()) return;
+  try {
+    const el = signalElement();
+    if (!el) return;
+    el.setAttribute(ONLOOK_RENDER_STATE_ATTR, state);
+    el.setAttribute(ONLOOK_RENDER_STORY_ATTR, storyId);
+  } catch {
+  }
+}
+function clearRenderState(storyId) {
+  try {
+    const el = signalElement();
+    if (!el) return;
+    if (el.getAttribute(ONLOOK_RENDER_STORY_ATTR) !== storyId) return;
+    el.removeAttribute(ONLOOK_RENDER_STATE_ATTR);
+    el.removeAttribute(ONLOOK_RENDER_STORY_ATTR);
+  } catch {
+  }
+}
+function emit(event, payload) {
+  if (isSnapshotEnvironment()) return;
+  try {
+    getPreviewChannel()?.emit(event, payload);
+  } catch {
+  }
+}
+function emitContained(payload) {
+  emit(ONLOOK_CONTAINED_EVENT, payload);
+}
+function emitRendered(storyId) {
+  emit(ONLOOK_RENDERED_EVENT, {
+    storyId,
+    contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION
+  });
+}
+function summarizeError(error, maxLength = 400) {
+  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : String(error);
+  const oneline = raw.trim();
+  return oneline.length > maxLength ? `${oneline.slice(0, maxLength - 1)}\u2026` : oneline;
+}
+function attributeErrorToModule(error) {
+  if (error && typeof error === "object") {
+    const direct = error[ONLOOK_CONTAINED_PROP];
+    if (isMarker(direct)) return direct;
+  }
+  const registry = globalScope()[ONLOOK_CONTAINED_MODULES_GLOBAL];
+  if (!registry) return void 0;
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  if (!message) return void 0;
+  for (const candidate of Object.values(registry)) {
+    if (isMarker(candidate) && message.includes(candidate.modulePath)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function isMarker(value) {
+  return value !== null && typeof value === "object" && typeof value.modulePath === "string" && value.reason === "env-validation";
+}
+var INSTALLED_CHANNELS = /* @__PURE__ */ new WeakSet();
+function currentStoryId() {
+  try {
+    const w = globalScope().window;
+    const search = w?.location?.search;
+    if (!search) return void 0;
+    return new URLSearchParams(search).get("id") ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function relayPayload(source, raw) {
+  const obj = raw ?? {};
+  const message = typeof obj.message === "string" ? obj.message : typeof obj.description === "string" ? obj.description : typeof obj.title === "string" ? obj.title : summarizeError(raw);
+  const storyId = currentStoryId();
+  return {
+    ...storyId ? { storyId } : {},
+    contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
+    message: summarizeError(message),
+    source
+  };
+}
+function installUncontainedErrorRelay(channel = getPreviewChannel()) {
+  if (!channel || typeof channel.on !== "function") return;
+  if (INSTALLED_CHANNELS.has(channel)) return;
+  INSTALLED_CHANNELS.add(channel);
+  channel.on(STORYBOOK_STORY_THREW_EXCEPTION, (payload) => {
+    emit(ONLOOK_UNCONTAINED_ERROR_EVENT, relayPayload("storyThrewException", payload));
+  });
+  channel.on(STORYBOOK_STORY_ERRORED, (payload) => {
+    emit(ONLOOK_UNCONTAINED_ERROR_EVENT, relayPayload("storyErrored", payload));
+  });
+}
+function onlookBeforeAll() {
+  exposeContract();
+  installUncontainedErrorRelay();
+}
+
+// src/preview/containment-boundary.ts
+var cardStyles = {
+  wrapper: {
+    boxSizing: "border-box",
+    fontFamily: "ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+    color: "#1f2937",
+    background: "#fafaf9",
+    border: "1px solid #e7e5e4",
+    borderRadius: "12px",
+    padding: "20px 24px",
+    margin: "16px",
+    maxWidth: "560px",
+    lineHeight: 1.5
+  },
+  badge: {
+    display: "inline-block",
+    fontSize: "11px",
+    fontWeight: 600,
+    letterSpacing: "0.04em",
+    textTransform: "uppercase",
+    color: "#92400e",
+    background: "#fef3c7",
+    borderRadius: "999px",
+    padding: "2px 10px",
+    marginBottom: "10px"
+  },
+  title: {
+    fontSize: "15px",
+    fontWeight: 600,
+    margin: "0 0 6px"
+  },
+  detail: {
+    fontSize: "13px",
+    margin: "0 0 10px",
+    color: "#44403c"
+  },
+  message: {
+    fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+    fontSize: "12px",
+    whiteSpace: "pre-wrap",
+    wordBreak: "break-word",
+    color: "#7f1d1d",
+    background: "#fef2f2",
+    border: "1px solid #fee2e2",
+    borderRadius: "8px",
+    padding: "10px 12px",
+    margin: "0 0 10px"
+  },
+  footer: {
+    fontSize: "12px",
+    margin: 0,
+    color: "#78716c"
+  }
+};
+var h = React.createElement;
+function ContainmentCard(props) {
+  const { storyId, storyLabel, message, module } = props;
+  const moduleDetail = module ? h(
+    "p",
+    { style: cardStyles.detail, key: "module" },
+    `This story imports `,
+    h("code", null, module.modulePath),
+    module.envKeys.length > 0 ? `, which validates environment variables at load time. Missing: ${module.envKeys.join(", ")}.` : ", which could not load in this environment."
+  ) : null;
+  return h(
+    "div",
+    {
+      [ONLOOK_CONTAINED_CARD_ATTR]: "",
+      [ONLOOK_RENDER_STATE_ATTR]: "contained",
+      [ONLOOK_RENDER_STORY_ATTR]: storyId,
+      role: "alert",
+      style: cardStyles.wrapper
+    },
+    h("span", { style: cardStyles.badge, key: "badge" }, "Needs setup"),
+    h("h2", { style: cardStyles.title, key: "title" }, `${storyLabel} can't render yet`),
+    moduleDetail,
+    message ? h("pre", { style: cardStyles.message, key: "message" }, message) : null,
+    h(
+      "p",
+      { style: cardStyles.footer, key: "footer" },
+      "Onlook contained this error so the rest of Storybook keeps working."
+    )
+  );
+}
+var OnlookContainmentBoundary = class extends React.Component {
+  // `onlook/rendered` fires once per story mount — re-renders of a healthy
+  // story (arg updates) don't re-emit.
+  renderedSignalSent = false;
+  constructor(props) {
+    super(props);
+    this.state = { error: null, hasError: false };
+  }
+  static getDerivedStateFromError(error) {
+    return { error, hasError: true };
+  }
+  componentDidCatch(error) {
+    const module = attributeErrorToModule(error);
+    setRenderState("contained", this.props.storyId);
+    emitContained({
+      storyId: this.props.storyId,
+      contractVersion: ONLOOK_CONTAINMENT_CONTRACT_VERSION,
+      message: summarizeError(error),
+      ...module ? { module } : {}
+    });
+  }
+  componentDidMount() {
+    exposeContract();
+    this.signalRenderedIfClean();
+  }
+  componentDidUpdate() {
+    this.signalRenderedIfClean();
+  }
+  componentWillUnmount() {
+    clearRenderState(this.props.storyId);
+  }
+  signalRenderedIfClean() {
+    if (this.state.hasError || this.renderedSignalSent) return;
+    this.renderedSignalSent = true;
+    setRenderState("rendered", this.props.storyId);
+    emitRendered(this.props.storyId);
+  }
+  render() {
+    if (this.state.hasError) {
+      return h(ContainmentCard, {
+        storyId: this.props.storyId,
+        storyLabel: this.props.storyLabel,
+        message: summarizeError(this.state.error),
+        module: attributeErrorToModule(this.state.error)
+      });
+    }
+    return this.props.children;
+  }
+};
+function storyLabelFrom(context) {
+  const title = context.title?.split("/").pop();
+  if (title && context.name) return `${title} \xB7 ${context.name}`;
+  return title ?? context.name ?? context.id ?? "This story";
+}
+function onlookContainmentDecorator(Story, context) {
+  const ctx = context ?? {};
+  const storyId = ctx.id ?? "unknown";
+  return h(
+    OnlookContainmentBoundary,
+    { key: storyId, storyId, storyLabel: storyLabelFrom(ctx) },
+    h(Story)
+  );
+}
+
+// src/preview/index.ts
+var decorators = [onlookContainmentDecorator];
+var beforeAll = onlookBeforeAll;
+
+export { ContainmentCard, ONLOOK_CONTAINED_CARD_ATTR, ONLOOK_CONTAINED_EVENT, ONLOOK_CONTAINMENT_CONTRACT_GLOBAL, ONLOOK_CONTAINMENT_CONTRACT_VERSION, ONLOOK_RENDERED_EVENT, ONLOOK_RENDER_STATE_ATTR, ONLOOK_RENDER_STORY_ATTR, ONLOOK_UNCONTAINED_ERROR_EVENT, OnlookContainmentBoundary, attributeErrorToModule, beforeAll, decorators, getPreviewChannel, installUncontainedErrorRelay, isSnapshotEnvironment, onlookBeforeAll, onlookContainmentDecorator };

package/dist/screenshot-service/index.d.ts

@@ -1,12 +1,6 @@
 export { closeBrowser } from './utils/browser/index.js';
 import 'playwright';
 
-/**
- * Generate screenshots for all stories (parallelized for speed)
- *
- * @param offset - Absolute index offset for logging (e.g. skip=200 → offset=200)
- * @param total - Total number of stories across all runs (for [n/total] logging)
- */
 declare function generateAllScreenshots(stories: Array<{
     id: string;
     importPath: string;