Manage frontend project template updates (#1)

* refactor: apps/packages layout; add A+ template sync; update aliases, vite, tailwind, docs

* No changes detected, no commit message needed.

Co-authored-by: sorrust <[email protected]>

---------

Co-authored-by: Cursor Agent <[email protected]>

Author: tobenot

.template-source

@@ -0,0 +1,3 @@
+TEMPLATE_REPO=https://your.host/your-template.git
+TEMPLATE_REF=main
+MANIFEST_FILE=sync.manifest

README.md

@@ -1,120 +1,80 @@
-# Carrot Web Game Template
+# Carrot Web Game Template (Apps/Packages Layout)
 
-![Made with React & TypeScript](https://img.shields.io/badge/Made%20with-React%20%26%20TypeScript-blue.svg?style=for-the-badge&logo=typescript)
-![Vite](https://img.shields.io/badge/Vite-B73BFE?style=for-the-badge&logo=vite&logoColor=white)
-![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)
+A simple, modular, and extensible web game template based on React, TypeScript, and Vite. Optimized for itch.io and GitHub Pages. This repo is organized for easy reuse and low-maintenance updates.
 
-A simple, modular, and extensible web game template based on React, TypeScript, and Vite. Designed for rapid prototyping and building games for platforms like **itch.io** and **GitHub Pages**.
+- Game apps live in `apps/*` (demo apps included)
+- Reusable code lives in `packages/*` and shared configs in `configs/*`
+- Consumers can either manually copy changes or run a tiny sync script (A+ workflow)
 
-> **Note**: For detailed technical documentation, please refer to our **[Full Documentation](./docs/README.md)**.
+## Quick Start
 
-> **[➡️ Try the Live Demo!](https://tobenot.top/Basic-Web-Game/)**
-
-![Demo Screenshot](./docs/assets/screenshot.webp)
-
-Play Beyond Books on Itch.io based on this project!
-
-[![Play Beyond Books on Itch.io](./docs/assets/bb_screenshot.webp)](https://tobenot.itch.io/beyond-books)
-
----
-
-## Why Carrot Web Game Template?
-
-While you can always build a project from scratch with `create-react-app`, this template is specifically optimized for web game development, saving you from common setup headaches:
-
--   **Game-Centric Architecture**: Separates the core engine (`carrot`) from game-specific logic (`games`), promoting organized, reusable code.
--   **One-Command Deployments**: Built-in scripts for **itch.io** and **GitHub Pages** that automatically handle tricky path configurations, letting you focus on your game.
--   **Essential Components Included**: Comes with pre-built, customizable components like `ImageLoader`, `TypewriterText`, and `GameShell` for aspect ratio and screen orientation control.
-
-## 🗺️ Roadmap & TODO
-
-This template is actively evolving. Here are the key features planned for the near future. Contributions are highly welcome!
-
--   [ ] **Core Systems**
-    -   [ ] **LLM/AI Integration**: A generic module for calling large language models, enabling dynamic narrative and NPC interactions.
-    -   [ ] **Audio Manager**: A robust service for handling background music and sound effects.
-    -   [ ] **Localization (i18n) System**: A simple framework for supporting multiple languages.
--   [ ] **Performance Optimization**: Focus on code splitting and asset optimization for faster load times.
--   [ ] **Backend Support**: Develop a companion backend template for handling player data or game state persistence. (Vision: [Basic-Web-Game-Backend](https://github.com/tobenot/Basic-Web-Game-Backend))
-
-## ✨ Features
-
--   **Modular Architecture**: Core engine (`carrot`) is separated from game-specific logic (`games`).
--   **React + TypeScript**: Modern, type-safe UI development with reusable core components.
--   **Vite Powered**: Fast development server and optimized builds.
--   **Automated Deployments**:
-    -   Built-in script (`npm run build:itch`) to version, build, and package your game for **itch.io**.
-    -   Streamlined deployment to **GitHub Pages** via `npm run deploy`.
--   **Easy to Customize**: A clean starting point for your next web game.
-
-## 🚀 Getting Started
-
-### Prerequisites
-
--   Node.js 18+
--   npm or yarn
-
-### Installation & Development
-
-1.  Clone this repository or use it as a template.
-2.  Install dependencies:
-    ```bash
-    npm install
-    ```
-3.  Start the development server:
-    ```bash
-    npm run dev
-    ```
-    Your game will be running at `http://localhost:5173`.
-
-## 📦 Building for Production
-
-To create a production-ready build, run:
+1. Install deps
+```bash
+npm install
+```
+2. Dev server
+```bash
+npm run dev
+```
+3. Build
 ```bash
 npm run build
 ```
-This will generate a `dist` directory with all your game files.
 
--   **For itch.io**: Use `npm run build:itch`. This command automatically versions, builds, and packages your game into a `.zip` file, ready for upload.
--   **For GitHub Pages**: Before deploying, ensure the `name` field in `package.json` matches your GitHub repository name. Then, use `npm run deploy`.
-
-> For more details on build commands and local testing, see the [Build and Deployment section in our documentation](./docs/05-build-and-deploy.md).
-
-## 📂 Project Structure
+## Project Structure
 
 ```
 /
-├── dist/               # Production build output
-├── docs/               # Detailed project documentation
-├── public/             # Static assets (images, fonts, config files)
-│   └── version.json    # Auto-versioning for itch.io builds
-├── src/                # Source code
-│   ├── carrot/         # The core engine/template
-│   ├── games/          # Houses all specific game projects
-│   └── ...
-├── scripts/
-│   └── build-itch.js   # Script for versioning and packaging for itch.io
-├── .github/            # GitHub-specific files (e.g., workflows)
-└── ...
+├── apps/
+│   └── web/                 # Main web app (Vite root)
+│       ├── public/
+│       ├── src/
+│       │   ├── games/       # Demo apps (carrot-card-demo, demo-with-backend, portal)
+│       │   └── ...
+│       └── index.html
+├── packages/
+│   ├── ui/                  # Reusable UI components (ImageLoader, TypewriterText, GameShell, ...)
+│   └── services/            # Reusable services (ResourceLoader, ...)
+├── scripts/                 # Build and helper scripts
+│   ├── build-itch.js
+│   └── update-from-template.sh
+├── sync.manifest            # Whitelist for template sync (A+)
+├── docs/                    # Detailed documentation
+├── vite.config.ts           # Vite config points to apps/web as root, outputs to /dist
+└── tailwind.config.js       # Tailwind scans apps and packages
 ```
 
-A more detailed breakdown of the project structure is available in [our documentation](./docs/02-project-structure.md).
+## A+ Template Sync (optional, zero lock-in)
 
-## 🎨 Customization
+- For teams preferring manual copy, keep doing that.
+- Alternatively, use the included script to copy only template-managed files from this repo.
 
-To create your own game, follow the detailed guide in [our documentation](./docs/04-creation-and-extension.md).
-
-## 🤝 Contributing
+Configure your project (optional):
+```
+# .template-source
+TEMPLATE_REPO=https://your.host/your-template.git
+TEMPLATE_REF=main
+MANIFEST_FILE=sync.manifest
+```
 
-Contributions are welcome! If you have ideas for improvements or find a bug, please first read our **[Contribution Guide](./docs/06-contributing.md)** and check out the issues page.
+Run sync in your project root:
+```bash
+bash scripts/update-from-template.sh
+```
+- Backs up overwritten files to `.template_backups/<timestamp>`
+- Copies only paths listed in `sync.manifest`
 
-### 💡 Help Wanted
+## Build & Deploy
 
-We are actively looking for help in the following areas:
--   **More Core Components**: Ideas for reusable UI or logic components (e.g., `SoundManager`, `SpriteAnimation`).
--   **Documentation**: Improving existing docs or adding translations.
--   **Game Samples**: Creating more diverse game examples to showcase the engine's capabilities.
+- itch.io: `npm run build:itch` produces `/dist/*.zip`
+- GitHub Pages: `npm run build:pages && npm run deploy`
 
-## 📄 License
+## Notes
+- `import.meta.env.BASE_URL` is respected; `ResourceLoader` uses it to resolve assets.
+- Tailwind scans `apps/web` and `packages/*`.
+- Aliases:
+  - `@` -> `apps/web/src`
+  - `@ui` -> `packages/ui/src`
+  - `@services` -> `packages/services/src`
 
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+See `docs/` for details.