www is the Astro / MDX / raw TypeScript site for Incomplete Infinity / U29DC.

• Primary references: Astro, Astro MDX, Astro content collections, Vite, MDX, Tailwind CSS, Cloudflare Workers, WebGL, WebGPU
• Local source-of-truth files: package.json, astro.config.ts, wrangler.jsonc, public/_headers, src/layouts/layout.astro, src/app/app.ts, src/app/core/loop.ts, src/content.config.ts
• Edit AGENTS.md only; README.md and CLAUDE.md are symlinks to it for tool compatibility.

.
├── src/
│   ├── pages/              Astro routes, article exports, sitemap, robots, llms.txt
│   ├── layouts/            global document shell and metadata
│   ├── components/         chrome, home, artifacts, MDX, logo, and core UI components
│   ├── content/            authored MDX artifacts
│   ├── data/               site copy, links, mark metadata, and constants
│   ├── assets/             flat imported source assets such as tiny inlined mark WebPs
│   ├── app/                browser runtime: core loop, systems, UI owners, graphics, and runtime utilities
│   ├── lib/                portable content, media URL, markdown, and build/export utilities
│   └── styles/             tokens, base, layout, prose, preview, and motion CSS
├── public/                 static headers, icons, local fonts, logo, and OG image
├── astro.config.ts         Astro, MDX, Tailwind, GLSL string minification, and Cloudflare adapter config
├── wrangler.jsonc          Cloudflare Worker and asset deployment config
└── AGENTS.md               canonical repo-level agent instructions

• Start with src/layouts/layout.astro for shell, metadata, header persistence, grid guide, route router, and the single browser app import.
• Start with src/app/app.ts, src/app/core/owner.ts, and src/app/core/loop.ts for browser runtime ownership, owner order, and frame-loop behavior.
• Start with src/pages/index.astro for homepage composition and src/pages/[slug].astro for artifact pages.
• Start with src/content.config.ts, src/lib/artifacts.ts, and src/lib/markdown.ts for content collection, visibility, sorting, and markdown export behavior.

• bun install - install dependencies and refresh the lockfile.
• bun run dev - start Astro locally on localhost:3000.
• bun run build - build the Astro site.
• bun run preview - preview the production build.
• bun run deploy - run bun run util:check, then deploy with Wrangler.
• bun run update - update normal packages, then re-pin Astro, MDX, and the Cloudflare adapter to alpha.
• bun run util:format - apply and verify formatting with Oxfmt.
• bun run util:lint - lint and auto-fix with Oxlint.
• bun run util:check - format, lint-fix, type-check, and build.
• bun run util:clean - remove Astro/build caches.

• src/layouts/layout.astro owns global CSS, metadata, canonical/OG/Twitter tags, font preloads, the persistent header, grid guide, page shell, route router, and the single browser runtime import.
• src/pages/index.astro composes the homepage in this order: origin, protocols, artifact studies, artifact fragments, optional signals, connect.
• src/pages/[slug].astro renders artifact detail pages with article metadata, MDX content, hidden metadata, and connect footer.
• src/pages/[slug].md.ts, src/pages/[slug].txt.ts, src/pages/llms.txt.ts, src/pages/rss.xml.ts, and src/pages/feed.json.ts are first-class machine-readable surfaces. Keep them aligned with visible content when copy or MDX behavior changes.
• Runtime behavior uses data-* attributes as the contract between Astro markup, CSS, and src/app/*. Extend the existing hook contract for new runtime state.
• src/app/app.ts is the browser composition root. It starts systems first (device, route, scroll, motion) and UI owners second (lines, media, preview, logo).
• src/app/core/loop.ts is the only app-owned requestAnimationFrame scheduler. Runtime owners wake it when work exists and sleep when idle.
• src/app/core/owner.ts defines the lifecycle owner contract. Owner files should read in this order: imports, types/constants, class fields, lifecycle methods preinit, init, resize, read, update, write, post, dispose, then private helpers and exports.
• src/app/core/state.ts owns stable cross-owner state types so core does not import downstream systems or UI.
• src/app/core/tokens.ts centralizes TypeScript-side motion, preview, media, and line-reveal timing defaults. Keep it aligned with src/styles/tokens.css when CSS motion tokens change.
• src/app/systems/route.ts owns route state and the Astro transition bridge. Other owners subscribe to route state instead of importing astro:transitions/client.
• src/app/systems/scroll.ts owns custom smooth scroll. Keep the model explicit with actual, animated, target, velocity, direction, limit, and native fallback state.
• src/app/ui/lines.ts, src/app/ui/media.ts, src/app/ui/preview.ts, and src/app/ui/logo.ts own DOM enhancement behavior.
• src/app/graphics/canvas.ts owns logo canvas/WebGL rendering, diagnostics, and fallback safety. It must use the shared core loop, not a second RAF loop.

Runtime philosophy:

• Every frame must have an owner, reason, and place in the loop.
• Async work may load, decode, play, or fail, but it should report state instead of owning runtime control flow.
• Device capability is policy. Expensive owners should ask the device profile before starting high-cost work.
• CSS transitions are valid when the runtime owns the state change, the transition is transform/opacity-oriented, reduced motion is explicit, and interruption/failure leaves the page usable.
• Keep Astro as the static renderer and route event source, not the center of browser architecture.

• MDX frontmatter controls artifact type, date, visibility, thumbnails, hover previews, and export metadata. isArtifactItem: false hides an artifact from public listings and exports.
• src/lib/markdown.ts powers markdown/text exports and first-media extraction. Changes here affect article routes, llms.txt, and hover preview defaults.
• Rich origin copy in src/components/home/origin.astro and plain origin copy in src/data/copy.ts should stay semantically aligned.
• Local fonts live under public/fonts. Tiny link mark WebPs live flat under src/assets and are imported inline by src/data/marks.ts. Article media resolves through the configured media base URL, currently https://storage.u29dc.com/assets/.
• This repository is public. Keep private vault material, client-sensitive detail, secrets, and personal runtime data in private systems outside the repo.

• Keep content portable. Prefer MDX frontmatter and content collections over framework-specific data machinery.
• Keep creative effects portable. Put browser runtime, canvas, WebGL, WebGPU, scroll, preview, and motion logic in src/app modules that can survive a future framework migration.
• Keep Astro pages mostly static. Client JavaScript belongs to visible interaction, media, graphics, and progressive enhancement paths.
• The browser experience is an Astro-rendered document plus raw TypeScript owners under src/app; route, scroll, motion, preview, media, and graphics behavior should fit that ownership model.
• Prefer plain .astro, .mdx, .ts, and CSS files until a heavier abstraction is clearly useful.
• Prefer one-word filenames for runtime owners and helpers where they stay clear: scroll.ts, motion.ts, lines.ts, media.ts, logo.ts, route.ts, loop.ts, owner.ts, canvas.ts.
• Keep src/app import direction simple: app -> core/systems/ui, systems -> core/utils, ui -> core/systems/graphics/utils, graphics -> core/utils, and utils -> no app owners.
• Keep src/lib free of browser runtime ownership. It is for portable content/export utilities, not app lifecycle, frame scheduling, or visual controllers.
• Prefer inline Tailwind utilities for component-local styling. Keep shared CSS for tokens, document defaults, layout primitives, MDX prose, animation selectors, and runtime state selectors.
• Use Lucide icons for standard interface icons. Reserve custom drawing for logos, graphics, and bespoke visual effects.

• Treat src/styles/layout.css, layout-grid, layout-lane, and layout-lane-wide as high blast-radius. They align the header, homepage, article pages, connect footer, and grid guide.
• Treat src/app/core/loop.ts, src/app/core/owner.ts, and src/app/core/timer.ts as high blast-radius. They define frame order, lifecycle semantics, wake/sleep behavior, and timer handoff for the whole client runtime.
• Treat src/app/systems/scroll.ts as performance-sensitive interaction code. Preserve native fallback, reduced-motion behavior, keyboard/bar/route scroll compatibility, and minimal wheel-handler work.
• Treat src/app/ui/preview.ts, src/lib/hover.ts, and src/app/ui/lines.ts as performance-sensitive interaction code. Keep pointer work loop-batched and hot writes transform/opacity-oriented.
• Treat src/app/ui/logo.ts and src/app/graphics/canvas.ts as fragile visual code. Preserve reduced-motion, low-power fallback, canvas visibility, and nonblank rendering.
• Treat public/_headers, wrangler.jsonc, and astro.config.ts as deployment/security-sensitive. Run the full quality gate after config changes.
• Generated output such as dist/, .astro/, .wrangler/, node_modules/, and cache directories is regenerated from source.

• Required gate for code, config, content-export, and dependency changes: bun run util:check.
• For dependency or config changes, run bun install first when the lockfile may need to change.
• For visual work, run bun run dev and verify desktop and mobile browser views before reporting completion.
• For hover previews, page transitions, smooth scroll, and WebGL work, verify client-side navigation as well as first load.
• For WebGL/WebGPU work, verify reduced-motion, low-power fallback, canvas visibility, and nonblank rendering.
• If validation is intentionally limited, state exactly what was not run and the residual risk.