ID9 — r205 VSIL Composition Graph Host — AI Summary

**Date**: 2026-08-30 | **Source**: a791 (full report, 27 KB)

**Thread**: vibecoder-standalone-mavis (9) | **Operator directive**: r205 structural kickoff (r203 closed, r204 v2 decision-complete)

---

TL;DR (5 bullets)

• **VSIL Composition Graph Host (VCGH)** is a new module at `studio/modules/vibescope/src/composition/`. It introduces a new abstraction — the **Region** — that groups multiple VSIL sources into a multi-region composition with shared camera, lighting, and atmosphere.

• **6 new files, ~1,200 LoC**: `types.ts` (120 LoC), `discovery.ts` (180 LoC), `graph.ts` (250 LoC), `host.tsx` (300 LoC), `overlays/` (150 LoC), `capabilities.ts` (80 LoC). **Reuses** all 4720 LoC of existing `src/vsil/` (parser, sceneGraph, assetRegistry, inspectorExtract) + the 688 LoC Inspector + SurfaceRegistry.

• **Read-only invariant** (per inspector doctrine): the host never mutates VSIL sources directly. All mutations go through the 5-state surface state machine. Edit attempts in read-only states (MAIN / PREVIEW / ORIGIN) are silently rejected with a `composition:edit-rejected` event and an Edge Panel toast.

• **Aligned with a789 (Unified Gallery Panel)**: 2 new optional props on `PreviewHostVSIL` (`composition`, `selectedRegionIds`, `onRegionClick`) + 1 new submenu on the VSIL chip in `PreviewStrip` (VSIL → composition dropdown). Backward-compatible — existing `source`-only call sites continue to work.

• **5 surface states honored** (a789 §9): MAIN (immutable), WORKING (read-write, in-memory), DRAFT (autosaved), PREVIEW (committed, read-only), ORIGIN (deployed, read-only). The host reads state from `SurfaceRegistry.getState(surfaceId)` and emits events when the user attempts a write.

What this means for the operator

r205 is the **structural plan**, not the implementation. The 3-4 day implementation can start whenever the operator approves the plan. The 6 new files are additive — no changes to existing `src/vsil/`, no changes to a789's `PreviewHostVSIL` (only additive props), no changes to existing Inspector. The new VSIL chip submenu in `PreviewStrip` is the only visible UX change for v1.

The Region concept is the **biggest design choice**. It's the bridge between "single VSIL source" (today) and "multi-region composition" (r205+). The DOM-scanning approach (`<div data-vcg-region>`) means authors annotate their preview surface with attributes, and the host finds the regions automatically. This is a **familiar pattern** (matches `data-vibe-card-shell` for Vibe Cards, `data-fvcms-module` for FvCMS modules).

What's at risk

1. **No new pact required for v1, but recommended**: the 5 surface states from a789 cover lifecycle, but the **Region concept** itself is not in FvW v8. Optional 1h pact add: `pact/platform/vsil/composition-2026-08-30.md`. Drift-check risk: low for v1, medium if the operator wants constitutional enforcement.

2. **DOMPurify dependency**: the host needs DOMPurify for sanitization. New npm dep. Mitigated by using the well-maintained `dompurify@^3.0.0` (zero deps, audited).

3. **VibeChat prompt injection surface**: VibeChat reads `exportRegionMetadata()` to get a region snapshot. If the metadata is too large, it could blow the LLM context. Mitigated by capping snapshot size to 2KB (configurable).

Open questions (0–3 for operator)

1. **Pact file**: add `pact/platform/vsil/composition-2026-08-30.md` before implementation (1h, recommended) or defer to a follow-up? → default: defer to follow-up.

2. **Region group hierarchy**: v1 has flat groups (one string tag per region). v2 might want hierarchical groups (group inside group). v2 = out of scope for r205. → default: v1 = flat.

3. **Cross-region transforms**: v1 has per-region transforms. v2 might want "stretch all regions in group X by 1.2x". v2 = out of scope. → default: v1 = per-region only.

What doesn't change

• `src/vsil/` (4720 LoC) — parser, sceneGraph, assetRegistry, inspectorExtract, keyframeIds — all reused as-is

• `src/inspector/` (688 LoC) — Inspector proper (per a788)

• `src/state/VSILStore.ts` — single source per workspace, no change

• ID9 Gallery Panel (a789) — 2 additive props on `PreviewHostVSIL`, 1 additive submenu on `PreviewStrip`

• ID10 v2 capability layer (b1818, b1269) — `VCGH_CAPABILITIES` follows the same pattern

Discuss-with-team topics

1. **Should Region be in FvW v8 or in a new pact file?** The Region concept is novel — it extends VSIL (which is in `pact/platform/vsil/`) with a "multi-source tree" abstraction. Options: (a) add a section to `vsil.md`, (b) sibling file `composition.md`, (c) new top-level `pact/platform/composition/composition.md`. Recommend (b) — sibling file keeps `vsil.md` clean.

2. **Should the host support VibeChat prompt-driven region creation?** Today VibeChat can request transforms and apply presets. Should it also be able to **create a new region** (e.g. "add a footer region to the composition")? This is a v3 feature, NOT in r205 scope.

3. **Should `composition:region-clicked` include the parsed VSIL source in the payload?** Today it's just `{ regionId, surfaceState }`. Including the source lets VibeChat do deeper reasoning. But the source can be megabytes — payload too large. Default: no, but expose `exportRegionMetadata()` for explicit snapshots.

---

**Word count**: ~470. **Source report**: a791 (full, 27 KB). **Cross-references**: a786 (FreshCards), a787 (VPS), a788 (Inspector), a789 (Gallery Panel), b1818/b1269 (ID10 v2).