# Pattern Iframe

> Build or generate a Common Fabric pattern whose primary UI is a self-contained `cf-iframe` guest. Use when an agent should turn an input-data shape and a small state/output contract into a working iframe-first pattern without learning the broader pattern framework, including plain DOM, React, D3, Phaser 2D games, Babylon.js 3D scenes, PerSpace/PerUser/PerSession data, path-scoped Cell access, stable array-item handles, mergeable pushes, or bridged SQLite.

- Skill: `commontoolsinc/pattern-iframe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add commontoolsinc/pattern-iframe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/commontoolsinc/pattern-iframe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: commontoolsinc (https://skillmd.com/u/commontoolsinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/commontoolsinc/pattern-iframe

---


# Iframe-first patterns

Choose one self-contained authoring contract before writing code. Route by the
primary rendering owner, in this order:

- For a 3D game, world, simulation, or WebGL scene, read
  `docs/common/ai/iframe-pattern-babylon-guide.md` in full.
- For a primarily 2D HTML5 game, read
  `docs/common/ai/iframe-pattern-phaser-guide.md` in full.
- For a data visualization whose DOM or SVG is owned by D3, read
  `docs/common/ai/iframe-pattern-d3-guide.md` in full.
- For a React component tree, hooks, an explicitly requested React guest, or a
  stateful React-only editor, diagram, grid, or canvas library, read
  `docs/common/ai/iframe-pattern-react-guide.md` in full. It owns the boundary
  between durable Fabric data, React drafts, and library-managed interaction
  state.
- Otherwise read `docs/common/ai/iframe-pattern-guide.md` in full for a plain
  DOM guest.

For an explicit hybrid, choose the guide for the framework that owns the DOM or
canvas lifecycle. Load a second guide only when the request genuinely combines
two owners, such as React mounting and unmounting a D3-managed subtree. Do not
load the general pattern-development guides unless the requested behavior
extends beyond the generated wrapper.

Keep the authored surface small:

- Put the files under `packages/patterns/iframe-<name>/`. The `iframe-` prefix
  is load-bearing: pattern discovery uses it to recognize `guest.ts` and
  `guest.tsx` as browser sources rather than additional pattern entries.
- `contract.ts` names the input, durable state, and output data shapes and their
  defaults.
- `guest.ts` or `guest.tsx` owns the application. It may use plain DOM code or
  React and the guest bridge.
- `main.tsx` is generated glue. Do not hand-edit it.
- One joint initial `pull()` barrier owns readiness for every resource an action
  uses. Keep action controls disabled until it resolves; an individual
  synchronous `sink()` callback must never declare the guest ready.

Generate the wrapper with:

```bash
deno run -A tools/write-iframe-wrapper.ts \
  --contract packages/patterns/iframe-<name>/contract.ts \
  --guest packages/patterns/iframe-<name>/guest.ts \
  --out packages/patterns/iframe-<name>/main.tsx
```

Add `--react` when the authored guest is React TSX, as required by the React
guide.

Add `--html packages/patterns/iframe-<name>/guest.html` when the guest needs a
custom document shell, and `--force` only when regenerating the named output.
The HTML shell must contain `<!-- PATTERN_IFRAME_SCRIPT -->` exactly once.

Validate the generated pattern with:

```bash
deno fmt packages/patterns/iframe-<name>
deno check packages/patterns/iframe-<name>/<guest-file>
deno task cf check packages/patterns/iframe-<name>/main.tsx --no-run
```

Replace `<guest-file>` with the authored `guest.ts` or `guest.tsx` filename.

Run the pattern or add a focused test when behavior, rather than only its data
contract, changed. Preserve `contract.ts` and the guest source beside the
generated wrapper so the pattern remains reproducible.