elbaph

Imported from MJPL013/elbaph (AGENTS.md). Install upstream with npx skills add MJPL013/elbaph. Copyright stays with the author.

AGENTS.md

This file is the operational guide for coding agents working on Elbaph. Treat the repository code as the final authority. If this document and the code disagree, inspect the relevant implementation and update this document in the same change.

Project Definition

Elbaph is a static, browser-based 3D portfolio for Manoj Pal. Visitors navigate a small spherical world, discover portfolio landmarks, and click them to open structured information panels.

Current product constraints:

• The experience is an explorable world, not a conventional resume page.
• The avatar stays at a fixed world position while the planet rotates beneath it.
• The world uses stylized low-poly geometry, shared toon materials, and ink outlines.
• Professional content is shown through landmarks and interaction panels. The resume PDF is not exposed in the public UI.
• Personal interests are intentionally placeholder content until the owner provides facts. Do not invent them.
• There is no backend, API server, database, router, or physics engine in this repository.

Current Implementation Status

• Four world quarters exist: Experience, AI Projects, Creative, and Contact.
• Thirteen portfolio landmarks and additional filler buildings are placed on the planet.
• All landmarks are true 3D procedural React Three Fiber components.
• Kazam Energy has a dedicated hero-building blockout with shared material slots, instanced chargers, instanced bollards, road markings, and atlas metadata.
• The texture manifest and prompt catalog exist, but runtime texture loading and generated texture files do not. Materials currently use solid toon colors.
• The Goku/Nimbus GLB is bundled locally. A lightweight placeholder renders while its lazy-loaded component and model load.
• The former personal placeholder is a visible Side Quest portal marked WORK IN PROGRESS; it has no destination route yet.
• Avatar readiness is confirmed only after a real GLB mesh renders, not merely after the file loader resolves.
• The sky dome uses a lightweight procedural shader for animated fine grain and horizon fuzz, reduced on low quality.
• Landmark interactions use district-colored Discovery Log panels with one Brief section expanded by default; Close and outside clicks dismiss the panel.
• Background music uses Music/Morning_on_the_Map.mp3 through one native audio element at 16% volume, starts after user interaction, loops, and persists mute state.
• Keyboard movement, pointer/touch drag movement, collision blocking, interaction camera framing, quality tiers, and WebGL fallback are implemented.
• Render deployment is configured as a static site in render.yaml.

Do not describe Kazam as a final textured production asset. It is the approved geometry/material-slot blockout awaiting a separate texture-generation and final-art phase.

Runtime Flow

1. src/main.tsx mounts src/App.tsx and global CSS.
2. App.tsx detects WebGL, selects a quality tier, preloads the avatar, creates the R3F Canvas, and mounts DOM overlays.
3. src/components/WorldScene.tsx owns lighting, shared materials, the planet, avatar, camera, diagnostics, and post-processing.
4. src/components/TreadmillPlanet.tsx reads keyboard/pointer input, converts it to a camera-relative direction, checks raycast collisions, and rotates the complete planet group.
5. src/components/Landmarks.tsx renders portfolio landmarks and filler buildings from src/world/landmarkData.ts.
6. src/components/LandmarkBox.tsx converts spherical coordinates to a position/quaternion, creates interaction and collision targets, and opens the selected content.
7. src/components/scenery/HeroLandmark.tsx maps each buildingArchetype to its 3D building and adds a camera-facing label.
8. src/components/InteractionOverlay.tsx resolves the selected ID through src/content/portfolioContent.ts and renders the panel.
9. src/components/WorldHud.tsx renders quarter information and the BackgroundMusicControl DOM audio UI.

Source Of Truth

Architectural Invariants

Do not break these without explicit owner approval and corresponding test changes:

• Keep the avatar fixed at CHARACTER_FIXED_POSITION; movement rotates the planet quaternion.
• Use viewport-relative movement from src/game/facing.ts for keyboard and pointer controls.
• Freeze traversal while useGameStore().isInteracting is true.
• Keep collision lightweight: registered box colliders plus predictive raycasting.
• Keep portfolio facts separate from placement and geometry.
• Keep landmark IDs identical between PORTFOLIO_CONTENT and LANDMARKS.
• Keep building bodies attached to the spherical surface via surfaceQuaternion.
• Use WorldBillboardLabel for readable names; do not bake live text into a building facade.
• Use useElbaphMaterial() and shared material IDs in scenery. Do not add per-mesh meshStandardMaterial to the building kit.
• High/medium quality use post-processing outlines. Low quality omits post-processing and may use local outline shells only on silhouette-critical geometry.
• Keep debug colliders hidden by default. ?debug=1 and the H key must continue to toggle them.
• Keep the avatar placeholder visible until the GLB is ready.
• Do not expose or open the resume PDF from the app.
• Keep source files below 200 lines where practical; split by responsibility instead of compressing complex code into unreadable one-line structures.

Common Change Procedures

Edit existing portfolio facts

1. Edit the matching file under src/content/.
2. Do not change placement or geometry unless the request also asks for a world change.
3. Run npm run verify:content and npm run build.

Move or resize a landmark

1. Edit only its entry in src/world/landmarkData.ts first.
2. Keep footprint aligned with the visible building and collider needs.
3. Adjust labelOffset if the billboard overlaps geometry.
4. Run layout, collision, render, and visual verification.

Add a portfolio landmark

1. Add confirmed content under the correct src/content/portfolio*.ts file.
2. Add or reuse a BuildingArchetype and building component.
3. Add the archetype mapping in HeroLandmark.tsx.
4. Add placement/configuration in LANDMARKS using the exact same ID.
5. Add or update verification expectations. Do not weaken counts merely to make tests pass.

Change a building or material

1. Propose the visual concept, explain why it fits Elbaph, and state triangle/draw-call/texture implications before implementing a new visual direction.
2. Reuse BuildingKit.tsx and existing material IDs where they fit.
3. Add silhouette geometry only where it communicates function; reserve surface detail for future textures/decals.
4. Check desktop, mobile, and ?quality=low output.

Add runtime textures

This is not implemented yet. A complete change must include loading/fallback behavior, color-space handling, atlas use, low-quality variants, disposal, asset budgets, and verification. Do not merely add files matching manifest paths and claim textures are integrated.

Commands

Requirements: Node.js 20+, npm 10+, and Chrome or Edge for browser verification.

npm install
npm run dev
npm run build
npm run preview

Verification scripts:

npm run verify:content
npm run verify:architecture
npm run verify:avatar
npm run verify:audio
npm run verify:layout
npm run verify:render
npm run verify:visual
npm run verify:movement
npm run verify:relative-movement
npm run verify:focus-input
npm run verify:collision
npm run verify:camera
npm run verify:state
npm run report:size

report:size requires a current dist/, so run the build first. Browser checks start their own Vite server and locate local Chrome/Edge. Set PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH or CHROME_PATH if auto-detection fails. Screenshots and test artifacts go under ignored .agents/artifacts/.

Choose verification by blast radius, but run the full suite for movement, camera, collision, shared material, landmark-system, or renderer changes.

Quality And Performance Contracts

• Kazam budget: at most 7,000 triangles and 16 draw calls. Runtime checks inspect its userData metadata.
• Shared scenery materials must not be duplicated; diagnostics compare material UUIDs.
• Future raster assets over 200 KB are flagged by npm run report:size.
• The active MP3 is 3.40 MiB and must remain a separate streamed asset; report:size warns when an MP3 exceeds 5 MiB.
• Current texture limits are declared in TEXTURE_RUNTIME_LIMITS: 2048 category atlas, 1024 Kazam albedo atlas, 512 Kazam decal atlas, and 16-pixel gutters.
• Quality can be forced with ?quality=high, ?quality=medium, or ?quality=low.
• The material registry currently contains 17 shared IDs, including the portal-energy material.

Git And Generated Files

• Inspect git status before editing. Preserve unrelated user changes.
• Do not commit node_modules/, dist/, .agents/, .codex/, logs, screenshots, or local environment files.
• The tracked avatar model at 3d_models/son_goku_and_kintoun_nimbus.glb is intentional.
• agent_instructions.txt is ignored legacy local context and contains stale claims. Do not use it as project truth; use this file and the implementation.
• Keep commits scoped and describe the actual behavior changed.

Anti-Hallucination Rules

• Do not claim a feature, asset, metric, integration, or deployment exists without locating it in code or verifying it at runtime.
• Distinguish current implementation from roadmap work in every handoff.
• Do not invent personal facts, project links, employment details, or performance numbers.
• Do not infer that a manifest entry means its referenced file exists or is loaded.
• Music licensing and attribution are not recorded in this repository; do not claim redistribution rights without owner-provided evidence.
• When uncertain, name the unknown and inspect the relevant file or ask the owner. Do not fill gaps with plausible text.