refactoring, linting, formatting

README

@@ -75,17 +75,17 @@ This makes the project especially useful for self-hosted environments, public-se
 
 ### Keyboard shortcuts
 
-| Shortcut | Action |
-| --- | --- |
-| `F1` / `?` | Open in-app help and tutorial |
-| `Ctrl`/`⌘` + `A` | Select all pages |
-| `Delete` / `Backspace` | Delete selected pages after confirmation |
-| `Esc` | Clear the current selection or close an open dialog |
-| `Ctrl`/`⌘` + `Z` | Undo |
-| `Ctrl`/`⌘` + `Shift` + `Z` | Redo |
-| `Ctrl`/`⌘` + `Y` | Redo |
-| `←` / `→` in preview | Move to previous / next page |
-| `Esc` in preview | Close preview |
+| Shortcut                   | Action                                              |
+| -------------------------- | --------------------------------------------------- |
+| `F1` / `?`                 | Open in-app help and tutorial                       |
+| `Ctrl`/`⌘` + `A`           | Select all pages                                    |
+| `Delete` / `Backspace`     | Delete selected pages after confirmation            |
+| `Esc`                      | Clear the current selection or close an open dialog |
+| `Ctrl`/`⌘` + `Z`           | Undo                                                |
+| `Ctrl`/`⌘` + `Shift` + `Z` | Redo                                                |
+| `Ctrl`/`⌘` + `Y`           | Redo                                                |
+| `←` / `→` in preview       | Move to previous / next page                        |
+| `Esc` in preview           | Close preview                                       |
 
 Keyboard shortcuts are ignored while typing in form fields.
 
@@ -115,25 +115,35 @@ browser  <-- HTTPS -->  static web server / reverse proxy  -->  built app assets
 
 There is no application server to operate. Administrators only need to host the built files from `dist/`.
 
-### Build from source
+### Build and test from source
 
 ```bash
 npm ci
+npm run check
+```
+
+`npm run check` runs the main project quality gate:
+
+```bash
+npm run typecheck
+npm run lint
+npm run test
 npm run build
 ```
 
 The production build is written to `dist/`.
 
-To preview the production build locally:
+Useful individual development commands:
 
 ```bash
-npm run preview
-```
-
-For development:
-
-```bash
-npm run dev
+npm run dev           # start the Vite development server
+npm run preview       # preview the production build locally
+npm run test          # run tests once
+npm run test:watch    # run tests in watch mode
+npm run typecheck     # run TypeScript without emitting files
+npm run lint          # run ESLint
+npm run format        # format the project with Prettier
+npm run format:check  # verify Prettier formatting
 ```
 
 ### Static hosting
@@ -219,11 +229,13 @@ The current development baseline is:
 v0.2.0 — Browser-only PDF workspace baseline
 ```
 
+This baseline is preserved through a staged refactoring path. Workspace state, thumbnail handling, generated download URLs, page-grid components, tests, type-checking, linting, and formatting are now separated enough to support the next feature phase without turning `App.tsx` back into a monolith.
+
 ## Project structure
 
 ```text
 src/
-  App.tsx                         Main application state and orchestration
+  App.tsx                         Main application orchestration and UI wiring
   components/
     ActionDialog.tsx              Reusable confirmation/action dialog
     ActionsPanel.tsx              Export, extract, and split actions