Implement forest-first layout and tuning controls

.playwright-cli/page-2026-03-15T14-40-38-280Z.yml

@@ -0,0 +1,82 @@
+- generic [ref=e3]:
+  - img [ref=e5]
+  - generic [ref=e8]:
+    - generic [ref=e11]:
+      - heading "WikiWebMap" [level=1] [ref=e12]
+      - paragraph [ref=e13]: Trace how Wikipedia topics connect. Start with one idea, or jump into a curated path and watch the graph bridge the gap.
+    - generic [ref=e14]:
+      - generic [ref=e15]: Search a Wikipedia topic
+      - generic [ref=e16]:
+        - generic [ref=e17]: Explore A Topic
+        - generic [ref=e18]: Press Enter to add it
+      - textbox "Search a Wikipedia topic" [ref=e19]:
+        - /placeholder: Search a Wikipedia topic...
+    - generic [ref=e20]:
+      - generic [ref=e21]:
+        - generic [ref=e22]: Start Here
+        - paragraph [ref=e23]: Search one topic to seed the map, then click nodes to inspect them or pick two ideas to trace a path.
+      - generic [ref=e24]:
+        - generic [ref=e25]: Quick Topics
+        - generic [ref=e26]:
+          - button "Physics" [ref=e27] [cursor=pointer]
+          - button "Jazz" [ref=e28] [cursor=pointer]
+          - button "Mount Everest" [ref=e29] [cursor=pointer]
+    - generic [ref=e30]:
+      - generic [ref=e31]:
+        - generic [ref=e32]:
+          - generic [ref=e33]: Curated Path Ideas
+          - generic [ref=e34]: Use these when you want the app to show you an interesting bridge instead of starting from one page.
+        - button "Shuffle" [ref=e35] [cursor=pointer]
+      - generic [ref=e36]:
+        - button "place Run path Great Barrier Reef→Coral Explore a place through nearby topics and landmarks." [ref=e37] [cursor=pointer]:
+          - generic [ref=e38]:
+            - generic [ref=e39]: place
+            - generic [ref=e40]: Run path
+          - generic [ref=e41]: Great Barrier Reef→Coral
+          - generic [ref=e42]: Explore a place through nearby topics and landmarks.
+        - button "technology Run path OpenAI→Transformer (machine learning model) See how technical ideas and tools connect." [ref=e43] [cursor=pointer]:
+          - generic [ref=e44]:
+            - generic [ref=e45]: technology
+            - generic [ref=e46]: Run path
+          - generic [ref=e47]: OpenAI→Transformer (machine learning model)
+          - generic [ref=e48]: See how technical ideas and tools connect.
+        - button "technology Run path Minecraft→Procedural generation See how technical ideas and tools connect." [ref=e49] [cursor=pointer]:
+          - generic [ref=e50]:
+            - generic [ref=e51]: technology
+            - generic [ref=e52]: Run path
+          - generic [ref=e53]: Minecraft→Procedural generation
+          - generic [ref=e54]: See how technical ideas and tools connect.
+    - button "Start Exploration" [disabled] [ref=e55]
+    - generic [ref=e56]: "Tip: after the graph appears, click a topic to inspect it. To find a bridge between two topics, use Shift+Click on desktop or Select For Path in the mobile details sheet."
+  - generic:
+    - generic [ref=e57]:
+      - button "Settings" [ref=e58] [cursor=pointer]:
+        - img [ref=e59]
+      - button "Legend" [ref=e61] [cursor=pointer]:
+        - img [ref=e62]
+    - generic [ref=e64]:
+      - button "✂️ Prune" [disabled] [ref=e65]:
+        - generic [ref=e66]: ✂️
+        - generic [ref=e67]: Prune
+      - button "🗑️ Delete Selection" [disabled] [ref=e68]:
+        - generic [ref=e69]: 🗑️
+        - generic [ref=e70]: Delete Selection
+  - generic [ref=e71]:
+    - generic [ref=e72]:
+      - generic [ref=e73]:
+        - text: "Nodes:"
+        - strong [ref=e74]: "0"
+      - generic [ref=e75]:
+        - text: "Connections:"
+        - strong [ref=e76]: "0"
+      - generic [ref=e77]:
+        - text: "Path:"
+        - strong [ref=e78]: Shift+Click
+      - generic [ref=e79]:
+        - text: "Select:"
+        - strong [ref=e80]: Alt+Drag
+      - button "View Session Diagnostics" [ref=e81] [cursor=pointer]:
+        - img [ref=e82]
+    - generic [ref=e84]: Start with one topic to seed the graph, or use a curated path card to watch WikiWebMap search for a bridge between two ideas.
+  - generic:
+    - generic: Hover a connection line for context. Click a line to pin it.

.preview.pid

@@ -0,0 +1 @@
+34580

README.md

@@ -31,7 +31,7 @@ Live: `https://wikiconnectionsmap.web.app/`
 - GitHub Actions validates pull requests and publishes Firebase preview channels before merge.
 - Merges to `main` deploy to Firebase Hosting live.
 - Bluehost is assumed to be used only for DNS or custom-domain management unless you have separate hosting outside this repo.
-- See `docs/deployment.md`, `docs/release-checklist.md`, `docs/release-prep.md`, `docs/development-plan.md`, `docs/ai-api-mcp-plan.md`, and `docs/env-inventory.md` for release workflow details.
+- See `docs/deployment.md`, `docs/release-checklist.md`, `docs/release-prep.md`, `docs/development-plan.md`, `docs/ux-effects-plan.md`, `docs/ai-api-mcp-plan.md`, and `docs/env-inventory.md` for release workflow details.
 
 ## Controls (high level)
 - Drag canvas to pan; scroll to zoom.

docs/ux-effects-plan.md

@@ -0,0 +1,183 @@
+# UX And Web Effects Plan
+
+## Goal
+
+Make WikiWebMap feel more legible, more intentional, and more polished without destabilizing the production graph experience.
+
+This plan focuses on:
+- first-run clarity
+- mobile usability
+- interaction feedback
+- visual hierarchy
+- motion/effects that support understanding instead of distracting from it
+
+## Design direction
+
+The product should feel like:
+- a research instrument, not a generic dashboard
+- visually alive, but still readable
+- fast and tactile on desktop
+- guided and spacious on mobile
+
+Core principles:
+- Motion should explain state changes.
+- Effects should reinforce graph relationships.
+- Panels should never compete with the graph for attention.
+- The first 30 seconds of use should feel obvious.
+
+## Biggest current UX gaps
+
+### 1. First-run orientation is still weak
+- New users do not get a strong explanation of what to do first.
+- Suggested paths help, but the screen still relies on inference.
+
+### 2. Mobile feels functional, not polished
+- The mobile sheets are safer now, but they still feel like adapted desktop UI.
+- Important actions are present, but the experience is not yet elegant.
+
+### 3. Visual hierarchy is flat in places
+- The search box, graph, connection context, settings, and diagnostics all compete.
+- There is not yet a strong “primary task” rhythm on load.
+
+### 4. Motion is mostly utilitarian
+- The graph has energy, but UI transitions and contextual reveals are still basic.
+- There is room for effects that make cause-and-effect easier to understand.
+
+### 5. Trust/polish is improving but not complete
+- The product is closer to professional release quality now, but the brand/system still needs a more cohesive finish.
+
+## Recommended rollout
+
+### Phase 1: Clarity pass
+Goal:
+- Make the product easier to understand in the first minute.
+
+Changes:
+- Replace the current “just search” feeling with a stronger first-run prompt.
+- Add a short guided intro block above or below the search input.
+- Clarify the value of suggested paths with better microcopy.
+- Improve empty-state language for path search, logs, and connection context.
+
+Suggested UI work:
+- Add a “Start here” card in [SearchOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchOverlay.tsx)
+- Add one-line purpose text under the title
+- Give suggested paths short category labels such as “Science”, “Culture”, or “Surprising”
+- Refine helper text in [SearchStatusOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchStatusOverlay.tsx)
+
+Risk:
+- Low
+
+### Phase 2: Mobile UX pass
+Goal:
+- Make the mobile experience feel intentionally designed, not merely adapted.
+
+Changes:
+- Turn node details into a more polished bottom sheet with snap-point behavior styling.
+- Make connection context feel like a real mobile drawer instead of a floating status panel.
+- Prevent panel overlap between search, status, node details, and diagnostics.
+- Improve touch-target sizes and spacing consistency.
+
+Suggested UI work:
+- Refine [NodeDetailsPanel.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/NodeDetailsPanel.tsx)
+- Refine [ConnectionStatusBar.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/ConnectionStatusBar.tsx)
+- Revisit mobile layout in [GraphControls.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/GraphControls.tsx)
+- Consider a mobile-specific diagnostics entry point in [LogPanel.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/LogPanel.tsx)
+
+Risk:
+- Medium
+
+### Phase 3: Motion and effects pass
+Goal:
+- Add effects that teach the graph and reward interaction.
+
+Changes:
+- Animate panel entrances with consistent timing and easing.
+- Add subtle reveal/stagger behavior for suggested paths and search results.
+- Make path discovery feel more cinematic when a result resolves.
+- Add better hover/focus lighting for nodes and connections.
+- Add a soft “state handoff” animation when restoring graph state after an aborted search.
+
+Suggested effects:
+- Search panel fade/slide on first load
+- Node details sheet spring-in on mobile
+- Context drawer expand/collapse animation
+- Path result pulse or trace effect in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts)
+- Softer background parallax or light-field drift in [LensingGridBackground.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/LensingGridBackground.tsx)
+
+Guardrails:
+- Keep transitions short
+- Respect `prefers-reduced-motion`
+- Avoid effects that obscure text or graph readability
+
+Risk:
+- Medium
+
+### Phase 4: Visual system polish
+Goal:
+- Make the whole interface feel like one product, not a collection of good components.
+
+Changes:
+- Tighten typography hierarchy and repeated component spacing.
+- Standardize panel treatments, border opacity, blur strength, and button emphasis.
+- Replace any remaining “default utility look” with a stronger visual language.
+- Align iconography and CTA weight across controls.
+
+Suggested UI work:
+- Normalize shared panel/button styles in [index.css](/C:/Users/monro/Codex/WikiWebMap/src/index.css)
+- Unify the title/search/header feel in [SearchOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchOverlay.tsx)
+- Harmonize floating surfaces across [GraphControls.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/GraphControls.tsx), [SearchStatusOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchStatusOverlay.tsx), and [ConnectionStatusBar.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/ConnectionStatusBar.tsx)
+
+Risk:
+- Low to medium
+
+### Phase 5: Trust and product finish
+Goal:
+- Make the app feel release-grade to a new visitor.
+
+Changes:
+- Add slightly better product framing and explanation of what makes the map useful.
+- Improve brand consistency in copy and headings.
+- Make diagnostics/logging feel intentionally “advanced mode” instead of accidental.
+- Add subtle success states when major actions complete.
+
+Suggested UI work:
+- Better product framing in [README.md](/C:/Users/monro/Codex/WikiWebMap/README.md) and the app header
+- Stronger loading, success, and empty-state language
+- Cleaner affordances for diagnostics access
+
+Risk:
+- Low
+
+## High-impact UX tasks
+
+### Top 5 to do next
+1. Add a stronger first-run search/onboarding block in [SearchOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchOverlay.tsx)
+2. Convert connection context into a more deliberate mobile/desktop drawer pattern in [ConnectionStatusBar.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/ConnectionStatusBar.tsx)
+3. Add motion rules and shared transitions in [index.css](/C:/Users/monro/Codex/WikiWebMap/src/index.css)
+4. Polish the node details sheet in [NodeDetailsPanel.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/NodeDetailsPanel.tsx)
+5. Add a more expressive path-result reveal in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts)
+
+## Safe implementation order
+
+1. Copy and hierarchy improvements
+2. Mobile sheet/drawer layout cleanup
+3. Shared motion tokens and reduced-motion handling
+4. Path-result visual effects
+5. Larger brand/style polish
+
+This order keeps the highest-value improvements low-risk at the start.
+
+## Suggested success criteria
+
+- A new user can understand what to do in under 10 seconds.
+- Mobile users can complete a topic search and a path search without confusion.
+- Panels no longer feel crowded or overlapping.
+- Motion makes state changes clearer instead of noisier.
+- The app feels more premium without slowing down the graph.
+
+## Recommended branch strategy
+
+- Ship UX copy and hierarchy changes in one branch.
+- Ship mobile panel/layout polish in a separate branch.
+- Ship effects/motion work in a separate branch after the layout stabilizes.
+- Keep `GraphManager.ts` effect changes isolated from broader refactors.