# Aurora Admin v2 — Project Status

_Last updated: 2026-07-03_

## What this project is

A ground-up rebuild of the "uiXpress" WordPress admin-theme plugin, relaunched
as **Aurora Admin**. The original plugin's look/feel and feature set are the
target, but **no original code is reused** — all Vue components, PHP classes,
Tailwind config, and build tooling are freshly written. This lives in
`aurora-admin-v2/` (the earlier in-place rebrand attempt, `aurora-admin-working/`,
is superseded and no longer the active codebase).

## Workflow rules established

- **Always verify live in Chrome** before declaring a fix done — the user was
  burned by blind-iteration guesses costing time/money. Use the Chrome MCP
  tools (`tabs_context_mcp`, `navigate`, `computer`/screenshot, `javascript_exec`)
  to inspect real DOM/computed styles rather than guessing from source.
- **Zip packaging**: Windows `Compress-Archive` corrupts the WP upload (backslash
  path separators break PHP's unzip). Always build the zip via PowerShell
  `System.IO.Compression.ZipFile`, normalizing every entry path with
  `.Replace('\', '/')`. Output goes to
  `aurora-admin-v2-dist\aurora-admin\aurora-admin-v2.zip`.
- **Old build caching gotcha**: WordPress serves whatever plugin files were last
  installed — if the user says "didn't fix it," suspect a stale zip still
  installed before suspecting the code. Verify the live script hash via
  `document.querySelector('script[src*="dashboard"]')` when in doubt.
- Site under test: `http://admin.local/wp-admin/`.

## Architecture

- **PHP** (`admin/src/...`, namespaced `AuroraAdmin\...`), bootstrapped from
  `aurora-admin.php`, instantiated in `admin/src/App/AuroraAdmin.php`.
- **Vue 3** app (`app/src/...`), Vite multi-entry build → `manifest.json`,
  read by `admin/src/Utility/Assets.php::enqueue()` which also walks the
  manifest's `imports` chain to pull in shared-chunk CSS.
- **Single global stylesheet**: `app/src/shell/shell-frame.css` — defines all
  `--aurora-*` CSS variables (incl. `.aurora-dark` overrides) and the only
  rules that touch WP structural IDs (`#wpcontent`, `#wpbody-content`). No
  element resets/utility classes leak onto native WP pages (this was the
  root cause of the original rebrand's Tailwind-leakage bug — avoided here
  by design).
- **Immersive shell** (`admin/src/Shell/Shell.php` + `app/src/shell/SiteShell.vue`
  + `Sidebar.vue` + `Toolbar.vue`): hides native WP chrome, mounts a Vue
  sidebar/toolbar on every admin page. `MenuSerializer.php` converts WP's
  `$menu`/`$submenu` globals into JSON for the sidebar.
- **Dashboard takeover** (`admin/src/Pages/DashboardTakeover.php` +
  `app/src/pages/dashboard/Dashboard.vue`): hijacks native `index.php` via
  `in_admin_header`, hides the native `.wrap`, renders the Aurora dashboard
  in its place. 12-col grid; cards are single `<section class="aurora-card">`
  elements with inline `grid-column: span N` (NOT wrapped — component
  attribute fallthrough for styles was unreliable).
- **Settings page** (`admin/src/Pages/SettingsPage.php` + `app/src/pages/
  settings/Settings.vue`): owns the top-level "Aurora Admin" admin menu
  directly (no submenu). Two-box layout: `.settings__nav` (category list) +
  `.settings__content` (fields), both boxed/bordered on a darker backdrop.
  Field schema is declarative in `app/src/pages/settings/settingsConfig.js`,
  rendered by `app/src/pages/settings/components/SettingsField.vue` (types:
  text, toggle, color, image, repeater, multiselect, segmented, remote-sites).
- **Settings persistence**: `admin/src/Options/Settings.php` — partial-payload
  save via `merge_on_save()` sanitize callback (merges into existing option,
  doesn't overwrite). `Settings::get_safe()` strips `license_key` and remote
  site passwords for use on non-admin-gated pages; `Settings::get()` (full)
  only used on the manage_options-gated settings page itself.
- **Global search**: `app/src/shell/components/SearchModal.vue`, Ctrl+K,
  debounced `wp/v2/search` REST calls, gated on `disable_global_search` setting.
- **Remote site switcher**: toolbar dropdown, gated on `canSwitchSites` (from
  `remote_site_switcher_capability` setting) + non-empty `remote_sites`.
- **Scheduled content**: `app/src/pages/dashboard/cards/ScheduledContent.vue`
  calendar cells (squares, date top-left, count centered) are clickable —
  navigate to `edit.php?post_status=future&aurora_day=YYYY-MM-DD` if that day
  has scheduled posts, else show a toast ("no scheduled content"). Server side:
  `admin/src/Posts/ScheduledDayFilter.php` filters the `edit.php` query via
  `pre_get_posts` and prints an info notice.
- **Analytics**: `admin/src/Analytics/Analytics.php` (first-party pageview
  tracker, own DB table `wp_aurora_admin_pageviews`, bot detection, gated on
  `enable_analytics`/`track_admins` settings) + `admin/src/Rest/AnalyticsData.php`
  (aggregation REST endpoint: totals, series, device/referrer/country
  breakdowns, bounce rate, active users).
- **White label**: `admin/src/WhiteLabel/WhiteLabel.php` — custom favicon,
  rename plugin in Plugins list, rename top-level menu item, gettext
  find/replace via `text_replacements` setting.
- **Native page dark styling**: `admin/assets/native-dark.css` (large static
  sheet, all rules gated `html.aurora-dark.aurora-ready`, scoped under
  `#wpbody-content`) + `admin/assets/native-enhance.js` (progressive JS
  enhancement — currently only `enhanceUpdates()`, which groups the flat
  Updates page sections into `.aurora-native-card` wrapper divs on
  `body.update-core-php`).

## Key bugs fixed (root causes, in case they resurface)

- **`.card` global class collision**: original Dashboard cards used
  `class="card"`, colliding with WP core's `.card { max-width: 520px }`,
  capping card width regardless of grid span. Fixed by renaming to
  `.aurora-card*` everywhere. Lesson: never use unprefixed class names on
  Aurora components — always prefix `aurora-`.
- **Grid-column not applying on wrapped cards**: settled on unwrapped
  `<section class="aurora-card" :style="{gridColumn: ...}">` — component
  boundaries ate the style binding in earlier attempts.
- **Two-box settings layout**: took two wrong iterations (splitting
  header/fields instead of nav/content) before matching the user's reference
  image. If revisiting settings layout, re-confirm against a screenshot
  before assuming intent.
- **Redundant outer frame border on settings page**: `#wpbody-content`'s
  frame border/radius doubled up with the new two-box layout; fixed with a
  `body.toplevel_page_aurora-admin` override in `shell-frame.css` that drops
  the outer frame there only.

## Current / in-progress task

**User's last request: "now the updates page doesn't match the style as the
dashboard page."**

Status: diagnosis started but not finished. I navigated to
`update-core.php` and confirmed the page renders with the shell (minify
button, View Website/Dashboard icons, search, dark toggle) and that
`native-enhance.js` is already grouping the page into three
`.aurora-native-card` boxes (Current version / Plugins / Themes). I had
**not yet** done a side-by-side computed-style comparison against
`.aurora-card` (used on the Dashboard, e.g. "Recent content" / "Site Health"
cards) to find the actual mismatch — could be background shade, border
radius, padding, title typography, or hover state. No code changes made yet
for this specific request.

### Next step (concrete)

Via Chrome `javascript_exec`, pull `getComputedStyle()` for a live
`.aurora-card` element on the Dashboard and a live `.aurora-native-card`
element on the Updates page — compare `background-color`, `border-color`,
`border-radius`, `padding`, `box-shadow`, and heading font-size/weight. Then
patch `.aurora-native-card` rules in `admin/assets/native-dark.css` (and/or
structure in `native-enhance.js` if the mismatch is structural, e.g. missing
a title wrapper element) to match `.aurora-card` in `Dashboard.vue`. Verify
live, then rebuild/sync to dist, re-zip, and have the user reinstall.

## Not-yet-done (deferred, no active request)

- Full field sets for settings categories beyond General/Analytics/White
  Label (original plugin had more).
- Extending `native-enhance.js` boxing to other native screens (Tools, etc.)
  beyond Updates.
- Porting the real license-key activation flow (built previously in the old
  `aurora-admin-working` project, not yet ported to v2 — currently just a
  text field).
- Light-mode boxing for native pages (`native-dark.css`/`native-enhance.js`
  currently only styled for dark mode; light mode native pages are untouched
  WP default).