Add sidebar 1:1 migration docs

SIDEBAR_1_TO_1_TASKLIST.md

@@ -0,0 +1,296 @@
+# WP Agentic Writer Sidebar 1:1 Migration Tasklist
+
+**Source task plan:** `SIDEBAR_1_TO_1_MIGRATION.md`
+**Source of truth:** `assets/js/sidebar.js`
+**Mode:** planning/tasklist only. No implementation code, no build step, no inferred behavior.
+
+Use this tasklist to execute the migration described in `SIDEBAR_1_TO_1_MIGRATION.md`. Every checkbox must be completed against `assets/js/sidebar.js`, not memory.
+
+**Current status:** planning docs are in place and the abandoned React rebuild scaffold has been removed from `assets/js`. No build was run, no enqueue switch was made, and implementation now needs to restart from the migration plan rather than from a preexisting React target.
+
+## Ground Rules
+
+- [x] Confirm `assets/js/sidebar.js` is the current source of truth before starting.
+- [x] Confirm `SIDEBAR_1_TO_1_MIGRATION.md` is open beside `assets/js/sidebar.js`.
+- [x] Do not use `MIGRATION_GUIDE.md` as authority when it differs from `assets/js/sidebar.js`.
+- [x] Do not rename functions during the first migration pass.
+- [x] Do not extract helper files during the first migration pass.
+- [x] Do not change visible text, labels, placeholders, icons, SVG markup, classes, inline styles, aria attributes, roles, or conditional render gates.
+- [x] Do not replace `RawHTML`, markdown logic, stream handling, abort handling, localStorage keys, endpoint paths, request bodies, or Gutenberg APIs.
+- [ ] Keep the first target as a monolithic JSX port.
+
+## Definition of Done for Each Range
+
+- [ ] Source range is copied or represented completely.
+- [ ] `createElement` conversion keeps the same tag/component.
+- [ ] Props are preserved 1:1.
+- [ ] Children order is preserved 1:1.
+- [ ] Conditional gates are preserved in the same branch position.
+- [ ] State/ref/effect ordering is preserved.
+- [ ] Callback boundaries and dependency arrays are preserved.
+- [ ] Inline styles, string literals, titles, placeholders, labels, and SVG strings are preserved.
+- [ ] Any migrated range is checked against the original source lines before moving on.
+
+## Phase 0 - Source Lock and Boundaries
+
+- [x] Verify `sidebar.js` has 12,363 lines.
+- [x] Verify file header and IIFE boundary: lines 1-7 and 12363.
+- [x] Verify dependency destructuring: lines 8-15.
+- [x] Verify debug logger and `pluginIcon`: lines 16-35.
+- [x] Verify `AgenticWriterSidebar` starts at line 38.
+- [x] Verify `AgenticWriterSidebar` closes at line 12347.
+- [x] Verify HOC/plugin boot remains separate: lines 12349-12363.
+- [x] Verify main return starts at line 12307.
+- [x] Record any source drift before implementation. If line numbers changed, regenerate this tasklist from the updated source.
+
+## Phase 1 - Monolith Skeleton
+
+- [ ] Create the migrated target as one monolithic sidebar component.
+- [ ] Map every WordPress dependency from lines 8-15.
+- [ ] Preserve `pluginIcon` behavior from lines 31-35.
+- [ ] Preserve component prop shape: `AgenticWriterSidebar = ({ postId })`.
+- [ ] Preserve `mapSelectToProps` behavior from lines 12349-12352.
+- [ ] Preserve `ConnectedSidebar` behavior from lines 12355-12356.
+- [ ] Preserve `registerPlugin("wp-agentic-writer")` behavior from lines 12358-12362.
+- [ ] Do not split files yet.
+
+## Phase 2 - State, Refs, and Constants
+
+- [ ] Migrate settings and error formatting: lines 40-138.
+- [ ] Migrate chat/top-level state: lines 139-149.
+- [ ] Migrate session lock state and refs: lines 152-160.
+- [ ] Migrate config defaults, config state, and config refs: lines 163-188.
+- [ ] Migrate cost/provider state and provider metadata helper: lines 191-223.
+- [ ] Migrate editor/refinement lock state and refs: lines 224-237.
+- [ ] Migrate SEO audit state: lines 240-243.
+- [ ] Migrate clarification, pending plan, and request refs: lines 246-268.
+- [ ] Migrate active operation refs/state: lines 269-279.
+- [ ] Migrate writing state: lines 280-289.
+- [ ] Migrate workspace snapshot/collapse state and toggle: lines 290-321.
+- [ ] Migrate mention/slash/input refs and state: lines 323-336.
+- [ ] Migrate focus keyword state and persistence refs: lines 338-347.
+- [ ] Migrate welcome state: lines 349-352.
+- [ ] Migrate undo stack and max size: lines 354-356.
+- [ ] Migrate Memanto restore state/ref: lines 358-366.
+- [ ] Verify state/ref/hook order matches `sidebar.js` exactly.
+
+## Phase 3 - Effects, Saving, Timeline, and Editor Locks
+
+- [ ] Migrate agent mode reset effect: lines 367-371.
+- [ ] Migrate post config load effect: lines 373-400.
+- [ ] Migrate `savePostConfig`: lines 402-448.
+- [ ] Migrate debounced post config effect: lines 449-473.
+- [ ] Migrate cost tracking effect: lines 474-499.
+- [ ] Migrate `normalizeWritingState`: lines 500-510.
+- [ ] Migrate `saveWritingState`: lines 511-539.
+- [ ] Migrate `persistWritingStatePatch`: lines 540-550.
+- [ ] Migrate writing state load effect: lines 551-585.
+- [ ] Migrate scroll refs/effect: lines 586-595.
+- [ ] Migrate timeline regex/status constants and helpers: lines 596-673.
+- [ ] Migrate active operation helpers: lines 674-728.
+- [ ] Migrate refine-all confirmation callbacks: lines 729-752.
+- [ ] Migrate undo snapshot helpers: lines 753-812.
+- [ ] Migrate post saving lock effects: lines 813-841.
+- [ ] Migrate editor input lock and DOM blocker effect: lines 842-981.
+- [ ] Migrate text/config/keyword helpers and welcome start: lines 1020-1194.
+
+## Phase 4 - SEO, Workspace, Sessions, and Locks
+
+- [ ] Migrate `runSeoAudit`: lines 1195-1269.
+- [ ] Migrate SEO fix instruction helpers: lines 1270-1348.
+- [ ] Migrate `handleSeoAuditFix`: lines 1349-1459.
+- [ ] Migrate `generateMetaDescription`: lines 1460-1563.
+- [ ] Migrate block preview helpers: lines 1564-1599.
+- [ ] Migrate workspace snapshot helper/effects: lines 1600-1668.
+- [ ] Migrate beforeunload/session restore effects: lines 1669-1716.
+- [ ] Migrate session storage sanitizing and hydration: lines 1717-1781.
+- [ ] Migrate session message persistence: lines 1782-1889.
+- [ ] Migrate session lock acquire/release/heartbeat/takeover: lines 1890-2026.
+- [ ] Migrate lock/chat-history/post-session effects: lines 2027-2300.
+- [ ] Migrate `loadPostSessions`: lines 2301-2397.
+- [ ] Migrate `openSessionById`: lines 2398-2515.
+
+## Phase 5 - Mentions, Commands, Plans, and Agent Decisions
+
+- [ ] Migrate stream target and mention token helpers: lines 2516-2569.
+- [ ] Migrate title refinement: lines 2570-2689.
+- [ ] Migrate slash command parsing/options/block index: lines 2690-2758.
+- [ ] Migrate target block resolution and insert refinement block: lines 2759-2870.
+- [ ] Migrate plan streaming: lines 2871-3188.
+- [ ] Migrate retry helpers: lines 3189-3473.
+- [ ] Migrate plan block/preview helpers: lines 3474-3604.
+- [ ] Migrate section block helpers and persistence: lines 3605-3696.
+- [ ] Migrate plan task/target/matching/status/index helpers: lines 3697-3906.
+- [ ] Migrate chat summary, intent detection, context, reset, plan message, keyword suggestion, and runtime helpers: lines 3907-4218.
+- [ ] Migrate plan ID, intent classifier, and action decider: lines 4219-4320.
+
+## Phase 6 - Execution, Refinement, and Block Context
+
+- [ ] Migrate `executePlanFromCard`: lines 4321-4768.
+- [ ] Migrate stop execution: lines 4769-4794.
+- [ ] Migrate clear chat context: lines 4795-4870.
+- [ ] Migrate serialized block creation: lines 4871-4953.
+- [ ] Migrate block reformatting: lines 4954-5056.
+- [ ] Migrate plan revision: lines 5057-5142.
+- [ ] Migrate edit plan apply/cancel: lines 5143-5280.
+- [ ] Migrate clarification context effect/helper: lines 5281-5327.
+- [ ] Migrate duplicate heading removal: lines 5328-5362.
+- [ ] Migrate refineable block/list helpers: lines 5363-5442.
+- [ ] Migrate context block helpers: lines 5443-5520.
+- [ ] Migrate slang/AI-slop detection helpers: lines 5521-5606.
+- [ ] Migrate refinement diagnosis and block mention resolution: lines 5607-5799.
+- [ ] Migrate `handleChatRefinement`: lines 5800-6388.
+- [ ] Verify `wpaw-diff-added` and `wpaw-diff-removed` behavior survives unchanged.
+
+## Phase 7 - Chat Input and Main Async Flows
+
+- [ ] Migrate refine-all modal: lines 6389-6455.
+- [ ] Migrate mention options: lines 6456-6579.
+- [ ] Migrate custom insert-mention event effect: lines 6580-6612.
+- [ ] Migrate input change/key handling: lines 6613-6701.
+- [ ] Migrate mention and slash insertion helpers: lines 6702-6758.
+- [ ] Migrate `sendMessage`: lines 6759-8056.
+- [ ] Migrate `submitAnswers`: lines 8057-8476.
+- [ ] Verify all stream readers, decoders, timeouts, active readers, and abort branches match the source.
+
+## Phase 8 - Render Surfaces
+
+- [ ] Migrate `renderClarification`: lines 8477-8829.
+- [ ] Verify `renderSingleChoice`: lines 8486-8547.
+- [ ] Verify `renderMultipleChoice`: lines 8550-8577.
+- [ ] Verify `renderOpenText`: lines 8580-8597.
+- [ ] Verify `renderConfigForm`: lines 8600-8723.
+- [ ] Verify answer input switch: lines 8725-8742.
+- [ ] Migrate conversation session actions: lines 8830-9004.
+- [ ] Migrate `renderWelcomeScreen`: lines 9005-9184.
+- [ ] Migrate `renderWritingEmptyState`: lines 9185-9253.
+- [ ] Migrate `renderFocusKeywordBar`: lines 9254-9459.
+- [ ] Migrate `renderAgentWorkspaceCard`: lines 9460-9629.
+- [ ] Preserve `renderContextIndicator = renderAgentWorkspaceCard`: lines 9630-9632.
+- [ ] Migrate `renderContextualAction`: lines 9633-9996.
+- [ ] Migrate `renderMessages`: lines 9997-10917.
+- [ ] Migrate `renderConfigTab`: lines 10918-11434.
+- [ ] Migrate `getAgentStatus`: lines 11435-11448.
+- [ ] Migrate `renderGlobalStatusBar`: lines 11449-11585.
+- [ ] Migrate `renderChatTab`: lines 11586-12020.
+- [ ] Migrate cost state/effect/helpers: lines 12021-12057.
+- [ ] Migrate `renderCostTab`: lines 12058-12306.
+- [ ] Migrate main component return tree: lines 12307-12346.
+
+## Phase 9 - Render Surface Element Audit
+
+- [ ] Refine modal: confirm dialog role, aria modal/label, overlay, modal, title, body, checkbox, cancel, continue.
+- [ ] Clarification UI: confirm all question types, custom answer field, config fields, progress bar, previous/skip/next/finish behavior.
+- [ ] Welcome UI: confirm recent session, older session details, open/delete buttons, keyword input, mode pills, start button.
+- [ ] Writing empty state: confirm SVG icon, copy, create outline button, hint text.
+- [ ] Focus keyword bar: confirm expanded/compact branches, suggestions, selected state, provider/cost display, expand/collapse.
+- [ ] Workspace card: confirm collapsed state, status, context grid, keyword field, conversation/provider summary, resume card.
+- [ ] Contextual action: confirm `create_outline` action, clarity check branch, generate-plan stream branch, action card.
+- [ ] Messages: confirm markdown helpers, grouping, timeline, plan, edit plan, structured errors, retry buttons, default response, resume actions.
+- [ ] Config tab: confirm every section, control, description, SEO controls, meta generation, audit score, check list, fix buttons.
+- [ ] Status bar: confirm status dot, memory badge, undo, sessions, chat, workspace toggle, config, cost buttons.
+- [ ] Chat tab: confirm lock banners, health notices, welcome/empty/workspace/activity gates, command area, hint, textarea, autocompletes, search toggle, stop/send, keyboard hints, modal.
+- [ ] Cost tab: confirm header, refresh, cards, budget section, warning, action summary table, history table, footer link.
+- [ ] Final shell: confirm menu item, sidebar title, icon, panel, tab wrapper, active tab branch.
+
+## Phase 10 - Class Inventory Audit
+
+- [ ] Verify every literal `className` token from `SIDEBAR_1_TO_1_MIGRATION.md` exists in the migrated target.
+- [ ] Verify dynamic classes remain dynamic expressions.
+- [ ] Verify `wpaw-diff-removed` append branch: lines 6075-6078 and 6111-6114.
+- [ ] Verify `wpaw-diff-added` append branches: lines 6085-6089 and 6128-6129.
+- [ ] Verify welcome pill `active` branches: lines 9152-9154 and 9162-9164.
+- [ ] Verify focus suggestion `selected`: lines 9322-9324.
+- [ ] Verify workspace `is-collapsed` and `status-${activeWorkspaceStatus}`: lines 9489 and 9514.
+- [ ] Verify timeline `statusClass` and `is-current`: lines 10351-10375.
+- [ ] Verify plan section `section.status || "pending"`: line 10582.
+- [ ] Verify SEO/meta status classes: lines 11165-11374.
+- [ ] Verify status-bar `is-active` branches: lines 11510-11572.
+- [ ] Verify chat input classes: lines 11596-11955.
+- [ ] Verify budget status classes: lines 12129, 12158, and 12167.
+
+## Phase 11 - Non-Render Class and Selector Audit
+
+- [ ] Preserve WordPress lock key `wpaw-writing`: lines 824 and 828.
+- [ ] Preserve body class `wpaw-editor-locked`: lines 825 and 829.
+- [ ] Preserve WordPress lock key `wpaw-refining`: lines 835 and 838.
+- [ ] Preserve body class `wpaw-refining-locked`: lines 836 and 839.
+- [ ] Preserve editor block class `wpaw-block-refining`: lines 895, 903, and 916.
+- [ ] Preserve input-blocking selector `.wpaw-sidebar, .wpaw-command-area, .wpaw-messages`: line 933.
+- [ ] Preserve diff cleanup removal of `wpaw-diff-removed`: line 5262.
+
+## Phase 12 - Endpoint and Integration Audit
+
+- [ ] Verify `/post-config/${postId}` calls.
+- [ ] Verify `/cost-tracking/${postId}` calls.
+- [ ] Verify `/writing-state/${postId}` calls.
+- [ ] Verify `/seo-audit/${postId}` call.
+- [ ] Verify `/generate-meta` call.
+- [ ] Verify all conversation endpoints.
+- [ ] Verify `/conversation/${postId}` and `/conversation/${data.post_id}` calls.
+- [ ] Verify `/chat-history/${postId}` call.
+- [ ] Verify `/memanto/restore?post_id=${postId}` call.
+- [ ] Verify `/refine-title` call.
+- [ ] Verify all `/generate-plan` calls.
+- [ ] Verify all `/chat` calls.
+- [ ] Verify `/section-blocks/${postId}` and `/section-blocks` calls.
+- [ ] Verify `/summarize-context` call.
+- [ ] Verify `/detect-intent` call.
+- [ ] Verify `/clear-context` call.
+- [ ] Verify `/suggest-keywords` call.
+- [ ] Verify `/execute-article` call.
+- [ ] Verify `/reformat-blocks` call.
+- [ ] Verify `/revise-plan` call.
+- [ ] Verify `/refine-from-chat` call.
+- [ ] Verify `/check-clarity` calls.
+- [ ] For every endpoint, verify method, nonce header, content type, body shape, stream/non-stream handling, provider metadata, cost updates, and error handling.
+
+## Phase 13 - Gutenberg and Browser Side Effects Audit
+
+- [ ] Verify all `select("core/block-editor")` calls.
+- [ ] Verify all `dispatch("core/block-editor")` calls.
+- [ ] Verify all `select("core/editor")` calls.
+- [ ] Verify all `dispatch("core/editor")` calls.
+- [ ] Verify `wp.data.subscribe` behavior.
+- [ ] Verify `wp.data.withSelect` behavior.
+- [ ] Verify localStorage keys: `wpaw_agent_workspace_collapsed` and `wpawSessionId_${postId}`.
+- [ ] Verify beforeunload handlers.
+- [ ] Verify global document event listeners and cleanups.
+- [ ] Verify window `wpaw:insert-mention` listener and cleanup.
+- [ ] Verify lock heartbeat interval setup and cleanup.
+- [ ] Verify debounced config/message/keyword saves.
+- [ ] Verify `AbortController` lifecycle.
+- [ ] Verify stream reader lifecycle and active reader cancellation.
+- [ ] Verify `TextDecoder` usage.
+
+## Phase 14 - Final Parity Audit
+
+- [ ] Confirm no functions are missing from `SIDEBAR_1_TO_1_MIGRATION.md`.
+- [ ] Confirm no state/ref/effect entries are missing.
+- [ ] Confirm no render surface entries are missing.
+- [ ] Confirm no class inventory entries are missing.
+- [ ] Confirm no dynamic class expressions were flattened.
+- [ ] Confirm no endpoint inventory entries are missing.
+- [ ] Confirm no editor/browser side effects are missing.
+- [ ] Confirm final plugin registration still renders `ConnectedSidebar`.
+- [ ] Confirm no optional extraction was performed before monolith parity.
+- [ ] Confirm any future extraction task references the source line range it moves.
+
+## Optional Phase 15 - Extraction After Monolith Parity Only
+
+- [ ] Extract only one helper group at a time.
+- [ ] Before extraction, record source range and destination file.
+- [ ] Move code without renaming public/internal symbols.
+- [ ] Preserve imports/dependencies exactly.
+- [ ] Re-run the same parity checks for the moved range.
+- [ ] Do not extract render surfaces until all behavior helpers are proven equivalent.
+- [ ] Do not delete the monolith source range until the moved range is checked line-by-line.
+
+## Stop Conditions
+
+- [ ] Stop if `sidebar.js` changes and this tasklist has not been regenerated.
+- [ ] Stop if a migrated range requires guessing.
+- [ ] Stop if a function seems unused but exists in `sidebar.js`.
+- [ ] Stop if a class appears styling-only but exists in `sidebar.js`.
+- [ ] Stop if an endpoint or request body differs from `sidebar.js`.
+- [ ] Stop if hook order would change.