Petshare Setup

Petshare Setup

Use this skill when an agent is asked to spin up, fork, rebrand, deploy, or modify this repository or a close derivative. The app is a self-hostable React/Vite pixel-pet sharing surface: users upload Codex-compatible pet packages, browse animated previews, download packages/GIFs, and join multiplayer playground rooms.

This is a repo-scoped Codex skill. Keep it under .agents/skills/petshare-setup/ so Codex can discover it from the repository.

First Read

Before editing, read:

• README.md
• docs/GETTING_STARTED.md
• docs/PROVIDER_ADAPTERS.md
• AGENTS.md
• references/petshare-architecture.md when touching app behavior, uploads, previews, animations, rooms, provider adapters, or deployment
• references/security-boundary.md when publishing, documenting public setup, reviewing exposure risk, or changing auth/moderation/provider surfaces

Non-Negotiables

• Keep changes literal to the request. Do not add fallbacks, backwards compatibility, provider-specific public env vars, or unrelated hardening.
• Keep the browser public contract provider-neutral. Public build vars are only: VITE_APP_API_BASE_URL, VITE_PUBLIC_APP_ORIGIN, VITE_REALTIME_URL, VITE_REALTIME_PUBLIC_KEY, VITE_APP_NAME, VITE_APP_HANDLE, VITE_APP_TAGLINE, and VITE_APP_REPO_URL.
• Never commit .env, .env.local, API tokens, salts, database passwords, provider account identifiers, generated migration exports, or local auth data.
• Use provider adapters as replaceable boundaries. Feature code under src/ should not branch on provider names.
• Do not turn this skill into an abuse manual. Do not add copy-paste scripts, unauthenticated client examples, raw room-event payload recipes, rate-limit thresholds, bypass instructions, scraping loops, or moderation-evasion advice.
• For ports, follow AGENTS.md: check a requested port before starting a process, and never kill reserved ports unless explicitly asked.

Core Workflow

1. Identify whether the task is setup, provider work, upload/asset work, preview/GIF work, animation/playground work, multiplayer rooms, rebranding, or security/publication review.
2. Load only the reference file needed for that surface.
3. Inspect current source before deciding; this repo has explicit adapter and feature boundaries.
4. Make the smallest code/doc changes that satisfy the user request.
5. Run the relevant validation commands below.
6. If publishing or handing off public code, run the exposure checks from references/security-boundary.md.

Repository Map

• src/domain/*: shared types, route parsing, API URLs, session storage, gallery constants, pet kind/tag config, and sprite atlas constants.
• src/app/*: SPA composition, route effects, API/session hooks, shell chrome, modal composition, and cross-feature refresh/navigation.
• src/uploads/*: file inputs, manifest parsing, slug normalization, upload validation preview, generated share.png, generated preview.webp, generated poster.webp, and POST /api/pets form assembly.
• src/pets/*: gallery/detail pet surfaces, sprite previews, cursor preview, metadata editing, tag/kind management, delete, share, and GIF export wiring.
• src/downloads/*: package modal, install command UI, spritesheet fetch, GIF encoding, and client-side blob download.
• src/gallery/*: browse/search/filter/sort/pagination, creator pages, collections, live room rail, and leaderboard.
• src/playground/*: Three.js playground, sprite animation, room overlays, realtime handlers, UI controls, minimap, chat, NPCs, ball, and trampoline.
• src/realtime/providerClient.ts and src/realtime/roomChannel.ts: generic frontend realtime exports.
• src/realtime/adapters/*: current provider-specific realtime implementation.
• adapters/cloudflare-worker/*: checked-in API, D1 schema, R2 storage, Durable Object realtime, Worker Assets hosting, and Cloudflare deployment.
• adapters/cloudflare-pages/*: optional crawler/social-share page functions for static hosts.
• scripts/*: public env validation and generated brand/social-card assets.

If a feature file starts absorbing unrelated behavior, extract into the matching feature folder rather than adding another section to a large component.

Setup Path

npm install
cp .env.example .env.local
node scripts/check-public-build-env.mjs
npm run build
npm run dev

Vite defaults to http://127.0.0.1:5173.

The build validator fails if required public env vars are missing, malformed, or if a VITE_* name looks secret-like. For provider/env changes, verify .env.example, scripts/check-public-build-env.mjs, docs, and adapter config agree exactly.