# daw v0.5.0 — Upgrade Plan (working doc)

Living plan for migrating the `daw` theme from a 22-year-old classic PHP theme to a
modern FSE block theme. Update freely as we go. Companion: [[dependencies]].

## Goal

Bring `daw` in line with how I build themes now (the `srh` theme is the reference),
shedding accumulated cruft along the way — without losing the bespoke, hand-crafted
character of the site.

## Locked decisions (2026-06-15)

1. **Full block / FSE theme** — `theme.json` + `templates/` + `parts/` + `patterns/` + `blocks/`, Site-Editor driven (like `srh`).
2. **Build:** `@wordpress/scripts` + webpack — replaces the gulp pipeline.
3. **Homepage stays bespoke** — keep the hand-rolled `front-page.php` (centered card, davo-bot, inline critical CSS); a classic PHP front-page coexists fine inside a block theme.

## Target conventions (from the `srh` theme)

- **Loader:** thin `functions.php` → `require_once` of `inc/<module>/loader.php`; each subdir's loader requires its peers. Consistent `dw_` function prefix.
- **`inc/` by concern:** e.g. `seo/`, `analytics/`, `perf/`, `a11y/`, `integrations/` — each procedural, hooked to `wp_head`/`wp_footer`/`wp_enqueue_scripts`.
- **`theme.json` v3:** `settings` (layout contentSize/wideSize, color palette, typography fontFamilies/fontSizes, spacing) + `styles` (elements). Design tokens live here, not in CSS.
- **`templates/` + `parts/`:** block-markup `*.html` (`index/single/archive/page/home/search/404/category`); parts for `header`/`footer`.
- **`patterns/`:** auto-discovered from `/patterns/` via PHP file headers (Title/Slug/Categories/Block Types). Categories registered in `functions.php`.
- **`blocks/`:** per-block `block.json` (apiVersion 3) + `render.php`; `autoRegister:true` for render-only blocks (WP 7.0+), manual `register_block_type` + editor script for interactive ones.
- **Build:** `wp-scripts build`/`start`, custom `webpack.config.js` for extra entries + BrowserSync, `.babelrc` with `wp.element.createElement` pragma.

---

## Phases

### Phase 0 — Get a handle on it (done)
- [x] Document existing dependencies → [[dependencies]]
- [~] **Refactor `functions.php` → modular `inc/`** — **deferred** (2026-06-15): it's only ~200 lines and readable enough; not worth chopping yet. The `inc/` modularization will happen naturally as the FSE build grows. Map kept below for when we do.

**Proposed `functions.php` → `inc/` map (deferred — reference)** (current responsibilities → modules):

| Current (in functions.php) | New home |
|---|---|
| `dw_setup()` — theme supports, image sizes | `inc/setup.php` |
| `dw_scripts()` — the per-page enqueue ladder | `inc/assets.php` (the big readability win) |
| `dw_editor()` — editor styles | `inc/assets.php` |
| `dw_analytics()` — Matomo footer | `inc/analytics/matomo.php` |
| `dw_login_session()` — auth cookie filter | `inc/auth.php` |
| `dw_ask_widget()` — davo-bot loader | `inc/integrations/davo-bot.php` |
| `dw_plugs()` → smtp | `inc/integrations/smtp.php` (wraps existing `inc/smtp.php`) |
| existing `inc/{utils,template,tweaks,form,analytics}.php` | keep; fold into loader |

`functions.php` ends up a thin bootstrap: define constants → `require inc/loader.php`.
**Behavior must be byte-for-byte identical** at this stage (pure reorg, no feature change).

### Phase 1 — Build toolchain (in progress)
- [x] Stand up `@wordpress/scripts` + webpack: `package.json` (build/start scripts + deps), `.babelrc`, `webpack.config.js` (browser-sync proxying `daw.stu:3030`), `src/` → `build/` seed
- [x] `npm install` + `npm run build` verified (compiles `src/` → `build/index.js`). `npm start` wired (browser-sync `daw.stu:3030`), not yet run.
- [ ] Port front-end CSS/JS into `src/` as the block templates need it (incremental, through Phases 2–4)

**Decision (2026-06-15):** new toolchain runs **alongside** the legacy gulp/`v4-*` build, not replacing it yet — the live theme still enqueues `v4-style.min.css` / `v4-script.min.js`, so gulp stays dormant (deps kept) until block templates supersede those assets. **Retiring gulp + `v4-*` moves to Phase 5.** New source is isolated in `src/` → `build/` so it never collides with the 40 legacy files in `js/`.

### Phase 2 — theme.json foundation
- [ ] `theme.json` v3: layout, color palette, typography, spacing, element styles
- [ ] Port design tokens out of `style.css`/`styles.scss`

### Phase 3 — Block templates + parts
- [ ] `templates/`: index, single, archive, page, home, search, 404, category, tag
- [ ] `parts/`: header, footer (retire `header-*.php` / `footer-*.php` variants)
- [ ] Keep `front-page.php` bespoke (coexists)
- [ ] Decide each legacy `page-*.php`: → block template, → pattern, → retire (see open questions)

### Phase 4 — Patterns + custom blocks
- [ ] `patterns/` for reusable sections
- [ ] `blocks/` for dynamic bits (music/last.fm, desk loop → Query Loop, etc.)

### Phase 5 — Cleanup (the "additional cleanup")
- [ ] Drop confirmed-dead deps per [[dependencies]] (terminal.js, messenger, modernizr, jasny, animate.css…)
- [ ] Resolve audits: Twilio call/SMS/chat, fullcalendar, simple_html_dom, Stripe v2, icon fonts
- [ ] Remove legacy build outputs + `style.min.css`

### Phase 6 — New features
- [ ] _TBD — to be specified_

---

## Open questions / decisions to make

- Sign-off on the Phase 0 `inc/` module map above.
- **Page audit:** which legacy pages survive vs retire? Candidates to confirm: `bio`, `cv`, `shop`, `archive`, `chat`.
- **Feature audits:** is the Twilio phone/SMS/chat feature still live? Is `fullcalendar` still rendered anywhere? Is `simple_html_dom` still used?
- New features list (Phase 6).

## Changelog

- **2026-06-15** — Plan created; dependencies documented; decisions locked (FSE / wp-scripts / bespoke homepage).