Spheres4Dummies

High-performance, keyboard-first reference wiki for the Pathfinder 1e Spheres system — Spheres of Power (magic), Spheres of Might (combat), Spheres of Guile (skill), and Champions of the Spheres (hybrid classes). Rules text is reproduced verbatim — no interpretation, no summarization, no collapsible sections.

Live site: https://spheres4dummies.rulytafzil.com

Features

• ⚡ Fully static: Next.js 15 App Router with output: "export" — 160 prerendered routes, zero server, edge CDN on Vercel.
• ⌨️ Keyboard-first: Press / or Ctrl+K for global search across all 9,000+ rule cards, talents, feats, archetypes, and classes. Arrow-key navigation, Tab/Enter tag autocomplete.
• 🔗 Cross-referenced rules: Sphere mentions ("light sphere"), feat names, and magic/combat talent names across all rule text are auto-linked; hovering a dotted-underline reference shows the linked item's full rules text in-place (scrollable panel, fetched per page on demand) without leaving the page.
• 🔖 Notebook: Pin any card to a persistent Notebook (localStorage), drag-and-drop sidebar, full Notebook build page.
• 🏷️ Faceted tags & badges: Every item carries a strict lowercase kebab-case tag taxonomy rendered as weighted semantic badges.
• 🌗 Dark mode: Class-based theming with FOUC-free startup, persisted preference.
• 📖 Faithful rendering: Raw HTML content blocks preserve all tables, lists, bold/italic, and links from the source wiki.

Content

Dataset	Count
Magic spheres (Spheres of Power)	26 spheres — 1,602 talents, 651 feats, 161 archetypes, 170 drawbacks
Combat spheres (Spheres of Might)	26 spheres — 1,459 talents, 3 feats, 29 archetypes, 157 drawbacks
Skill spheres (Spheres of Guile)	16 spheres — 850 talents, 57 feats, 46 archetypes, 72 drawbacks
Classes	56 — 12 spherecasters, 9 practitioners, 7 operatives, 12 champions, 16 prestige
Feats catalog	30 categories — 1,021 feats
Rule hubs	Casting Traditions & draws, Martial Traditions & combat drawbacks
Search index	9,231 indexed items across 160 static routes
Link-preview index	9,129 previewable URLs (hover tooltips) with per-page full-content bundles

Architecture

raw/  ── scraper ──►  mirror/ (local wiki HTML)
 │
 ├── scripts/parse_*.py   ──►  src/content/**/*.json
 │       │                          │
 │       └── specs/classes/         ▼
 │           (56 declarative  spec_engine.py
 │            class JSON specs)    (3-layer outline engine)
 │
 └── scripts/build_search_index.py ──► search-index.json (9,231 items)

• Parsers (scripts/): Convert scraped Wikidot pages into structured JSON — spheres, feats, traditions, and classes.
• Declarative spec engine (scripts/core/spec_engine.py + specs/classes/): All 56 classes are driven by JSON specs matched against the page DOM outline — features, modular option groups, class equipment, alternate class features.
• Search index (scripts/build_search_index.py): Unified index covering every rendered kind — features, options, feats, archetypes, FCB hubs, sphere content.
• Audit gate (scripts/audit.py): 6 deterministic checks (schema, tags, structure, specs, ToC/anchor sync, wiki ToC coverage) — must pass with 0 errors before every commit/deploy.

Badge Architecture & Tiering

All visual badges are deterministically projected from item.tags via resolveItemBadges(item) in src/utils/tagStyles.ts using a 5-tier priority hierarchy:

1. Tier 1 (Weight 10) - Root Hub: [Sphere], [Class]
2. Tier 2 (Weight 20) - Context: Parent Sphere ([Blood], [Creation], [Berserker]), Feat Category ([Combat], [Item Creation], [General], [Purring]), or Class ([Armorist], [Dissident]).
3. Tier 3 (Weight 30) - Type & Mechanism: [Talent], [Feat], [Archetype], [Drawback], [Class Feature], or specific class option group ([Mystic Combat], [Arsenal Tricks]).
4. Tier 4 (Weight 40 & 45) - Progression & Hit Die: [High], [Mid], [Expert], [Virtuoso], [d6], [d8], [d10], [d12].
5. Tier 5 (Weight 50) - Modifiers: [3PP], [Advanced], [Dual Sphere], [Legendary].

Drawback Rule: All drawbacks resolve to all associated sphere badges first, followed exclusively by [Drawback] (e.g. [Dark] [Telekinesis] [Drawback], [Dark] [Drawback], [General] [Drawback]).

Getting Started

npm install
npm run dev          # local dev server

Building & Deploying

# 1. Re-parse content (as needed)
python3 scripts/parse_all_magic_spheres.py
python3 scripts/parse_all_combat_spheres.py
python3 scripts/parse_all_skill_spheres.py
python3 scripts/parse_spherecaster_classes.py
python3 scripts/parse_practitioner_classes.py
python3 scripts/parse_operative_classes.py
python3 scripts/parse_champion_classes.py
python3 scripts/parse_prestige_classes.py
python3 scripts/parse_all_feats.py
python3 scripts/parse_casting_traditions.py
python3 scripts/parse_martial_traditions.py
python3 scripts/unify_sphere_feats.py
python3 scripts/linkify_content.py
python3 scripts/build_search_index.py

# 2. Audit gate (0 errors required)
python3 scripts/audit.py

# 3. Compile and deploy to Vercel
vercel build --prod
vercel deploy --prebuilt --archive=tgz --prod --yes

Local preview of a built export (no deploy):

npm run build && python3 serve.py
# serves out/ at http://localhost:8080

Project Structure

├── specs/classes/          # 56 declarative class JSON specs (spherecasters/, practitioners/, operatives/, champions/, prestige/)
├── specs/spheres/          # 68 declarative sphere JSON specs (magic/ + combat/ + skill/, ToC-guided)
├── specs/pages/using/     # 4 declarative Using Spheres of X guide-page specs
├── scripts/
│   ├── core/               # loader, sanitizer, tag_extractor, archetype_parser, spec_engine
│   ├── parse_*.py          # content parsers (spheres, feats, traditions, classes)
│   ├── linkify_content.py  # auto-hotlinks feat-name mentions (.preview-link anchors)
│   ├── build_search_index.py
│   └── audit.py            # standing audit gate
├── src/
│   ├── app/                # Next.js App Router pages (classes/, spheres/, feats/, rules/ incl. using/*, notebook/, license/)
│   ├── components/         # ClassView, SphereView, FeatView, CommandPalette, PageFilterBar, SidebarTOC, RuleCard, LinkPreviewTooltip, ...
│   ├── content/            # Generated JSON datasets + search/link-preview indexes + copyright notices
│   ├── hooks/              # useCardFilter, NotebookContext, useLinkPreview
│   ├── types/sphere.ts     # Shared data model
│   └── utils/              # tagStyles (badge system), searchRank (scoring)
├── raw/                    # Cached raw Wiki HTML (source of truth for parsers)
├── mirror/                 # Local wiki mirror files
└── .agent                  # Full agent workspace & architecture reference (deep dive)

Deep-dive reference: .agent is the canonical, ground-truth architecture document — spec engine internals, tag taxonomy, UI contracts, lessons learned, and the roadmap. Read it before making architectural changes.

License

The repository includes the full OGL 1.0a license text and 1,215 Section 15 copyright notices (src/content/legal/copyright-notices.json), viewable at /license.