# App-Codex — Oscar's Tree Academy

**Date:** 2026-07-06
**Status:** v0.1.0 ACTIVE

## 1. Surfaces

UI surfaces in the deployed app:

| ID | Name | Purpose | Mounted by |
|---|---|---|---|
| surface.oscar.page | Static page | Rendered dist HTML (Elementor + theme) | dist loader |
| surface.oscar.watermark-host | Workspace watermark | Defensive removal | oscar-watermark-hider |
| surface.oscar.dev-btn | Floating { } button | Toggle dev panel | oscar-dev-btn |
| surface.oscar.dev-panel | Dev panel content | Build meta, trace toggles, admin link | oscar-dev-panel |
| surface.oscar.trace-overlay | Trace badges (W-N, S-N, H-N, CTA-N) | Page inspector | oscar-trace |
| surface.oscar.module-editor | Post-carousel editor panel | Live widget data-settings edit | oscar-module-editor |

## 2. Behaviours

Interactions and state transitions:

| ID | Name | Trigger | Effect |
|---|---|---|---|
| behaviour.oscar.toggle-dev-panel | Click `{ }` | button click | dev-panel open/close |
| behaviour.oscar.drag-panel | Mouse down on header | drag | panel moves + snaps to edge within 50px |
| behaviour.oscar.pin-panel | Click 📌 | pin button | disable auto-hide |
| behaviour.oscar.squeeze-overlay | Click ⇔ | squeeze button | toggle body padding vs overlay |
| behaviour.oscar.toggle-trace | Checkbox change | trace toggle | re-scan page for that kind |
| behaviour.oscar.badge-click | Click W-N badge | badge click | if carousel, open editor; else copy tag |
| behaviour.oscar.save-module | Click Save | save button | write to localStorage + update data-settings attr |
| behaviour.oscar.watermark-kill | DOMContentLoaded + 100ms + 500ms | timer | remove #minimax-floating-ball |

## 3. State

Persistent state (localStorage):

- `oscar-panel-state:oscar-dev-panel` — dev panel position/pinned/overlay
- `oscar-panel-state:oscar-mod-<widgetId>` — module editor per widget
- `oscar-mod-<widgetId>` — saved module settings JSON

In-memory state:
- active panel registry (in window.OscarPanelManager)
- active trace badge registry (in oscar-trace.js)
- pending auto-hide timers (in panel manager)

## 4. Out of scope

These are NOT in this app-codex:
- The admin CMS at /admin/ (separate codex at /admin/app-codex.md if needed)
- The Elementor widgets themselves (those are Elementor + theme + plugin code)
- The static dist build process (FvRE static-build component, see FvRE repo)