# Inferway Studio — embedded editor dist (Studio L3b)

Where the pinned ComfyUI frontend build lives, why it lives there, how to
produce it, and what it costs.

## The decision

**The dist is NOT in the repository.** It is fetched at build time from PyPI,
sha256-verified before extraction, and written to
`website/public/console/studio/editor/` — which is git-ignored. Three reasons:

1. **Size.** 970 files / ~91 MB (92,532,537 bytes) of third-party static
   assets does not belong in a git history, and it would be re-shipped in
   every clone, worktree and CI checkout.
2. **Provenance.** The wheel's sha256 is pinned in
   `scripts/studio-editor.lock.json` (version 1.51.10, upstream tag
   `v1.51.10`). Verification happens before a byte is extracted, so the dist on
   disk is either exactly the pinned wheel's `static/` tree or the build fails.
   A committed copy could silently drift.
3. **Licence handling.** The upstream component is GPL-3.0. It is shipped
   beside Inferway's own additions, with `LICENSE.txt` and `NOTICE.md` copied
   into the dist by the build — see `NOTICE.md` in this directory.

**Placement.** `website/public/` is Next's static root, so the dist is served
at `/console/studio/editor/**` — a prefix that only ever returns public static
files (no dynamic handler, `Access-Control-Allow-Origin: *` without a
credentials mode, one CSP carrying `sandbox allow-scripts`, requirement 1/2/4).
The iframe `src` points at `index.html`: there is no directory index. The dist
is not part of the Next route tree, so it does not enter the perf-budget gate.

**Isolation** is the spike's S1hdr verdict: same origin, opaque origin in the
document (response CSP `sandbox allow-scripts` + the same `sandbox` attribute on
the iframe), everything interesting crossing a `postMessage` bridge. See
`inferway-shim.js` for what the frame may and may not do.

## How to enable

```bash
cd website
INFERWAY_STUDIO_EDITOR_BUILD=1 bun run build     # fetch + verify + inject + copy + verify
bun run build                                     # unchanged: the hook prints one line and exits 0
```

The hook is `scripts/studio-editor-build.mjs`, wired as `prebuild` in
`package.json`, so it runs before every `next build` (laptop, CI, Vercel).

- **`INFERWAY_STUDIO_EDITOR_BUILD` unset (the default, and production today):**
  one line on stdout, exit 0, **no network access and no filesystem changes**.
  Nothing new is served under `/console/studio/editor/`.
- **`INFERWAY_STUDIO_EDITOR_BUILD=1`:** runs `scripts/studio-editor-fetch.mjs`
  (wheel sha256 verified before extraction), injects the single
  `<script src="./inferway-shim.js"></script>` line as the first element of
  `<head>` (idempotent), copies `inferway-shim.js`,
  `inferway-bridge-protocol.js`, `LICENSE.txt` and `NOTICE.md`, then verifies
  the file count against the lock, that `index.html` still equals the
  upstream file once the injected line is stripped, and that **every file in
  the dist matches `static-files.sha256`** (one `sha256␠␠path` line per
  shipped file). Any failure exits non-zero and fails the build.

Enabling it is a separate, later decision: it changes what is deployed, not how
the site builds today.

## Licence and static file inventory

- **Licence.** The upstream component is GPL-3.0:
  `LICENSE.comfyui-frontend-v1.51.10.txt` is the licence text of tag `v1.51.10`
  (35,149 bytes, sha256 `3972dc9744f6499f0f9b2dbf76696f2ae7ad8af9b23dde66d6af86c9dfb36986`,
  also pinned as `license` in `scripts/studio-editor.lock.json`). The build
  copies it into the dist as `LICENSE.txt`, next to `NOTICE.md`, which states
  in English and 中文 what Inferway changed: one injected `<script>` line in
  `index.html` plus four added files, nothing else.
- **Inventory.** `static-files.sha256` lists every file the dist ships —
  974 lines today: the wheel's 970 upstream files (including the injected
  `index.html`) plus `inferway-shim.js`, `inferway-bridge-protocol.js`,
  `LICENSE.txt` and `NOTICE.md` — as `<sha256>␠␠relative/path`, sorted by path.
  A gated build verifies the whole list and fails on the first disagreement.
  After a deliberate upstream bump, regenerate it in one command:

```bash
cd website
INFERWAY_STUDIO_EDITOR_BUILD=1 node scripts/studio-editor-build.mjs --write-inventory
```

## Cost of enabling

- **~91 MB and 970 files** in the deployment (92,532,537 bytes extracted; the
  hook adds 4 files on top), plus the wheel download on a cold cache.
- **970 static requests** on a cold cache for a full editor boot — the
  practical cost is cache strategy, not bundle size (the dist never enters a
  Next route, so no first-load JS budget is affected).
- The editor makes **no API request**: `api/*` is intercepted in the frame and
  answered by `src/lib/studioBridge.ts` over `postMessage`; run/queue/prompt
  answer a fixed "not available", so the embedded editor can never spend.

## Files

| File | Role |
|---|---|
| `inferway-shim.js` | Injected into the frame; storage/cookie/request/dialog/download/clipboard adapter (its own source, served unminified) |
| `inferway-bridge-protocol.js` | Closed message-type list, schema validation, size caps; classic script shared with the parent side |
| `NOTICE.md` | Upstream provenance + exactly what Inferway changed (English and 中文), copied into the dist |
| `LICENSE.comfyui-frontend-v1.51.10.txt` | Upstream GPL-3.0 text from tag `v1.51.10`, copied into the dist as `LICENSE.txt` |
| `static-files.sha256` | Inventory of every file the dist ships: `<sha256>␠␠path`, verified on each gated build (`--write-inventory` regenerates) |
| `__tests__/` | Unit tests for the shim and the protocol (run by `bun run test`) |
| `../scripts/studio-editor-build.mjs` | The build hook described above |
| `../scripts/studio-editor-fetch.mjs` / `studio-editor.lock.json` | Pinned fetch + verification (slice 1) |
| `../src/lib/studioBridge.ts` | The parent side of the bridge and the default answer table |

## Acceptance for this slice

- `bun run test` — shim, protocol, bridge and build-hook tests.
- `INFERWAY_STUDIO_EDITOR_BUILD=1 bun run build` — the real dist, verified.
- `bunx playwright test e2e/studio-editor-bridge.spec.ts` — boots the real dist
  in a sandboxed iframe against a local 127.0.0.1 server and proves: canvas
  non-zero, 0 real requests and 0 preflights to `editor/api/*`, 0 WebSockets,
  0 requests to any other host, no uncaught page error, isolation probes still
  fail, and that a download and a clipboard write reach the parent handlers.