Feather 3D

Build a local-only 3D scene composer as a web app. This is a personal tool, not a product.

Stack, no substitutions: Vite + TypeScript + vanilla Three.js (latest). No React, no framework. No backend, no accounts, no telemetry, no network calls at all.

What it does:
1. Full-window WebGL canvas with an orbit/pan/zoom camera (OrbitControls) and a grid helper.
2. Drag and drop .glb or .gltf files onto the canvas to add them to the scene. Use GLTFLoader and fit the camera to the new object's bounding box on first load.
3. Click an object to select it. Show TransformControls with keyboard shortcuts: W translate, E rotate, R scale, X toggle world/local space, Delete removes the selection.
4. Left sidebar: scene outliner listing objects by name, click to select, double click to rename, visibility toggle per object.
5. Right sidebar: numeric inputs for position, rotation (degrees) and scale of the selection, kept in sync with the gizmo in both directions.
6. Lighting panel: one directional light with intensity, color and a draggable azimuth/elevation, plus ambient intensity. Drag and drop an .hdr file to set the environment via RGBELoader and PMREMGenerator, with an exposure slider.
7. Shadows: soft shadow map from the directional light, plus a toggleable ground plane that receives shadows only.
8. Undo/redo (Ctrl+Z / Ctrl+Shift+Z) for add, delete, transform and rename. Implement it as a plain command stack, do not try to diff the whole scene graph.
9. Save/load the scene as a JSON file: asset filenames plus transforms plus light settings. On load, re-prompt for any asset files it cannot find instead of failing silently.
10. Render button: renders the current view at a chosen resolution (up to 4x canvas size) and downloads a PNG. Also an Export glTF button using GLTFExporter.

Explicitly out of scope, do not build these: mesh editing or sculpting, UV tools, material/shader authoring beyond base color and roughness sliders, animation, physics, any AI generation, any multi-user or cloud sync.

Deliver: working dev server on npm run dev, a README with the shortcut list, and no .env because there are no secrets. Keep it to a handful of files with a clear scene-state module; do not invent an architecture.

# AGENTS.md — Build guide for Feather 3D

## Project scope
A local Three.js scene composer: drop in glTF assets, move and rotate them with a gizmo, tweak lights and environment, then export the scene or a PNG render.

Catalogue verdict: no. 3D authoring tools are the category where one-shot builds go to die. An agent will happily hand you a Three.js scene with a transform gizmo and an orbit camera in an afternoon, and it will feel great for about ten minutes. Then you want snapping, a real undo stack, material editing, HDRI lighting that does not blow out, UVs, glTF import that survives weird exporters, and a viewport that stays at 60fps with more than a dozen objects, and you are now writing a DCC app instead of using one. None of that is conceptually hard, all of it is thousands of small interaction decisions plus GPU tuning, and that is exactly what you are paying for here. Build the toy if you want a scene composer for one specific job, not if you want a 3D tool you enjoy opening.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- Node and a browser with WebGL2
- Your own glTF/GLB assets, nothing is generated for you
- An HDRI file for environment lighting

## Stack and architecture
- Stack, no substitutions: Vite + TypeScript + vanilla Three.js (latest). No React, no framework. No backend, no accounts, no telemetry, no network calls at all.
- Model source assets, editable projects, operations, and exported versions; keep stable source IDs and timestamps.
- Interface for this 3D scene design workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Save/load the scene as a JSON file: asset filenames plus transforms plus light settings. On load, re-prompt for any asset files it cannot find instead of failing silently.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: Actual modeling: you can arrange assets, you cannot make them.

## Agent implementation rules
- Project rule, data: Model source assets, editable projects, operations, and exported versions; keep stable source IDs and timestamps.
- Project rule, behavior: Left sidebar: scene outliner listing objects by name, click to select, double click to rename, visibility toggle per object.
- Project rule, recovery: Save/load the scene as a JSON file: asset filenames plus transforms plus light settings. On load, re-prompt for any asset files it cannot find instead of failing silently.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this 3D scene design operation with sample or user-owned data: Left sidebar: scene outliner listing objects by name, click to select, double click to rename, visibility toggle per object.
- Show a concrete result or export: Render button: renders the current view at a chosen resolution (up to 4x canvas size) and downloads a PNG. Also an Export glTF button using GLTFExporter.
- State the practical limit: Actual modeling: you can arrange assets, you cannot make them.

## Engineering roadmap
1. Phase 1, architecture and data: Stack, no substitutions: Vite + TypeScript + vanilla Three.js (latest). No React, no framework. No backend, no accounts, no telemetry, no network calls at all. Model source assets, editable projects, operations, and exported versions; keep stable source IDs and timestamps.
2. Phase 2, implement: Left sidebar: scene outliner listing objects by name, click to select, double click to rename, visibility toggle per object.
3. Phase 3, implement: Right sidebar: numeric inputs for position, rotation (degrees) and scale of the selection, kept in sync with the gizmo in both directions.
4. Phase 4, review and output: Lighting panel: one directional light with intensity, color and a draggable azimuth/elevation, plus ambient intensity. Drag and drop an .hdr file to set the environment via RGBELoader and PMREMGenerator, with an exposure slider. Render button: renders the current view at a chosen resolution (up to 4x canvas size) and downloads a PNG. Also an Export glTF button using GLTFExporter.
5. Phase 5, recovery and acceptance: Save/load the scene as a JSON file: asset filenames plus transforms plus light settings. On load, re-prompt for any asset files it cannot find instead of failing silently. Verify this invariant with a saved fixture: Undo must restore the previous visual state; export dimensions and asset hash must match the saved project. State the practical limit: Actual modeling: you can arrange assets, you cannot make them.

## Paid-product capabilities outside this build
- Actual modeling: you can arrange assets, you cannot make them
- A trustworthy undo/redo history across every operation
- Material and shader editing beyond a handful of sliders
- Viewport performance work: shadows, culling, LOD, big scenes
- Whatever asset library, templates or generation features ship with the paid product

## Implementation prompt
Build a local-only 3D scene composer as a web app. This is a personal tool, not a product.

Stack, no substitutions: Vite + TypeScript + vanilla Three.js (latest). No React, no framework. No backend, no accounts, no telemetry, no network calls at all.

What it does:
1. Full-window WebGL canvas with an orbit/pan/zoom camera (OrbitControls) and a grid helper.
2. Drag and drop .glb or .gltf files onto the canvas to add them to the scene. Use GLTFLoader and fit the camera to the new object's bounding box on first load.
3. Click an object to select it. Show TransformControls with keyboard shortcuts: W translate, E rotate, R scale, X toggle world/local space, Delete removes the selection.
4. Left sidebar: scene outliner listing objects by name, click to select, double click to rename, visibility toggle per object.
5. Right sidebar: numeric inputs for position, rotation (degrees) and scale of the selection, kept in sync with the gizmo in both directions.
6. Lighting panel: one directional light with intensity, color and a draggable azimuth/elevation, plus ambient intensity. Drag and drop an .hdr file to set the environment via RGBELoader and PMREMGenerator, with an exposure slider.
7. Shadows: soft shadow map from the directional light, plus a toggleable ground plane that receives shadows only.
8. Undo/redo (Ctrl+Z / Ctrl+Shift+Z) for add, delete, transform and rename. Implement it as a plain command stack, do not try to diff the whole scene graph.
9. Save/load the scene as a JSON file: asset filenames plus transforms plus light settings. On load, re-prompt for any asset files it cannot find instead of failing silently.
10. Render button: renders the current view at a chosen resolution (up to 4x canvas size) and downloads a PNG. Also an Export glTF button using GLTFExporter.

Explicitly out of scope, do not build these: mesh editing or sculpting, UV tools, material/shader authoring beyond base color and roughness sliders, animation, physics, any AI generation, any multi-user or cloud sync.

Deliver: working dev server on npm run dev, a README with the shortcut list, and no .env because there are no secrets. Keep it to a handful of files with a clear scene-state module; do not invent an architecture.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.