# wanessalabs-astro - Full Ingestion Context

> The Wanessa Labs front door at **[wanessalabs.com](https://wanessalabs.com)**. Static Astro site, no backend, deployed to Cloudflare Pages.

---

## 1. Project Overview & Architecture
# wanessalabs-astro

The Wanessa Labs front door at **[wanessalabs.com](https://wanessalabs.com)**. Static Astro site, no backend, deployed to Cloudflare Pages.

Canonical project docs: `prd.md` (why), `lineage.md` (decisions), `roadmap.md` (what's next).
Brand and tokens: `design/brand.md` + `design/tokens.css`. **Read those before any UI work. Never hardcode a colour or a size.**

## Commands

| Command | Action |
|---|---|
| `npm install` | Install dependencies |
| `npm run dev` | Dev server on `localhost:4321` |
| `npm run build` | Build to `./dist/` |
| `npm run preview` | Serve the built output locally |
| `npx astro check` | Typecheck (expect 0 errors) |
| `npm run timeline` | Regenerate `src/data/projects-timeline.json` from vault lineage files. Manual, never part of the build. See `scripts/README-timeline.md` |
| `npm run test:timeline` | Parser + redaction tests for the timeline exporter |

## Deploy

Cloudflare Pages project **`wanessalabs-com`**, `pages_build_output_dir = "dist"`.

**Pushing `main` already deploys this site.** The project is Git-connected: run
`wrangler pages deployment list` and the Production rows carry a commit SHA in the
Source column. Confirmed 2026-08-19, when a push built and went live on its own and a
manual upload afterwards was redundant. Reach for the manual command below only to ship
content that is not committed, or to redeploy without a new commit. A manual upload
lands as a Production deployment with an empty Source, which is the tell that it did not
come from a build.

```sh
npx wrangler pages deploy dist --project-name=wanessalabs-com --branch=main
```

**Wrangler prefers the git branch it detects over the `--branch` flag.** Run the command above from inside this repo on a feature branch and it lands in **Preview** despite `--branch=main`, printing a "Deployment alias URL" line when it does.

The operative variable is git *detection*, not which branch you are on. Copy `dist` somewhere outside any git repo and deploy from there, and `--branch=main` is honoured:

```sh
cp -r dist "$SCRATCH/deploy" && cd "$SCRATCH/deploy"
npx wrangler pages deploy . --project-name=wanessalabs-com --branch=main
```

Verified 2026-07-29: Production `5e3bf4d2` shipped this way while the working tree sat on `feat/13-cards-docs`. This matters because merging to `main` is the owner's call, so a deploy must never require it. Always confirm the environment rather than trusting the success message:

```sh
npx wrangler pages deployment list --project-name=wanessalabs-com
```

## Structure

```
src/
├── components/          Astro components
│   ├── ProjectMindMap.astro   /projects map: canvas mount + DOM label layer + accordion
│   ├── ProjectGlyph.astro     51 hand-authored 24x24 line marks, keyed by slug
│   ├── ProjectMark.astro      illustrated artwork on detail pages, glyph fallback
│   └── ProjectVisual.astro    per-project hero illustrations
├── content/
│   └── projects/        One markdown file per project. Frontmatter drives the catalog.
├── data/
│   ├── projects-timeline.json   Committed, generated. Do not hand-edit.
│   └── timeline-manual.json     Hand-curated history from extracted repos.
├── layouts/BaseLayout.astro   head, SEO, OG/Twitter meta, fonts
├── pages/               File-based routes
├── scripts/mindmap3d.ts       3D force sim + three.js scene + label projector
└── styles/global.css    Design tokens and shared component CSS

scripts/                 Node, run by hand. Not part of the build.
├── projects-timeline-export.mjs   Allowlist -> parse -> redact -> committed JSON
├── timeline-allowlist.json        The publish allowlist. Fail-closed.
├── lib/                           Parser and redaction rules
└── README-timeline.md             How to refresh it, and what the rules are
```

Content is markdown in `src/content/`. Adding a project means adding a file; nothing else needs editing.

## The projects map

`/projects` renders every project as a 3D force-directed graph. The architecture is deliberate and worth understanding before changing it:

- **three.js draws geometry only** (bubbles and 1px edges). No text is ever rendered into the canvas.
- **Every label stays a real DOM `<a>`/`<button>`**, positioned over the canvas each frame from its node's projected 3D coordinate.

That split is not stylistic. A label in the DOM can be *measured*, so before it is placed it checks its box against every label and bubble already on screen, tries 12 anchor positions around its node, and hides rather than overlap. The previous version placed nodes from hardcoded pixel coordinates with a fixed fan-out angle and could not measure anything, so it collided its own labels once a track passed roughly a dozen projects. Keeping labels in the DOM is also what preserves keyboard navigation and crawlable project links.

- **Positions are never authored.** A force simulation (`mindmap3d.ts`) solves them at runtime, so a new project re-solves the layout rather than needing coordinates.
- **`three` is dynamically imported, desktop-only (>=768px), after the map scrolls into view.** So is `mindmap3d.ts` itself. Mobile downloads neither.
- **The accordion is both the mobile surface and the desktop fallback** for no-JS, no-WebGL, a failed chunk, and WebGL context loss. The map area must never render as an empty box.

Full rationale: `lineage.md` (2026-07-29) and `docs/superpowers/specs/2026-07-29-projects-3d-mindmap-design.md`.

## SEO and social

`BaseLayout.astro` owns canonical URL, OG, and Twitter meta. The default share card is `public/og-default.png` (1200x630); pass `ogImage` to override it per page.

## Conventions

- **Zero em dashes in user-facing copy.** Hard brand rule. Use a colon, period, or comma.
- Every shipped project gets a page in `src/content/projects/`.
- Elevation is borders-only. No shadows on this surface; that ramp belongs to the games hub.
- **Design tokens live in `src/styles/global.css`, not `design/tokens.css`.** The latter is a
  spec file the site does not import: `--on-accent`, `--radius-*`, `--ease-signature` and
  `--font-*` are declared there and resolve to nothing at runtime. See the note in `404.astro`.
- The timeline dataset is read in frontmatter only. **No component may take a client
  directive on it** — it is ~98 kB and none of it needs to reach the browser.



## 3. Machine & Robot Information
- Canonical manifest: /llms.txt
- Full context: /llms-full.txt
- Robots policy: /robots.txt