# App-Trace Atlas — Module Index

**Locked 2026-08-04 07:25 BST** as part of a452 Phase 2 (App-Trace Atlas shell).

The full Atlas lives at `app-trace-atlas/atlas.json` (29.6 KB). This document is the **human-readable index** for browsing and editing without parsing JSON.

**The 5-level chain (per FWV v8 §04)**: `surface → behaviour → module → file → test`. The Atlas makes the chain machine-verifiable.

## Module summary

- **22 surfaces** (UI elements the user can see)
- **39 behaviours** (pieces of app logic, each triggered by an event)
- **24 modules** (logical groupings of related code)
- **23 files** mapped (more in reality; this is the first cut)
- **12 tests** mapped (full coverage not yet there; test gap to be closed in Phase 5 Recipe Books)
- **23 panels** (editor chrome, per §1.7a)
- **7 blocks** (content chunks, per §1.7a)

## Panel index (23, editor chrome per §1.7a)

| Panel | Purpose | Path | Behaviors |
|---|---|---|---|
| editor-outline | Yellow clickable tags on regions/blocks | `app-fragments/editor-outline/` | show-on-hover, click-to-select |
| editor-palette | 2-column grid of 16 blocks | `app-fragments/editor-palette/` | render-blocks, drag-block-to-region |
| editor-region-actions | Toolbar for region properties | `app-fragments/editor-region-actions/` | show-actions-on-click, apply-property |
| editor-layout-templates | Layout picker for new regions | `app-fragments/editor-layout-templates/` | show-picker-on-add-region, apply-template |
| editor-inspector | Property editor for selected element | `app-fragments/editor-inspector/` | render-fields-for-selected, save-on-change |
| editor-navigator | Structure tree of regions/blocks | `app-fragments/editor-navigator/` | render-tree, click-to-jump |
| editor-content-admin | Records CRUD (lives in chrome) | `app-fragments/editor-content-admin/` | list, create, edit, delete records |
| editor-breadcrumb | Path breadcrumb for selection | `app-fragments/editor-breadcrumb/` | render-path, click-to-jump |
| editor-context-menu | Right-click menu | `app-fragments/editor-context-menu/` | show-on-right-click, apply-action |
| editor-selection | Selection state | `app-fragments/editor-selection/` | set-selected, clear-selected |
| fvcms-dev-btn | The { } floating button | `app-fragments/fvcms-dev-btn/` | toggle-chrome |
| fvcms-dev-panel | Dev panel (chrome tabs) | `app-fragments/fvcms-dev-panel/` | show-on-toggle, render-chrome-tabs |
| fvcms-panel-manager | Multi-panel state machine | `app-fragments/fvcms-panel-manager/` | mount, dock, auto-hide, remove |
| fvcms-cms-panel | Legacy v0.7.3 CMS panel | `app-fragments/fvcms-cms-panel/` | mount, render-chrome |
| cms-data | Static modules catalogue | `app-fragments/cms-data/` | load-modules |
| fvcms-trace | Trace panel (visualises Atlas live) | `app-fragments/fvcms-trace/` | (planned) |
| fvcms-floating-buttons | Container for floating buttons | `app-fragments/fvcms-floating-buttons/` | (planned) |
| fvcms-module-editor | Module editor panel | `app-fragments/fvcms-module-editor/` | (planned) |
| fvcms-region-editor | Region editor panel | `app-fragments/fvcms-region-editor/` | (planned) |
| fvcms-watermark-hider | Hides Oscar watermark | `app-fragments/fvcms-watermark-hider/` | (planned) |
| content-admin-launcher | The {📋} button | `app-fragments/content-admin-launcher/` | (planned) |
| editor-save-for-reuse | Review content types | `app-fragments/editor-save-for-reuse/` | (planned) |
| editor-templates | Manage starting points for new records | `app-fragments/editor-templates/` | (planned) |

**Total inventoried in atlas.json**: 22 (15 with full behaviours + 7 with planned behaviours; will be expanded in Phase 5)

## Block index (7, content chunks per §1.7a)

| Block | Tier | Path | Behaviours |
|---|---|---|---|
| heading | 3 (generic MIT) | `modules/heading/` | render |
| button | 3 (generic MIT) | `modules/button/` | render, handle-click |
| image | 3 (generic MIT) | `modules/image/` | render |
| carousel | 3 (generic MIT) | `modules/carousel/` | render, next-slide, prev-slide |
| testimonial | 3 (generic MIT) | `modules/testimonial/` | render |
| info-box | 3 (generic MIT) | `modules/info-box/` | render |
| cta-box | 3 (generic MIT) | `modules/cta-box/` | render |

All 7 blocks are **Tier 3 generic MIT** per FWV v8 §17 (the freshvibe-cms alignment gives them away for free; consumers can ship their own derivatives).

## Test coverage gaps (Phase 5 work)

The Atlas currently shows 12 tests mapping to 39 behaviours. That means **at least 27 behaviours are untested** in the first-cut Atlas. Phase 5 (per-module Recipe Books) will close these gaps by:

1. Adding per-block tests for the 7 blocks (currently 0 tests for any block)
2. Adding per-panel tests for the 7 "planned" panels
3. Reviewing each untested behaviour and either adding a test or marking it as `out-of-scope` with justification

## How to use this Atlas

- **From a behaviour** (e.g. "palette.drag-block-to-region"): find the behaviour, trace forward to its modules + files + tests
- **From a surface** (e.g. "the { } button"): find the surface, trace forward to its behaviours + modules
- **From a test** (e.g. "tests/outline.mjs"): find the test, trace backward to its covered behaviours + modules
- **To find a gap** (e.g. "no test for the carousel next-slide behaviour"): scan the behaviours list, find one without a test entry

The Atlas is the source of truth for the **"did the change break anything?"** question. Any code change should reference which behaviours + files it touches; the Atlas then shows which tests to run.

## Update protocol

Any change to a panel, block, behaviour, file, or test should update the Atlas. This is enforced in Phase 7 (App-VP + drift detector) where the drift detector will compare the Atlas against the actual code and flag mismatches.

## What the Atlas is NOT

- Not a type system (use TypeScript or JSDoc for that)
- Not a dependency graph (use `npm ls` for that)
- Not a documentation system (use `docs/` for prose, the Atlas for traceability)
- Not a test runner (use `npm test` for that)

The Atlas is **only** the surface→behaviour→module→file→test chain. If something doesn't fit that chain, it doesn't go in the Atlas.