feat: balance root layout and add project attribution

Author: StoneHub

AGENTS.md

@@ -10,13 +10,16 @@
 - Read `docs/deployment.md` and `docs/release-checklist.md` before changing CI or release behavior.
 - When touching the new layout/mobile flow, read `docs/ux-effects-plan.md`.
 - When touching the React Flow renderer or alternate view modes, read `docs/react-flow-structured-view-plan.md`.
+- When touching public attribution, Wikimedia references, or API-identification behavior, also check `README.md` and `NOTICE`.
 
 ## Working Rules
 - Read the existing code and docs before changing behavior.
 - Prefer minimal, local changes over broad rewrites.
 - If a task spans multiple files, the most likely hotspots are `src/App.tsx`, `src/GraphManager.ts`, `src/components/*`, `src/features/structured-view/*`, `src/hooks/useGraphState.ts`, and matching tests under `src/`.
 - Do not commit generated local artifacts such as `.preview.*` or `.playwright-cli/`.
 - If instructions or release steps seem stale, call that out explicitly in the handoff.
+- For graph-layout changes, sanity-check first-load behavior with at least two root topics in `web` mode before calling the UX done.
+- For Wikimedia/API wording, verify against official Wikimedia policy pages and keep the UI notice, `README.md`, and `NOTICE` aligned.
 
 ## Verification
 - Install dependencies with `npm ci`.

NOTICE

@@ -5,4 +5,5 @@ Copyright 2025 Monroe
 This product includes software developed by the WikiWebMap contributors.
 
 Wikipedia content and page metadata are provided by the Wikimedia Foundation and are
-licensed under CC BY-SA 4.0. This project is not affiliated with Wikimedia Foundation.
+licensed under CC BY-SA 4.0. This project is not affiliated with or endorsed by the Wikimedia Foundation.
+Wikipedia is a trademark of the Wikimedia Foundation.

README.md

@@ -3,6 +3,8 @@
 Explore Wikipedia topics as an interactive graph: expand nodes, search for connections between topics, and visualize link context.
 
 Live: `https://wikiconnectionsmap.web.app/`
+Website: `https://monroes.tech`
+GitHub: `https://github.com/StoneHub/WikiWebMap`
 
 ## Quickstart
 
@@ -48,5 +50,12 @@ Live: `https://wikiconnectionsmap.web.app/`
 ## License
 Apache-2.0. See `LICENSE`.
 
+## Ownership, API, and Wikimedia Notice
+- This repo is currently Apache-2.0. That means attribution and branding help establish authorship, but they do not prevent someone else from reusing or forking the code under the license terms.
+- Set `VITE_WIKI_API_CONTACT_EMAIL` so requests send a descriptive `Api-User-Agent` header to Wikipedia.
+- The app rate-limits and caches Wikipedia requests, and `VITE_RECAPTCHA_SITE_KEY` can be used to reduce automated abuse on the client side.
+- Wikipedia is a trademark of the Wikimedia Foundation. WikiWebMap is an independent project and is not affiliated with or endorsed by the Wikimedia Foundation.
+
 ## Attribution
-- Wikipedia/Wikimedia content is licensed under CC BY-SA 4.0. This project is not affiliated with the Wikimedia Foundation.
+- Wikipedia/Wikimedia content is licensed under CC BY-SA 4.0.
+- This project is not affiliated with or endorsed by the Wikimedia Foundation.

docs/development-plan.md

@@ -9,6 +9,9 @@ This repo is now in a safer release-ready state than it was at clone time:
 - Mobile guidance and destructive actions are safer.
 - The repo now has unit coverage for `WikiService`, `runPathfinder`, and `useGraphState` reset/restore behavior.
 - Session diagnostics now include both connection logs and captured client runtime errors.
+- `web` mode now seeds root topics from root-count-aware positions instead of total-node-count drift, which keeps first-load layouts more balanced.
+- Project attribution and external links now live with the bottom-left graph tools on desktop, with matching ownership/Wikimedia notice language in the UI and docs.
+- Neutral placeholder art now avoids leaning on Wikimedia-looking fallback branding when a topic has no thumbnail.
 
 Renderer planning note:
 - The next radically different visualization experiment is a React Flow-based `Structured View`; see `docs/react-flow-structured-view-plan.md`.
@@ -115,6 +118,12 @@ Recommended order:
 | P6 | UX | Improve onboarding and mobile drawer polish | Increases usability and product trust | Medium | Low | Phase 5 |
 | P7 | Observability | Add remote client error reporting | Makes live issues easier to diagnose after release | Medium | Low | Phase 5 |
 
+## Immediate next improvements
+
+1. Add a one-click `Spread Roots` action so users can quickly recreate the “pull major topics apart, let the inner nodes congregate” layout they naturally discovered.
+2. Turn current link-strength scoring into clearer visual language with a legend entry for strong ties, shared-neighbor ties, and cross-branch bridges.
+3. Add a small server-side or edge cache/proxy layer for Wikipedia requests so abuse control, request budgets, and API identification are no longer purely client-enforced.
+
 ## Branch strategy
 
 - Use a release PR to merge the current hardening work to `main`.

docs/ux-effects-plan.md

@@ -31,6 +31,10 @@ Core principles:
 - New users do not get a strong explanation of what to do first.
 - Suggested paths help, but the screen still relies on inference.
 
+### 1a. First-load spatial rhythm still needs refinement
+- Root topics now seed more intelligently, but web mode still needs stronger first-load balance when multiple major topics are added quickly.
+- The most successful layouts still happen after a user drags roots outward and lets inner topics settle between them.
+
 ### 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.
@@ -39,6 +43,10 @@ Core principles:
 - The search box, graph, connection context, settings, and diagnostics all compete.
 - There is not yet a strong “primary task” rhythm on load.
 
+### 3a. Topic visuals are improving but still have room to mature
+- Nodes now have softer halos and better root emphasis, but the graph still does not fully communicate connection importance at a glance.
+- Link weight and branch significance are still more present in the data than in the visuals.
+
 ### 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.
@@ -48,6 +56,23 @@ Core principles:
 
 ## Recommended rollout
 
+### Phase 0: Space and trust pass
+Goal:
+- Make the first-loaded graph feel more balanced and make project ownership/independence clearer without crowding the main panel.
+
+Changes:
+- Keep root topics on soft perimeter anchors in `web` mode instead of letting total node count fling them outward.
+- Preserve the lower-left authorship/trust strip as part of the graph tool area rather than the intro panel.
+- Continue using neutral custom placeholder artwork instead of anything that could read as Wikimedia branding.
+
+Suggested UI work:
+- Tune soft-anchor strength and perimeter radius logic in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts)
+- Tune first-seed and multi-seed spawn logic in [useGraphState.ts](/C:/Users/monro/Codex/WikiWebMap/src/hooks/useGraphState.ts)
+- Keep attribution and external-link surfaces coordinated between [GraphControls.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/GraphControls.tsx), [SearchOverlay.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/SearchOverlay.tsx), and [README.md](/C:/Users/monro/Codex/WikiWebMap/README.md)
+
+Risk:
+- Low
+
 ### Phase 1: Clarity pass
 Goal:
 - Make the product easier to understand in the first minute.
@@ -151,11 +176,11 @@ Risk:
 ## 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)
+1. Add a “root spread” assist in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts) so major topics land in cleaner perimeter positions before the user drags them
 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)
+3. Add weighted link styling and legend language so strong/shared-topic bridges read immediately in [GraphManager.ts](/C:/Users/monro/Codex/WikiWebMap/src/GraphManager.ts) and [GraphControls.tsx](/C:/Users/monro/Codex/WikiWebMap/src/components/GraphControls.tsx)
 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)
+5. Add motion rules and shared transitions in [index.css](/C:/Users/monro/Codex/WikiWebMap/src/index.css)
 
 ## Safe implementation order
 

index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>WikiWeb Explorer - Interactive Wikipedia Knowledge Graph</title>
+    <title>WikiWebMap - Interactive Graph for Wikipedia Topics</title>
   </head>
   <body class="m-0 p-0 overflow-hidden">
     <div id="root"></div>

scripts/smoke.mjs

@@ -28,6 +28,8 @@ try {
   const page = await browser.newPage({ viewport: { width: 1365, height: 900 } });
   await slowWikipediaRequests(page);
   await page.goto(baseUrl, { waitUntil: 'networkidle' });
+  await page.getByRole('link', { name: 'monroes.tech' }).waitFor({ timeout: 15000 });
+  await page.getByRole('link', { name: 'GitHub' }).waitFor({ timeout: 15000 });
 
   await page.getByRole('textbox', { name: 'Search a Wikipedia topic' }).fill('Physics');
   await page.getByRole('button', { name: 'Start Exploration' }).click();

src/GraphManager.ts

@@ -419,15 +419,43 @@ export class GraphManager {
   private getCollisionRadius(node: Node) {
     const connections = this.degreeById.get(node.id) || 0;
     const meta = this.getMetadata(node.id);
-    const layoutBoost = this.usesGuidedTreeLayout() && meta.colorRole === 'root'
-      ? (this.isStructuredMapMode() ? 8 : 6)
+    const layoutBoost = meta.colorRole === 'root'
+      ? (this.usesGuidedTreeLayout() ? (this.isStructuredMapMode() ? 8 : 6) : 10)
       : 0;
     return (Math.min(30 + connections * 0.5, 60) * this.nodeSizeScale) + layoutBoost;
   }
 
+  private getWebRootAnchor(nodeId: string) {
+    const rootIds = this.nodes
+      .filter((candidate) => !this.hiddenNodeIds.has(candidate.id) && this.getMetadata(candidate.id).colorRole === 'root')
+      .map((candidate) => candidate.id);
+    const index = rootIds.indexOf(nodeId);
+    const center = { x: this.width / 2, y: this.height / 2 };
+
+    if (index === -1 || rootIds.length <= 1) return center;
+
+    const count = rootIds.length;
+    const startAngle = count === 2 ? Math.PI : -Math.PI / 2;
+    const angle = startAngle + (index / count) * Math.PI * 2;
+    const radiusX = count === 2
+      ? Math.max(180, Math.min(this.width * 0.22, 320))
+      : Math.max(180, Math.min(this.width * 0.28, 360));
+    const radiusY = count === 2
+      ? Math.max(24, Math.min(this.height * 0.04, 48))
+      : Math.max(120, Math.min(this.height * 0.24, 260));
+
+    return {
+      x: center.x + Math.cos(angle) * radiusX,
+      y: center.y + Math.sin(angle) * radiusY,
+    };
+  }
+
   private getChargeStrength(node: Node) {
-    if (this.layoutMode === 'web') return -500;
     const meta = this.getMetadata(node.id);
+    if (this.layoutMode === 'web') {
+      if (meta.colorRole === 'root') return -920;
+      return -340;
+    }
     if (this.isStructuredMapMode()) {
       if (meta.colorRole === 'root') return -340;
       if (meta.layoutDepth !== undefined && meta.layoutDepth > 2) return -190;
@@ -437,24 +465,31 @@ export class GraphManager {
   }
 
   private getLayoutTarget(node: Node) {
-    if (!this.usesGuidedTreeLayout()) {
-      return { x: this.width / 2, y: this.height / 2 };
-    }
-
     const meta = this.getMetadata(node.id);
     if (meta.isPinned && meta.manualPosition) {
       return meta.manualPosition;
     }
 
+    if (!this.usesGuidedTreeLayout()) {
+      if (meta.colorRole === 'root') {
+        return this.getWebRootAnchor(node.id);
+      }
+      return { x: this.width / 2, y: this.height / 2 };
+    }
+
     return this.forestTargets.get(node.id) || {
       x: node.x ?? this.width / 2,
       y: node.y ?? this.height / 2,
     };
   }
 
   private getTargetStrength(node: Node) {
-    if (!this.usesGuidedTreeLayout()) return 0.02;
     const meta = this.getMetadata(node.id);
+    if (!this.usesGuidedTreeLayout()) {
+      if (meta.isPinned) return 0.36;
+      if (meta.colorRole === 'root') return 0.1;
+      return 0.008;
+    }
     if (meta.isPinned) return 0.4;
     if (this.isStructuredMapMode()) {
       if (meta.colorRole === 'root') return 0.24;
@@ -465,7 +500,15 @@ export class GraphManager {
   }
 
   private getLinkDistance(link: Link) {
-    if (!this.usesGuidedTreeLayout()) return this.nodeSpacing;
+    if (!this.usesGuidedTreeLayout()) {
+      const sourceId = typeof link.source === 'object' ? link.source.id : link.source;
+      const targetId = typeof link.target === 'object' ? link.target.id : link.target;
+      const sourceMeta = this.getMetadata(sourceId);
+      const targetMeta = this.getMetadata(targetId);
+      const touchesRoot = sourceMeta.colorRole === 'root' || targetMeta.colorRole === 'root';
+      if (link.layoutRole === 'cross') return Math.max(this.nodeSpacing * 0.82, 108);
+      return touchesRoot ? Math.max(this.nodeSpacing * 0.92, 124) : Math.max(this.nodeSpacing * 0.8, 104);
+    }
     if (this.isStructuredMapMode()) {
       return link.layoutRole === 'cross'
         ? Math.max(this.nodeSpacing * 0.6, 96)
@@ -1502,8 +1545,35 @@ export class GraphManager {
 
       const radius = this.getCollisionRadius(d) - (this.usesGuidedTreeLayout() && meta.colorRole === 'root' ? 6 : 0);
       const focusScale = this.getFocusScale(meta);
+      const nodeColor = this.getNodeColor(d.id, meta);
       inner.attr('transform', `scale(${focusScale})`);
 
+      const auraData: Array<{
+        radius: number;
+        fill: string;
+        opacity: number;
+      }> = meta.isFocusTarget
+        ? [{ radius: radius + 16, fill: '#22d3ee', opacity: 0.12 }]
+        : meta.isPathEndpoint
+          ? [{ radius: radius + 14, fill: '#f59e0b', opacity: 0.14 }]
+          : meta.isPinned
+            ? [{ radius: radius + 13, fill: '#e2e8f0', opacity: 0.1 }]
+            : meta.colorRole === 'root'
+              ? [{ radius: radius + 12, fill: nodeColor, opacity: 0.16 }]
+              : [];
+
+      inner
+        .selectAll<SVGCircleElement, typeof auraData[number]>('circle.node-aura')
+        .data(auraData)
+        .join(
+          (enterSelection) => enterSelection.append('circle').attr('class', 'node-aura'),
+          (updateSelection) => updateSelection,
+          (exitSelection) => exitSelection.remove()
+        )
+        .attr('r', (aura) => aura.radius)
+        .attr('fill', (aura) => aura.fill)
+        .attr('fill-opacity', (aura) => aura.opacity);
+
       const outerRingData: Array<{
         radius: number;
         stroke: string;
@@ -1551,12 +1621,39 @@ export class GraphManager {
           (updateSelection) => updateSelection
         )
         .attr('r', radius)
-        .attr('fill', this.getNodeColor(d.id, meta))
+        .attr('fill', nodeColor)
         .attr('fill-opacity', meta.thumbnail ? 0.3 : 1)
         .attr('stroke', this.getNodeStroke(meta))
         .attr('stroke-width', this.getNodeStrokeWidth(meta))
         .attr('filter', meta.isFocusTarget ? 'url(#focus-glow)' : meta.isFocusNeighbor ? 'url(#neighbor-glow)' : null);
 
+      inner
+        .selectAll<SVGCircleElement, Node>('circle.node-inner-ring')
+        .data([d])
+        .join(
+          (enterSelection) => enterSelection.append('circle').attr('class', 'node-inner-ring'),
+          (updateSelection) => updateSelection
+        )
+        .attr('r', Math.max(8, radius * 0.74))
+        .attr('fill', 'none')
+        .attr('stroke', 'rgba(255,255,255,0.22)')
+        .attr('stroke-width', Math.max(0.9, 1.1 * this.nodeSizeScale))
+        .attr('stroke-opacity', meta.thumbnail ? 0.12 : meta.isDimmed ? 0.1 : 0.24);
+
+      inner
+        .selectAll<SVGEllipseElement, Node>('ellipse.node-sheen')
+        .data([d])
+        .join(
+          (enterSelection) => enterSelection.append('ellipse').attr('class', 'node-sheen'),
+          (updateSelection) => updateSelection
+        )
+        .attr('rx', Math.max(6, radius * 0.38))
+        .attr('ry', Math.max(4, radius * 0.22))
+        .attr('cx', -radius * 0.16)
+        .attr('cy', -radius * 0.22)
+        .attr('fill', 'rgba(255,255,255,0.16)')
+        .attr('fill-opacity', meta.thumbnail ? 0.08 : meta.isDimmed ? 0.06 : 0.16);
+
       this.addTextLabel(inner as any, d.title, radius);
     });