# Policy Editor Workspace

> **Audience:** Product/UX, UI engineers, policy authors/reviewers using the Console.  
> **Scope:** Layout, features, RBAC, a11y, simulation workflow, approvals, run dashboards, and offline considerations for the Policy Engine v2 editor (“Policy Studio”).

The Policy Editor is the primary Console workspace for composing, simulating, and approving `stella-dsl@1` policies. It combines Monaco-based editing, diff visualisations, and governance tools so authors and reviewers can collaborate without leaving the browser.

---

## 1 · Access & Prerequisites

- **Routes:** `/console/policy` (list) → `/console/policy/:policyId/:version?`.
- **Scopes:** 
  - `policy:write` to edit drafts, run lint/compile, attach simulations.
  - `policy:submit` / `policy:review` / `policy:approve` for workflow actions.
  - `policy:run` to trigger runs, `policy:runs` to inspect history.
  - `findings:read` to open explain drawers.
- **Feature flags:** `policyStudio.enabled` (defaults true once Policy Engine v2 API available).
- **Browser support:** Evergreen Chrome, Edge, Firefox, Safari (last two versions). Uses WASM OPA sandbox; ensure COOP/COEP enabled per [UI architecture](../ARCHITECTURE_UI.md).

---

## 2 · Workspace Layout

```
┌────────────────────────────────────────────────────────────────────────────┐
│ Header: Policy selector • tenant switch • last activation banner           │
├────────────────────────────────────────────────────────────────────────────┤
│ Sidebar (left)      │ Main content (right)                                 │
│ - Revision list      │ ┌───────────── Editor tabs ───────────────┐         │
│ - Checklist status   │ │  DSL  │  Simulation  │  Approvals  │ ... │         │
│ - Pending reviews    │ └─────────────────────────────────────────┘         │
│ - Run backlog        │                                                     │
│                      │ Editor pane / Simulation diff / Run viewer          │
└────────────────────────────────────────────────────────────────────────────┘
```

- **Sidebar:** Revision timeline (draft, submitted, approved), compliance checklist cards, outstanding review requests, run backlog (incremental queue depth and SLA).
- **Editor tabs:** 
  - *DSL* (primary Monaco editor)
  - *Simulation* (pre/post diff charts)
  - *Approvals* (comments, audit log)
  - *Runs* (heatmap dashboards)
  - *Explain Explorer* (optional drawer for findings)
- **Right rail:** context cards for VEX providers, policy metadata, quick links to CLI/API docs.

> Placeholder screenshot: `![Policy editor workspace](../assets/policy-editor/workspace.png)` (add after UI team captures latest build).

---

## 3 · Editing Experience

- Monaco editor configured for `stella-dsl@1`:
  - Syntax highlighting, IntelliSense for rule/action names, snippets for common patterns.
  - Inline diagnostics sourced from `/policies/{id}/lint` and `/compile`.
  - Code actions (“Fix indentation”, “Insert requireVex block”).
  - Mini-map disabled by default to reduce contrast noise; toggle available.
- **Keyboard shortcuts (accessible via `?`):**
  - `Ctrl/Cmd + S` – Save draft (uploads to API if changed).
  - `Ctrl/Cmd + Shift + Enter` – Run lint + compile.
  - `Ctrl/Cmd + Shift + D` – Open diff view vs baseline.
  - `Alt + Shift + F` – Format document (canonical ordering).
- **Schema tooltips:** Hover on `profile`, `rule`, `action` to view documentation (sourced from DSL doc).
- **Offline warnings:** When `sealed` mode detected, banner reminds authors to validate with offline bundle.

---

## 4 · Simulation & Diff Panel

- Triggered via “Run simulation” (toolbar) or automatically after compile.
- Displays:
  - **Summary cards:** total findings added/removed/unchanged; severity up/down counts.
  - **Rule hit table:** top rules contributing to diffs with percentage change.
  - **Component list:** virtualised table linking to explain drawer; supports filters (severity, status, VEX outcome).
  - **Visualisations:** stacked bar chart (severity deltas), sparkline for incremental backlog impact.
- Supports run presets:
  - `Golden SBOM set` (default)
  - Custom SBOM selection (via multi-select and search)
  - Import sample JSON from CLI (`Upload diff`).
- Diff export options:
  - `Download JSON` (same schema as CLI output)
  - `Copy as Markdown` for review comments
- Simulation results persist per draft version; history accessible via timeline.

---

## 5 · Review & Approval Workflow

- **Commenting:** Line-level comments anchored to DSL lines; global comments supported. Uses rich text (Markdown subset) with mention support (`@group/sec-reviewers`).
- **Resolution:** Approvers/reviewers can mark comment resolved; history preserved in timeline.
- **Approval pane:** 
  - Checklist (lint, simulation, determinism CI) with status indicators; links to evidence.
  - Reviewer checklist (quorum, blocking comments).
  - Approval button only enabled when checklist satisfied.
- **Audit log:** Chronological view of submit/review/approve/archive events with actor, timestamp, note, attachments.
- **RBAC feedback:** When user lacks permission, actions are disabled with tooltip referencing required scope(s).
- **Notifications:** Integration with Notifier—subscribe/unsubscribe from review reminders within panel.

---

## 6 · Runs & Observability

- **Run tab** consumes `/policy/runs` data:
  - Heatmap of rule hits per run (rows = runs, columns = top rules).
  - VEX override counter, suppressions, quieted findings metrics.
  - Incremental backlog widget (queue depth vs SLA).
  - Export CSV/JSON button.
- **Replay/Download:** For each run, actions to download sealed replay bundle or open CLI command snippet.
- **Alert banners:** 
  - Determinism mismatch (red)
  - SLA breach (amber)
  - Pending replay (info)

---

## 7 · Explain & Findings Integration

- Inline “Open in Findings” button for any diff entry; opens side drawer with explain trace (same schema as `/findings/*/explain`).
- Drawer includes:
  - Rule sequence with badges (block/warn/quiet).
  - VEX evidence and justification codes.
  - Links to advisories (Concelier) and SBOM components.
- Copy-to-clipboard (JSON) and “Share permalink” features (permalinks encode tenant, policy version, component).

---

## 8 · Accessibility & i18n

- WCAG 2.2 AA:
  - Focus order follows logical workflow; skip link available.
  - All actionable icons paired with text or `aria-label`.
  - Simulation charts include table equivalents for screen readers.
- Keyboard support:
  - `Alt+1/2/3/4` to switch tabs.
  - `Shift+?` toggles help overlay (with key map).
- Internationalisation:
  - Translations sourced from `/locales/{lang}.json`.
  - Date/time displayed using user locale via `Intl.DateTimeFormat`.
- Theming:
  - Light/dark CSS tokens; Monaco theme syncs with overall theme.
  - High-contrast mode toggled via user preferences.

---

## 9 · Offline & Air-Gap Behaviour

- When console operates in sealed enclave:
  - Editor displays “Sealed mode” banner with import timestamp.
  - Simulation uses cached SBOM/advisory/VEX data only; results flagged accordingly.
  - “Export bundle” button packages draft + simulations for transfer.
- Approvals require local Authority; UI blocks actions if `policy:approve` scope absent due to offline token limitations.
- Run tab surfaces bundle staleness warnings (`policy_runs.inputs.env.sealed=true`).

---

## 10 · Telemetry & Testing Hooks

- User actions (simulate, submit, approve, activate) emit telemetry (`ui.policy.action` spans) with anonymised metadata.
- Console surfaces correlation IDs for lint/compile errors to ease support triage.
- Cypress/Playwright fixtures available under `ui/policy-editor/examples/`; docs should note to re-record after significant UI changes.

---

## 11 · Compliance Checklist

- [ ] **Lint integration:** Editor surfaces diagnostics from API compile endpoint; errors link to DSL documentation.
- [ ] **Simulation parity:** Diff panel mirrors CLI schema; export button tested.
- [ ] **Workflow RBAC:** Buttons enable/disable correctly per scope (`policy:write/submit/review/approve`).
- [ ] **A11y verified:** Keyboard navigation, focus management, colour contrast (light/dark) pass automated Axe checks.
- [ ] **Offline safeguards:** Sealed-mode banner and bundle export flows present; no network calls trigger in sealed mode.
- [ ] **Telemetry wired:** Action spans and error logs include policyId, version, traceId.
- [ ] **Docs cross-links:** Links to DSL, lifecycle, runs, API, CLI guides validated.
- [ ] **Screenshot placeholders updated:** Replace TODO images with latest UI captures before GA.

---

*Last updated: 2025-10-26 (Sprint 20).*