Fjord town

.claude/hooks/game-session-start.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# SessionStart hook: puts the Fjord Town handoff, the open tasks of the current
+# milestone and recent git state into the session context. Plain stdout from a
+# SessionStart hook is added to Claude's context.
+set -u
+
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+branch="$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)"
+# The kai branches work on the engine split, which keeps its own plan and handoff.
+case "$branch" in
+	kai | kai/*) rel="docs/kai"; title="kai engine split" ;;
+	*) rel="apps/datagutt/docs"; title="Fjord Town game project" ;;
+esac
+docs="$root/$rel"
+[ -f "$docs/HANDOFF.md" ] || exit 0
+
+echo "## $title: session context"
+echo
+echo "Branch: $branch. Decisions are in $rel/DESIGN.md and must not be re-litigated."
+echo "Update $rel/HANDOFF.md and tick $rel/PLAN.md boxes in the same commit as the work."
+echo
+cat "$docs/HANDOFF.md"
+echo
+
+if [ -f "$docs/PLAN.md" ]; then
+	# Print the first milestone section that still has unticked tasks, open tasks only.
+	awk '
+		/^## [MK][0-9]+:/ { if (found) exit; heading = $0; open = 0; next }
+		/^## / { if (found) exit; heading = ""; next }
+		heading != "" && /^- \[ \] \*\*/ {
+			if (!found) { print "## Open tasks in current milestone"; print heading; found = 1 }
+			print; inTask = 1; next
+		}
+		/^- \[/ { inTask = 0; next }
+		inTask && /^      / { print; next }
+		{ inTask = 0 }
+	' "$docs/PLAN.md"
+	echo
+fi
+
+echo "## Git state"
+git -C "$root" log --oneline -5 2>/dev/null
+status="$(git -C "$root" status --short 2>/dev/null | head -20)"
+if [ -n "$status" ]; then
+	echo
+	echo "Uncommitted changes (possibly unfinished work from the last session):"
+	echo "$status"
+fi
+exit 0

.claude/hooks/game-stop-check.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Stop hook: on the game and kai branches, blocks the session from ending once when
+# there are code commits newer than the last commit that touched that branch's HANDOFF.md.
+set -u
+
+input="$(cat)"
+# Already continuing because of this hook: let the session stop, never loop.
+if printf '%s' "$input" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
+	exit 0
+fi
+
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+
+branch="$(git -C "$root" rev-parse --abbrev-ref HEAD 2>/dev/null || echo)"
+case "$branch" in
+	game | game/*) rel="apps/datagutt/docs" ;;
+	kai | kai/*) rel="docs/kai" ;;
+	*) exit 0 ;;
+esac
+[ -f "$root/$rel/HANDOFF.md" ] || exit 0
+
+last_code="$(git -C "$root" log -1 --format=%ct -- . ":(exclude)$rel" 2>/dev/null)"
+last_handoff="$(git -C "$root" log -1 --format=%ct -- "$rel/HANDOFF.md" 2>/dev/null)"
+[ -n "$last_code" ] || exit 0
+[ -n "$last_handoff" ] || last_handoff=0
+
+if [ "$last_code" -gt "$last_handoff" ]; then
+	cat <<JSON
+{"decision":"block","reason":"There are commits on $branch newer than the last $rel/HANDOFF.md update. Before stopping: rewrite $rel/HANDOFF.md (current state, next step, blockers, gotchas), make sure finished tasks are ticked in $rel/PLAN.md, and commit both. If this turn only answered a question and the handoff is already accurate, say so and stop."}
+JSON
+fi
+exit 0

.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/game-session-start.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/game-stop-check.sh\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [master, game, kai]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: package.json
+      # Next, Playwright and the asset scripts run on Node.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: bun install --frozen-lockfile
+      - run: bun run turbo run lint typecheck test world:check
+      - run: bunx playwright install --with-deps chromium
+        working-directory: apps/datagutt
+      # No access to the private art repo here: this builds and plays the game with
+      # placeholder art, which is exactly what a fresh clone gets.
+      - run: bun run turbo run test:e2e
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: apps/*/test-results/
+          retention-days: 7

.gitignore

@@ -1,36 +1,33 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
 # dependencies
-/node_modules
-/.pnp
+node_modules/
+.pnp
 .pnp.js
 
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
+# build and tool output
+.next/
+.turbo/
+coverage/
+*.tsbuildinfo
+next-env.d.ts
+# kai content output (`kai content`), written into each app
+.kai/
 
 # misc
 .DS_Store
 *.pem
-
-# debug
 npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
 
 # local env files
+.env
 .env*.local
 
 # vercel
 .vercel
 
-# typescript
-*.tsbuildinfo
-next-env.d.ts
-.claude/
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+
+# test output
+test-results/
+playwright-report/

.prettierignore

@@ -0,0 +1,3 @@
+apps/datagutt/world/maps/
+apps/datagutt/world/tile-ids.json
+apps/datagutt/world/tile-colors.json

CLAUDE.md

@@ -2,97 +2,54 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-## Project Overview
+## What this is
 
-Personal portfolio site for datagutt, built with **Next.js 16** (canary), **React 19**, and **TypeScript**. Uses **pnpm** as package manager.
+A Bun workspace driven by Turborepo. It holds **kai**, an engine for top-down pixel-art walking games (Phaser 4, Ink dialogue, generated maps, LimeZu art), and the games built on it:
 
-## Commands
-
-```bash
-pnpm dev          # Start dev server
-pnpm build        # Production build
-pnpm start        # Start production server
-pnpm lint         # ESLint (Next.js config)
-pnpm format       # Format with Prettier (includes Tailwind class sorting)
-pnpm format:check # Check formatting
-```
-
-## Architecture
-
-### Page Structure
-
-Single-page portfolio (`app/page.tsx`) — a server component that fetches GitHub data, then renders sections with `Suspense` boundaries. Below-fold components using GSAP/ScrollTrigger are dynamically imported to reduce initial bundle.
-
-### Canvas System
-
-Five interactive canvas backgrounds rendered in the hero section via `components/canvas/CanvasSwitcher.tsx`:
-
-- **PixelCanvas** — Conway's Game of Life with data pulses, mouse-seeded life, avatar hover burst effect
-- **TerrainCanvas** — Simplex noise terrain with mouse-driven elevation, continuous drift via GSAP
-- **FallingBlocksCanvas** — Tetris-style falling blocks
-- **DungeonCanvas** — Procedural dungeon generation
-- **StarfieldCanvas** — Parallax starfield
-
-All canvases use `app/utils/canvas.ts` for DPI-aware setup and `hooks/useResizeKey.ts` for responsive resizing.
-
-### Data Fetching (lib/github.ts)
-
-Three server-side functions, all cached for 1 hour via `unstable_cache` + React `cache()`:
-
-- `getPinnedRepos()` — Scrapes GitHub profile HTML for pinned repos
-- `getGitHubStats()` — GitHub REST API for user stats + total stars
-- `getContributions()` — External API for contribution calendar data
+- `apps/datagutt`: datagutt.no, the portfolio site as a game, "Fjord Town", with a plain-text twin, the Journal. Next.js 16.3. See `apps/datagutt/CLAUDE.md`.
+- `apps/sandbox`: the smallest kai game. It proves the engine needs nothing from Fjord Town and is the template for new games.
+- `packages/kai*`: the engine, as TypeScript source with no build step.
+- `tooling/`: shared TypeScript, ESLint and Vitest presets.
 
-GitHub username is hardcoded as `datagutt`.
+## Docs and session workflow
 
-### Animation
+- Engine: `docs/kai/`. Start with `ARCHITECTURE.md`; then `PLUGINS.md`, `CONTENT.md` and `NEW-GAME.md` as needed. Decisions in `docs/kai/DESIGN.md` are settled.
+- Fjord Town: `apps/datagutt/docs/` (`DESIGN.md`, `PLAN.md`, `ART.md`, `README.md` for the workflow).
+- Each package has a README saying what it is and what it must not import.
+- The SessionStart hook prints the handoff for the branch: `docs/kai/` on `kai` branches, `apps/datagutt/docs/` otherwise. The Stop hook asks for a HANDOFF.md update when there are newer code commits.
 
-GSAP with ScrollTrigger for scroll-based section entrances. All animation code respects `prefers-reduced-motion`. Canvas animations run at 60fps via requestAnimationFrame.
-
-### Styling
-
-Tailwind CSS with dark mode (class strategy). Custom green color palette (`primary-50` through `primary-950`). Custom pixel font families defined in `tailwind.config.ts`. Global styles in `app/globals.css` include glitch effects, pixel dividers, and custom scrollbar.
-
-### Data Files
-
-Static data lives in `data/` — `projects.ts`, `experience.ts`, `skills.ts`. Each exports typed arrays used by their respective components.
-
-### Lanyard live status (components/LanyardCard.tsx)
-
-Live Discord/Spotify presence card in the hero, right side. Uses `react-use-lanyard` (client WebSocket to `wss://api.lanyard.rest/socket`).
-
-- Discord ID resolves from `NEXT_PUBLIC_DISCORD_ID` (override) or the hardcoded `DEFAULT_DISCORD_ID` constant in `lib/lanyard.ts`. The card works out of the box, no env var required.
-- Requires the Discord user to be a member of the Lanyard guild (`discord.gg/lanyard`). If not joined, the card silently renders nothing.
-- Card is absolutely positioned to avoid layout shift on data arrival, fades in with GSAP. Hidden on mobile (`<md`) since the absolute slot would clip the content column.
-
-### Reactions overlay (components/reactions/, lib/reactions/, app/api/reactions/)
-
-Canvas-agnostic ephemeral multiplayer reaction layer. Visitors drop a chunky pixel ripple on click; click-and-hold (220ms) opens a radial palette of 8-bit pixel sprites (heart, star, fire, skull, sparkle).
+## Commands
 
-- Transport: a single bidirectional WebSocket at `/api/reactions/ws` (Node runtime, Fluid Compute, `maxDuration: 300`, 30s server ping). The client sends its reaction over the same socket it receives others on. Built on `experimental_upgradeWebSocket` from `@vercel/functions` (needs the `ws` package). Because `cacheComponents` is enabled, the route handler calls `connection()` before upgrading so it opts out of static prerendering. Local dev needs `vc dev` (Vercel CLI), since `next dev` does not run the WebSocket upgrade.
-- Coordinates normalize to the nearest top-level `<section id>` (hero/portfolio/about/techstack/experience/opensource/stats/contact). Receivers re-project per RAF against their own section rect, so scroll/resize tracks naturally.
-- The server skips echoing an event back to the connection that sent it (the sender already renders its own drop optimistically), so there is no client side sid filtering. Clients reconnect with exponential backoff on close, and buffer a small outbox of unsent reactions while the socket is down.
-- Single-instance fan-out only. A WebSocket connection is pinned to one Fluid instance, and one instance can host many connections, but two clients pinned to different instances under load will not see each other. Acceptable for ephemeral vibes; upgrade path is Upstash Redis pub/sub if needed.
-- Rate limit: in-process token bucket per WebSocket connection (5 tokens, 1/sec refill). The bucket lives and dies with the connection, so no shared map or GC is needed.
-- Click capture is window-level (`pointerdown` capture phase). Canvas mousemove and other handlers are not affected. Interactive targets and any element with `[data-no-reactions]` are skipped.
+```bash
+# From the repository root (Turborepo runs the task in every workspace)
+bun install              # Install dependencies (Bun 1.4; the lockfile is version 2)
+bun run dev              # Content and assets, then every app's dev server
+bun run build            # Content and assets, then the production builds
+bun run lint             # ESLint, including the import boundaries
+bun run typecheck        # tsc --noEmit
+bun run test             # Vitest unit tests
+bun run world:check      # Fail if generated maps are stale or invalid
+bun run test:e2e         # Build, then every app's Playwright tests
+bun run format           # Prettier
+bunx turbo run <task> --filter=<app or package>   # One workspace only
+```
 
-#### Kill switch
+The `kai` command (from `@datagutt/kai-assets`) runs inside an app folder: `kai content`, `kai assets`, `kai world gen|check|render`, `kai characters`, `kai art <tool>`, `kai dev`. Each app wraps them as `bun run` scripts. See `docs/kai/ARCHITECTURE.md`.
 
-Visitors can disable the overlay locally:
+## Rules the code relies on
 
-```js
-localStorage.setItem("rx_off", "1"); // disables sending and receiving
-localStorage.removeItem("rx_off");   // re-enable
-```
+- **Import boundaries** (`tooling/eslint-config/boundaries.js`): packages never import an app; runtime packages (`kai`, `kai-net`, `kai-live`, `kai-arcade`, `kai-next`) never import build time packages (`kai-worldgen`, `kai-limezu`, `kai-assets`) and import schemas only with `import type`; the runtime never imports Next or React; `kai-worldgen` and `kai-assets` never import the art adapter `kai-limezu`.
+- **No game content in `packages/`.** Content is JSON and Markdown in `apps/<app>/content/`, checked by Zod schemas; behaviour one game needs is a plugin in that app.
+- **Licensed pixels never enter this repository**, including packed atlases and renders. The art is in the private `datagutt/datagutt-assets`, used from a sibling checkout (`../datagutt-assets`) or cloned with a token. Without it builds use placeholder art.
+- **Imports inside packages carry their `.ts` extension**, and JSON imports that Node reaches need `with { type: "json" }`: Node and Bun load the source directly.
+- Code that the build loads (dialogue hosts, map builders) must not import `@datagutt/kai`'s index, which pulls in Phaser. Import by path, such as `@datagutt/kai/data`.
+- Dependencies change through `bun add`/`bun remove` in the workspace, never by editing `package.json`.
 
-#### Environment
+## Turborepo
 
-- `NEXT_PUBLIC_DISCORD_ID` (optional). Discord snowflake for Lanyard. Defaults to the constant in `lib/lanyard.ts`.
+`content`, `assets`, `build`, `dev`, `game:dev` and `test:e2e` are never cached: the asset build reads art from outside the repository, and the content bundle depends on schemas in other packages. `typecheck`, `test` and `world:check` run `content` first.
 
-## Key Configuration
+## CI and hosting
 
-- **React Compiler** enabled (`babel-plugin-react-compiler`)
-- **View Transitions** enabled experimentally
-- **Inline CSS** enabled via Next.js experimental config
-- **Path alias**: `@/*` maps to project root
-- **TypeScript strict mode** enabled
+- `.github/workflows/ci.yml`: `bun install --frozen-lockfile`, then lint, typecheck, unit tests and `world:check`, then every app's e2e tests.
+- Vercel builds `apps/datagutt` (the project's Root Directory). `apps/datagutt/vercel.ts` installs with `npx [email protected]`, because the build image's Bun 1.3 cannot read the lockfile.