Worldshaper/README.md

# Worldshaper

Canonical React + TypeScript worldbuilding studio and API for New RPG.

## Features

- Load content types from `/api/types`.
- Load selected content payload from `/api/content/:type`.
- Edit raw JSON.
- Save JSON back to `/api/content/:type`.

## Runtime

- Vite dev server runs on `http://localhost:4170`.
- API/app server runs on `http://localhost:5180` from `server.js` in this folder.
- `vite.config.ts` proxies `/api` to `http://localhost:5180`.
- Override the API/app port with `PORT=<port>` when needed.

## Content Location

- Preferred: place content beside `server.js` at `tools/worldshaper/content/`.
- Required image folder for `/api/images`: `tools/worldshaper/content/Images/` (capital `I`).
- Optional override: set `CONTENT_ROOT=/absolute/path/to/content` before starting the API.
- Fallbacks remain for legacy layouts, but local `tools/worldshaper/content` is checked first.

## Local development

From this folder:

1. `npm install`
2. In one terminal: `npm run dev:api`
3. In another terminal: `npm run dev`

## Build

- `npm run build`
- `npm run clean:workspace` removes generated bundles, logs, and disposable local artifacts.

## Project Structure

This repo is easiest to manage when the root stays limited to the live app and its source-of-truth assets:

- `src/` React, TypeScript, and editor code
- `content/` canonical game content, schemas, worlds, and images metadata
- `data/` editor metadata and local settings payloads
- `scripts/` maintenance, validation, and deployment helpers
- `public/` static assets copied by Vite

Generated or disposable folders such as `dist/`, `output/`, `backups/`, and `Release/` should not be treated as source-of-truth project files.

## Scope guardrails

- Keep files small and modular.
- No cross-file autofix/migration tooling in V2.1.
- Finish core CRUD + validation workflows before adding advanced UX.