web-starter-kit

Define and execute visual acceptance before, during, and after any task that can change rendered UI, game scenes, 3D assets, animation, responsive layout, or browser behavior. Use before editing a visual surface, for redesigns that must be proven in an isolated lab before integration, after visual feedback, and before claiming a visual result complete.

Slice transparent UI atlases into production PNGs through alpha connected-components, geometric clustering, and an explicit semantic review. Use when an atlas has a keyed/transparent background, when manual crop coordinates are unreliable, when UI parts must be identified before slicing, or when an agent needs to inventory every atlas element before building UI.

How build-time asset optimization works in this project and how to extend it. Every asset (image, audio, 3D model) is shrunk at build time by a dedicated Vite plugin in `vite/`, and every asset reachable from the entry graph is auto-collected into `virtual:bootstrap-assets` and preloaded by the bootstrap gate — no hand-written manifest. Enforces the shared plugin shape (resolveId tag → load repack → emit/serve, per-import `?…` query opt-out/tuning, closeBundle savings report) and the registry wiring (ASSET_EXTENSIONS + kind). MANDATORY before: adding/importing a `.glb`/`.gltf`/image/audio asset, adding a new asset TYPE, changing texture/audio/image compression, touching the preloader weighting, or writing a new `vite/*OptimizerPlugin.ts`. Trigger on: "optimize assets", "compress texture/model/audio", "GLB import", "glTF", "gltf-transform", "reduce bundle/asset size", "preloader", "loading bar", "virtual:bootstrap-assets", "why is my asset not preloaded", "add asset type", "assetsInclude", "asset pipeline", "?

Keep all gameplay logic independent from render FPS. Use for any work on player input, movement, combat, abilities, cooldowns, enemy AI, projectiles, damage, loot, encounter state, animation timing, cameras, `useFrame`, frame-rate caps, fixed ticks, simulation clocks, replay, interpolation, or multiplayer snapshots in this project. Applies to system designers and programmers.

Where every file goes in this project's src/ and how to work in it. The codebase is Feature-Sliced Design (FSD) layers + a Unity-style ECS. ECS mapping: an ENTITY is a React component that IS a game being (features/slice/entities/*.tsx); a COMPONENT is a React hook you attach to any entity (features/slice/components/use*.ts); a SYSTEM is pure framework-free logic (features/slice/systems/*.ts). MANDATORY before adding, moving, or renaming any file under src/ — new entity, hook, system, screen, scene, feature, shared util, asset, or route. Enforces: correct layer placement, relative imports (no path aliases), deep cross-slice imports (barrels only for a feature's public screen), the app/scenes/features/shared layering, and DEV-only debug routes for lab/dead code. Trigger on: "where do I put", "add a feature", "add an entity / component / system", "new screen", "new scene", "new route", "folder structure", "FSD", "ECS", "how is src organized", "import from another feature", "where does this hook go".

How to correctly make UI scale on mobile in this project. The app scales every UI screen with the external ScalableContainer (@vibegameengine/ui-scaler): content is authored in a fixed logical `targetWidth` and shrunk by `transform: scale(min(1, innerWidth/targetWidth))`. On a phone a desktop-width target collapses the UI to ~30% (tiny, unreadable). The ONE correct fix is a DYNAMIC targetWidth per device via the shared `useResponsiveTargetWidth` hook — never remove the scaler, never patch it with per-element `transform: scale(N)` compensation, never invent a new scaling system. MANDATORY whenever a screen is "too small / doesn't scale / broken on mobile", when touching `targetWidth`, ScalableContainer, a HUD/menu/overlay on mobile, or any responsive UI work. Trigger on: "mobile UI", "doesn't scale on phone", "too small on mobile", "targetWidth", "ScalableContainer", "adaptive UI", "responsive", "portrait", "HUD too big/small on mobile", "меню не скейлится", "плашка на мобилке".

Reconstruct Blender models from supplied reference sheets, branding templates, texture atlases, orthographic front/side/back/top views, or mascot/logo art where visual fidelity to the source is more important than a plausible generated object. Use when the user says the model must match a template, wireframe, texture pack, character sheet, mascot sheet, or brand asset exactly; also use after feedback like "does not look like the reference", "fit the texture 1:1", "wrong number of visible parts", or "compare against the template". Requires Blender MCP plus local Python with Pillow/OpenCV/numpy; pairs with blender-uv-texturing, wireframe-to-3d, blender-modeling, blender-materials, and blender-export.

Use SpriteForge to import, key, clean, outline, slice, or export 2D game sprites and UI atlases. Trigger when a user mentions SpriteForge, `__AGENT_API__`, chroma key/keying, pink/green background removal, sprite cleanup, outline nodes, or wants a processed SpriteForge result saved next to its source asset.

Keep Three.js / react-three-fiber draw calls low in this project. Use whenever adding repeated 3D objects (props, tiles, foliage, blocks, enemies, particles, greybox/blockout geometry) or creating materials. Enforces two rules: (1) batch repeated meshes with InstancedMesh (drei <Instances>/<Instance>), never one <mesh> per object; (2) define every material and geometry ONCE in the shared registry and reuse it — tint per-instance with instance color — never `new THREE.Material()` / `new THREE.Geometry()` inline. Shared assets register with `@vibegameengine/shader-warmup`'s central warmup service. Trigger on: "too many draw calls", "scene is slow", "add N of these", "spawn", "props", "instancing", "material", "shader warmup", "shader stutter", "warmup splash", "ShaderWarmupRegistry", high draw-call count in r3f-perf.

Prepare a Tripo character for direct, untouched Mixamo FBX animations. Use when a Tripo GLB is sent through Blender/Mixamo, a With-Skin FBX must become the one runtime GLB model, an animation-only Mixamo FBX must play without retargeting, or skin normals/materials break after FBX conversion.

Build and evolve the isolated UI-kit feature for this React game. Use when creating or changing reusable UI primitives, menus, HUD controls, dialogs, Patch9 wrappers, UI asset placement, UI-kit exports, or when deciding whether a screen should compose UI-kit rather than own another UI feature.

Localize this React game into Russian and English with feature-owned, type-safe dictionaries. Use whenever adding or translating UI copy, locale detection, a language selector, a `t(key)` call, `ru/en` files, or localized bootstrap/menu/HUD content. Enforces the project's FSD boundaries, matching dictionary keys, browser-locale fallback, and focused localization tests.

Build, slice, and repair responsive game UI in this project with the shared Patch9Button/Patch9Surface renderer. Use whenever creating or changing a HUD, main menu, modal, panel, framed button, UI atlas crop, or a UI overlay that must stay clickable inside ScalableContainer. Covers FSD placement, asset slicing, Patch9 inset configuration, interaction rules, and headed validation.

Frame-cost architecture for Three.js / react-three-fiber scenes in this project: how the scene is rendered multiple times per frame (main + shadow + velocity passes), and the static/dynamic split that stops invariant work being recomputed every frame. Use when reasoning about fps/perf beyond draw calls, shadows, GI / indirect / bounce light, reflections, "why is the scene rendered several times", "why so many triangles", per-frame cost, or when adding moving objects (players, monsters, projectiles) to a mostly-static world. Enforces: tag world geometry static vs dynamic (shadowLayers.ts / <ShadowGroup>), never recompute a pass whose inputs did not change (throttle/cache shadows, bake static GI), compute only the cheap dynamic delta per frame, composite. Trigger on: "shadows every frame", "bake", "static/dynamic", "GI", "reflected light", "reflections", low fps that instancing did not fix. Pairs with threejs-instancing-materials (draw-call budget).

How to BUILD / lay out Three.js / react-three-fiber scenes in this project. MANDATORY whenever placing, composing, arranging, or "dressing" scene geometry — buildings, props, trees/cones, ruins, terrain features, colored figures, level layout, greybox/blockout. Enforces the project's absolute rule (AGENTS.md #3): scenes are ALWAYS authored by hand — no RNG scatter, no seeded generators, no `range()`/random placement, no "spawn N from a loop to fill space". Every element is placed deliberately to serve a composition/reference, and EVERY step is confirmed with a headed (visible-window) screenshot before moving on. Trigger on: "build the scene", "lay out", "place", "arrange", "compose", "match the reference", "dress the set", "add buildings/trees/props", "the scene looks…", scene/level construction of any kind. Pairs with threejs-instancing-materials (draw calls) and threejs-scene-architecture (frame cost / static-dynamic).

Drive Blender from natural language. Converts plain-English requests ("model a sword and render it with cinematic lighting", "make this glass look frosted", "set up three-point lighting", "export this scene as glTF for the web") into Blender Python code executed via the Blender MCP server. Acts as the orchestrator that picks and chain-loads specialised sub-skills (blender-modeling, blender-materials, blender-lighting, blender-cameras, blender-rendering, blender-animation, blender-export, wireframe-to-3d, blender-pro-workflow, blender-skill-harmonizer, quality-refinement-autoloop). Use this skill whenever the user wants Claude to do anything in Blender, including creating geometry, applying materials, lighting a scene, framing a camera, rendering, animating, or exporting. Make sure to invoke this skill even if the user does not say "Blender" — also covers requests like "create a 3D model of...", "render this...", "make a glTF from...", "set up a scene with...", or any 3D-creation task. Requires the Blender MCP