code-by-sia · code-by-sia · May 30, 2026 · May 30, 2026
diff --git a/README.md b/README.md
@@ -10,11 +10,12 @@ OpenWebSheet is an open-source, web-based spreadsheet application. It runs in th
 
 1. Open the hosted app: <https://code-by-sia.github.io/OpenWebSheet/>
 2. Install the PWA using the install icon in the browser address bar.
-3. Download the sample file: <https://code-by-sia.github.io/OpenWebSheet/demo/DEMO.ows>
+3. Download the sample file: <https://code-by-sia.github.io/OpenWebSheet/DEMO.ows>
 4. Use the folder/load icon in the app to open the sample `.ows` file.
 
 ## Features
 
+- React application shell with shadcn-style controls
 - Canvas-based spreadsheet rendering
 - Basic cell content editing
 - Borders
@@ -76,15 +77,17 @@ Additional documentation is available in the [`docs/`](docs/) directory:
 
 - [Development guide](docs/development.md)
 - [Architecture overview](docs/architecture.md)
+- [UI structure](docs/ui-structure.md)
 - [User guide](docs/user-guide.md)
 - [Supported formats](docs/supported-formats.md)
+- [Troubleshooting](docs/troubleshooting.md)
 
 ## Contributing
 
 1. Create an issue or choose an existing one.
 2. Create a focused branch for the change.
 3. Keep changes small and reviewable.
-4. Run linting and tests before opening a pull request.
+4. Run tests, type checking, and the production build before opening a pull request.
 5. Update documentation when behavior, setup, or architecture changes.
 
 ## License

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -2,19 +2,32 @@
 
 ## High-Level Components
 
-- UI Layer (React-based)
-- Spreadsheet core logic
-- Canvas renderer
-- Formula evaluation
-- Import/export subsystem
-- PWA integration
+- React UI layer under `src/app`, `src/features`, and `src/shared`.
+- Spreadsheet core logic under `src/lib/core`.
+- Canvas rendering under `src/lib/rendering`.
+- UI-to-core adapter logic under `src/lib/UI.ts` and `src/features/sheet`.
+- Formula evaluation under `src/lib/core/formula`.
+- Native `.ows` document import/export helpers under `src/features/document-io`.
+- PWA integration through `src/registerServiceWorker.ts` and generated static assets.
 
 ## Design Principles
 
 - Keep spreadsheet logic independent from UI frameworks.
 - Minimize coupling between rendering and business logic.
 - Allow future UI migrations without rewriting the spreadsheet engine.
+- Keep React components small and composed by feature area.
+- Keep reusable UI primitives in `src/shared/ui`.
+- Keep Tailwind class composition in `src/app/styles.css`.
+
+## Runtime Flow
+
+1. `src/main.ts` mounts the React app.
+2. `src/app/App.tsx` owns top-level UI state for file mode, selection, formula bar value, and active appearance.
+3. `SpreadsheetSurface` creates the existing `UI` adapter with a DOM element.
+4. `UI` creates the canvas renderer and a `UIHandlerController`.
+5. Ribbon and formula bar actions call `UI.execCmd`, which forwards commands to the spreadsheet core.
+6. The core document emits changes back through `UI.addOnChangeEventListener`, and React updates the ribbon/formula state.
 
 ## Future Direction
 
-A future React migration should focus on the UI layer only while preserving the existing spreadsheet core.
+Advanced formula support, OpenDocument import/export, and richer spreadsheet interactions should extend the core APIs first, then expose those capabilities through the React features.
diff --git a/docs/development.md b/docs/development.md
@@ -1,34 +1,66 @@
 # Development Guide
 
+## Prerequisites
+
+- Node.js 18 or newer
+- npm
+
 ## Setup
 
 ```bash
 npm install
 npm run dev
 ```
 
+The development app is served from the Vite base path:
+
+```text
+http://127.0.0.1:5173/OpenWebSheet/
+```
+
 ## Build
 
 ```bash
 npm run build
 ```
 
+The production build writes static assets to `docs/` so GitHub Pages can serve the app.
+
 ## Testing
 
 ```bash
 npm test
 ```
 
+Use watch mode while working on UI behavior:
+
+```bash
+npm run test:watch
+```
+
 ## Type Checking
 
 ```bash
 npm run typecheck
 ```
 
+## Useful Scripts
+
+- `npm run dev`: start the local Vite server.
+- `npm run build`: create the production build in `docs/`.
+- `npm run preview`: preview the production build locally.
+- `npm test`: run Vitest once.
+- `npm run typecheck`: run TypeScript without emitting files.
+
 ## Contribution Workflow
 
 1. Create an issue.
 2. Create a branch.
 3. Implement changes.
 4. Run tests and type checking.
-5. Open a pull request.
+5. Run the production build when changing UI, assets, or configuration.
+6. Open a pull request with a summary and verification notes.
+
+## Build Warning
+
+The production build currently reports a direct `eval` warning from `src/lib/core/formula/Evaluator.ts`. The warning is known, and the build still succeeds. Changes to the formula engine should address that warning deliberately instead of hiding it in unrelated work.
diff --git a/docs/supported-formats.md b/docs/supported-formats.md
@@ -1,13 +1,25 @@
 # Supported Formats
 
-## Current
+## Current Format
 
-- .ows (OpenWebSheet native format)
+### `.ows`
+
+OpenWebSheet's native format stores workbook data as JSON. It is the only supported import/export format today.
+
+Supported data includes:
+
+- Sheets and cells
+- Cell values
+- Basic formulas
+- Merged cells
+- Cell appearance used by the current renderer
 
 ## Planned
 
-- OpenDocument Spreadsheet (.ods)
+- OpenDocument Spreadsheet (`.ods`)
 
 ## Notes
 
-Compatibility and import/export behavior should be documented as support expands.
+- `.ows` is intended for OpenWebSheet interoperability, not compatibility with other spreadsheet applications.
+- `.ods` support is tracked separately and should include fixtures and interoperability tests when implemented.
+- Unsupported features should fail gracefully and be documented as format support expands.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -0,0 +1,40 @@
+# Troubleshooting
+
+## The Dev Server Opens A Blank Page
+
+Open the app at the Vite base path:
+
+```text
+http://127.0.0.1:5173/OpenWebSheet/
+```
+
+Opening `http://127.0.0.1:5173/` directly may not load the app because the project is configured for GitHub Pages under `/OpenWebSheet/`.
+
+## Dependencies Fail To Install
+
+Use a current Node.js 18+ runtime, then reinstall dependencies:
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+Only remove `package-lock.json` when intentionally refreshing dependency resolution.
+
+## Production Build Shows An Eval Warning
+
+`npm run build` currently warns about direct `eval` in `src/lib/core/formula/Evaluator.ts`. This is known formula-engine behavior and does not fail the build.
+
+## Tests Cannot Find DOM APIs
+
+Vitest is configured with `jsdom` in `vite.config.ts`. If DOM APIs are missing, confirm tests are running through `npm test` and not through a bare TypeScript or Node command.
+
+## GitHub Pages Assets Look Stale
+
+Run a production build before publishing:
+
+```bash
+npm run build
+```
+
+The generated files in `docs/` are part of the static GitHub Pages deployment.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -1,17 +1,44 @@
 # User Guide
 
+## Opening The App
+
+Open the hosted app at <https://code-by-sia.github.io/OpenWebSheet/> or run it locally with `npm run dev`.
+
 ## Opening Files
 
-Open the application and load an OWS spreadsheet file.
+Use the folder button in the Home ribbon to load an `.ows` file. A sample file is available at <https://code-by-sia.github.io/OpenWebSheet/DEMO.ows>.
+
+## Saving Files
+
+Use the save button in the Home ribbon to download the current workbook as an `.ows` file.
+
+## Local Storage Mode
+
+The Home ribbon includes a local storage mode. In local mode, document changes are saved in the browser's local storage. Return to file mode before using download/upload workflows.
 
 ## Editing
 
-Select cells and modify their content.
+Select a cell on the sheet and edit its value through the formula bar. The formula bar shows the selected cell name and the current value.
 
 ## Formatting
 
-Borders, merge and split operations are supported.
+The Home ribbon supports:
+
+- Font family and size
+- Bold, italic, and underline
+- Text and fill color
+- Horizontal alignment
+- Merge and split cells
+- Border color and border presets
 
 ## Formulas
 
 Basic formula support is available. Advanced formula capabilities are tracked as a separate roadmap item.
+
+## View Layout
+
+The View ribbon includes layout controls for normal/page-oriented views and display toggles. These controls establish the UI surface for layout features; deeper renderer behavior will expand over time.
+
+## PWA Installation
+
+Modern browsers can install OpenWebSheet as a Progressive Web App. Use the install control in the address bar or browser menu while visiting the hosted app.